Group Managed Service Account Playbook Usage Guide

Requirements

The AD operations run from the AD management host — a Windows Server that can reach the domain controllers (defaults to the first Kuiper server; in inventories without an app_kuiper group, pass -e ad_management_host=<host>). The playbook installs the RSAT-AD-PowerShell feature on it automatically.

Prerequisites

A domain account with permissions to create security groups and service accounts in Active Directory must be available.
Define your gMSA definitions in extra_vars/gmsas.yml. See Sample Variables below.
The following variables must be defined. The variables should be all uppercase when defined as environment variables, but all lowercase when defined in host_vars, group_vars, or an Ansible vault.

Environment VariablesAnsible Variables

# REQUIRED VARIABLES
export DOMAIN_NAME='sapphire.dev'
export DOMAIN_ADMIN_USER='sapphire\adminuser'
export DOMAIN_ADMIN_PASSWORD='PASSWORD'

# REQUIRED VARIABLES
domain_name: 'sapphire.dev'
domain_admin_user: 'sapphire\adminuser'
domain_admin_password: 'PASSWORD'

Usage

Define your gMSA definitions in extra_vars/gmsas.yml using the sample variables below.
Run the playbooks/create-gmsa.yml playbook. The playbook will create the AD security group, add the specified members, and create the gMSA with the group as the allowed principal to retrieve the password. The AD operations are delegated to the AD management host; limit the play to the gMSA member hosts so the end-of-play Kerberos ticket purge (which applies the new group membership without a reboot) runs on them.
```
ansible-playbook --limit=epic-kpr-sapph1.sapphire.dev playbooks/create-gmsa.yml -e @extra_vars/gmsas.yml
```

Optional Variables

The following optional variables can be passed to override default AD paths and group ownership:

Variable	Description
`security_group_path`	OU path for the security group (e.g. `OU=Groups,DC=sapphire,DC=dev`)
`service_account_path`	OU path for the gMSA (e.g. `OU=Service Accounts,DC=sapphire,DC=dev`)
`managed_by`	AD identity to set as the group's `Managed By` attribute

Inventory Groups for `members_group`

When using members_group, the group name must match an Ansible inventory group. This repo derives its application groups (app_kuiper, app_nginx, app_systempulse, …) from the Terraform application VM tag, directly in the source inventory (inventory.aws_ec2.yml / inventory.azure_rm.yml) — no manual maintenance required as hosts are added or removed. Tag a VM application: kuiper and it joins app_kuiper automatically; that group name is what you pass to members_group. Because membership reflects live cloud inventory, the AD group stays in sync as hosts are added or replaced.

See Application & Environment Groups for the full picture. To verify the groups available to use in members_group, run:

ansible-inventory --graph

Sample Variables

extra_vars/gmsas.yml defines the gMSAs to create. Each entry requires a name (the gMSA account name), a group (the AD security group that controls which hosts can retrieve the password), and at least one of members or members_group to populate that group.

Specifying Members

members and members_group can be used independently or combined — duplicates are automatically removed.

members_group — an Ansible inventory group; short hostnames are derived automatically (e.g. hosts in epic_kpr resolve to epic-kpr-sapph1, epic-kpr-sapph2)
members — an explicit list of short AD computer names (without the trailing $)

# gmsa_definitions supports two ways to specify members (combinable):
#   members:       explicit list of short AD computer names
#   members_group: an Ansible inventory group; short names are derived automatically
gmsa_definitions:
  - name: kuiper-gmsa
    group: KuiperAllowedHosts
    members_group: epic_kpr

  # Mix both: group provides the base, members adds extras not in inventory
  # - name: kuiper-gmsa
  #   group: KuiperAllowedHosts
  #   members_group: epic_kpr
  #   members:
  #     - some-extra-host

  # Manual-only
  # - name: wbs-gmsa
  #   group: WbsAllowedHosts
  #   members:
  #     - epic-msql-sapph