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.

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.

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"

Tag	Includes	Description
`install`	`prerequisites`, `dependencies`, `install_kuiper`	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.