Kuiper Role Usage Guide

Requirements

None

Prerequisites

Microsoft SQL must be installed on the multipurpose SQL server, and the kuiper database must be created with the necessary permissions and configuration. This can be done using the Microsoft SQL role.
Required AD accounts (e.g. GMSAs) must be created. The create-gmsa.yml playbook can be used to create GMSAs in Active Directory.
The customer must provide a copy of the Kuiper MSI.
Both the user account running the playbook (installing Kuiper) and the Kuiper GMSA must have permissions to the kuiper database on the multipurpose SQL server.
The following variable must be defined. This variable is almost always already defined unless kerberos authentication is used. If Kerberos is used, the password must be provided due to the double hop issue. The variables should be all uppercase when defined as environment variables, but all lowercase when defined in host_vars or group_vars files or an ansible vault. Use a secure password generator to create strong passwords.

Environment VariablesAnsible Variables

# REQUIRED VARIABLES
export SERVER_ADMIN_PASSWORD='PASSWORD_OF_USER_RUNNING_KUIPER_PLAYBOOK'

# REQUIRED FOR KUIPER CLUSTERS, BUT RECOMMENDED FOR ALL INSTALLATIONS
export KUIPER_AES_PASSWORD='USE_PASSWORD_GENERATOR'

# OPTIONAL VARIABLES
export KUIPER_INSTALL_USER='DOMAIN_USER_TO_INSTALL_KUIPER'
export KUIPER_INSTALL_PASSWORD='PASSWORD_OF_DOMAIN_USER_TO_INSTALL_KUIPER'

# REQUIRED VARIABLES
server_admin_password: 'PASSWORD_OF_USER_RUNNING_KUIPER_PLAYBOOK'

# REQUIRED FOR KUIPER CLUSTERS, BUT RECOMMENDED FOR ALL INSTALLATIONS
kuiper_aes_password: 'USE_PASSWORD_GENERATOR'

# OPTIONAL VARIABLES
kuiper_install_user: 'DOMAIN_USER_TO_INSTALL_KUIPER'
kuiper_install_password: 'PASSWORD_OF_DOMAIN_USER_TO_INSTALL_KUIPER'

Kuiper Install User and Password

The kuiper_install_user and kuiper_install_password variables are optional. If not provided, the playbook will attempt to use the user running the playbook to install Kuiper.

Kuiper AES Password

The kuiper_aes_password variable is only required if multiple Kuiper instances are being installed. In a load balanced Kuiper cluster, each instance must have AES encryption enabled with the same AES password. It is used as the encryption key for the Kuiper database.

The role enforces this: a prerequisites preflight fails before anything is staged when no AES password is set and the install targets more than one machine (a load balanced deployment, as determined by kuiper_load_balanced below). Set an AES password, or set kuiper_load_balanced: false if the hosts install against independent Kuiper databases.

Even if only a single Kuiper instance is being installed, it is still recommended to set an AES password to simplify future scaling, reinstalls and migrations to new servers.

Load Balanced Deployments

kuiper_load_balanced states whether the hosts in the play serve one Kuiper instance behind a load balancer — that is, whether they share a single Kuiper database. Left unset (the default) it is derived from the play itself: more than one host running the role with a kuiper_sql_string means load balanced. Set it explicitly for the two cases the play cannot show:

kuiper_load_balanced: true   # --limit to one member of a load balanced set
kuiper_load_balanced: false  # several hosts, each with its own Kuiper database

The role refuses kuiper_answer_prompts: true on a load balanced deployment, and fails before anything is staged. That option installs headlessly by answering KuiperSetup's interactive prompts yes — needed when the app pool is a passwordless GMSA or the database is Azure SQL, where the prompts otherwise block forever in session 0 — but one of the prompts it dismisses is the ASP.NET SQL session state schema install failing. That is benign for a single server and not for a load balanced set, whose members need session state shared through SQL.

Tags

A tag must be specified when running this role. Running without --tags or with --tags all is not supported and will result in an error.

Tag	Includes	Description
`install`	`prerequisites`, `dependencies`, `install_kuiper`, `bootstrap_admin`	Runs all tasks required to install Kuiper.
`prerequisites`		Runs only the prerequisites tasks (resolve install user/password, validate SQL connectivity).
`dependencies`		Runs only the dependencies tasks (IIS features, group memberships, Kerberos ticket purge).
`install_kuiper`		Runs only the MSI installation tasks.
`bootstrap_admin`		Grants a domain security group Kuiper Super Administrator access through the REST security-group API, logging in as the install user (a no-op unless `kuiper_super_admin_group_name` is set).
`configure`		Applies instance settings through the Kuiper REST API (credentials, LDAP, environments, security groups, package sources, the Base Package Source and its file staging, environment/Satellite settings, perimeter authentication UI, System Pulse). Deployment settings (e.g. the `enableNtlm` "Remote authentication" toggle) are applied first; the WSMan TrustedHosts prerequisite for workgroup machines is applied host-locally on every Kuiper server. See API Configuration.
`fleet`	`machines`, `groups`, `certificates`, `packages`	Applies fleet topology. Assumes `configure` has run at least once. A full desired-state apply is `--tags configure,fleet`.
`machines`		Registers machines with Kuiper (explicit entries and group auto-enrollment). A registered machine only picks up work at its next Satellite check-in (five minutes by default), so follow this with the `epic_ecsa` role's `satellite_checkin` tag against the machines themselves to have Kuiper hand out the work immediately.
`groups`		Creates application groups and applies group machine and environment membership.
`certificates`		Imports certificates into Kuiper — either a PFX staged on the control node or one issued during the run through the `certificate_authority` role — and deploys/binds them to machines. See API Configuration.
`packages`		Deploys the latest available package to each group with `deploy_latest_package: true` (add-if-absent). See API Configuration.

Built-in reference (ansible-doc)

The role ships an argument spec documenting every user-facing variable (type, default, environment-variable fallback) and what each tag does. View it from any workspace with the role installed:

ansible-doc -t role kuiper

The spec also validates variables at role entry on every tagged run: kuiper_install_source_file and kuiper_sql_string are required, and a run missing them fails immediately with a clear message instead of partway through the install. Keep the spec (meta/argument_specs.yml in the role repo) and this guide in sync when the role's variables or tags change.

Usage

Create a file in host_vars for each host Kuiper will be installed on if it doesn't already exist. The file should be named after the host's inventory name (e.g. host_vars/abckpr01.yml).
A Kuiper MSI is required to install Kuiper. The playbook supports delivering it via HTTP(S) (e.g. storage account, S3 bucket, caddy file server, etc.) or by uploading it from the Ansible control node.
- When uploading files from the Ansible control node, place the MSI in a "shared files" directory on the ansible control node (usually a location on the container's persistent storage in /home/ansible/source/files) and set shared_files_directory in group_vars to the path of the directory. If the kuiper_install_source_dir variable is defined in host_vars, it will override shared_files_directory for that host.
- If the value of shared_files_directory or kuiper_install_source_dir is a URL, the playbook will attempt to download the MSI from that location. If it's a local file path, the playbook will attempt to upload the MSI from the Ansible control node. kuiper_install_source_file should be set to the name of the MSI file (e.g. 'Epic May 2026 Kuiper Fix Package 5.msi').
Update each hosts host_vars with the necessary variables using the sample variables below or navigate to templates to see more examples.

Run the playbooks/deploy-kuiper.yml playbook with the appropriate tag.

ansible-playbook --limit=epic-kpr-sapph1.sapphire.dev playbooks/deploy-kuiper.yml --tags install

Sample Variables

kuiper_install_source_file: Epic May 2026 Kuiper Fix Package 5.msi
kuiper_gmsa_user: sapphire\kuiper-gmsa$
kuiper_sql_string: "Server=epic-msql-sapph.sapphire.dev;Database=Kuiper;Integrated Security=True"

After upgrading Kuiper: refresh the perimeter-auth assets

Kuiper ships the Perimeter Authentication Configuration tool, and Epic versions its nginx template generator alongside Kuiper releases. The perimeter_auth role's Epic assets are generated from that tool and committed at a specific generator version, so a Kuiper upgrade may make them outdated.

After upgrading, re-run the refresh and review the diff:

ansible-playbook roles/perimeter_auth/tools/refresh-from-kuiper.yml -e kuiper_host=<kuiper> -e pauth_template_version=<version>

Then review git diff — that is exactly what Epic changed.

Full procedure, including what to do with the resulting diff: Perimeter Auth — where the Epic configuration comes from.