GMSASpec is Poorly documented

[kaushalendra-kumar]

In the section "Install GMSA cred spec", the placeholder values/comments for the actual GMSACredentialSpec are poorly documented. We tried to implement this and our container got in to ContianerCreating state.

Consider:

apiVersion: windows.k8s.io/v1
kind: GMSACredentialSpec
metadata:
  name: aks-gmsa-spec  # This name can be changed, but it will be used as a reference in the pod spec
credspec:
  ActiveDirectoryConfig:
    GroupManagedServiceAccounts:
    - Name: $GMSA_ACCOUNT_USERNAME
      Scope: $NETBIOS_DOMAIN_NAME
    - Name: $GMSA_ACCOUNT_USERNAME
      Scope: $DNS_DOMAIN_NAME
    HostAccountConfig:
      PluginGUID: '{CCC2A336-D7F3-4818-A213-272B7924213E}'
      PortableCcgVersion: "1"
      PluginInput: "ObjectId=$MANAGED_ID;SecretUri=$SECRET_URI"  # SECRET_URI takes the form https://$akvName.vault.azure.net/secrets/$akvSecretName
  CmsPlugins:
 - ActiveDirectory
  DomainJoinConfig:
    DnsName: $DNS_DOMAIN_NAME
    DnsTreeName: $DNS_ROOT_DOMAIN_NAME
    Guid:  $AD_DOMAIN_OBJECT_GUID
    MachineAccountName: $GMSA_ACCOUNT_USERNAME
    NetBiosName: $NETBIOS_DOMAIN_NAME
    Sid: $GMSA_SID

In particular the following needs to be more clear:

• $GMSA_SID is actually $AD_DOMAIN_OBJECT_SID; using the SID of the GMSA account as indicated by the placeholder results in an invalid setup.
• $MANAGED_ID would be better documented as $MANAGED_IDENTITY_OBJECT_ID. Although this is present elsewhere in the page as the same variable, it's also not explicitly declared in this section and you can't access it as a "variable" in the way a beginning $ would lead you to believe.
• It's not clear whether or not you need the trailing $ in $GMSA_ACCOUNT_USERNAME, which you do in 99% of cases (but not this one)

Having a completed example without the placeholders would be a big benefit, such as:

apiVersion: windows.k8s.io/v1
kind: GMSACredentialSpec
metadata:
  name: aks-gmsa-spec  # This name can be changed, but it will be used as a reference in the pod spec
credspec:
  ActiveDirectoryConfig:
    GroupManagedServiceAccounts:
    - Name: gmsa
      Scope: contoso
    - Name: gmsa
      Scope: contoso.com
    HostAccountConfig:
      PluginGUID: '{CCC2A336-D7F3-4818-A213-272B7924213E}'
      PortableCcgVersion: "1"
      PluginInput: "ObjectId=00000000-0000-0000-0000-000000000000;SecretUri=https://{keyvaultname}.vault.azure.net/secrets/{secretname}"  # SECRET_URI takes the form https://$akvName.vault.azure.net/secrets/$akvSecretName
  CmsPlugins:
  - ActiveDirectory
  DomainJoinConfig:
    DnsName: contoso.com
    DnsTreeName: contoso.com
    Guid: 00000000-0000-0000-0000-000000000000
    MachineAccountName: gmsa
    NetBiosName: contoso
    Sid: S-1-5-21-0000059250-1095680357-2181600000 # this is the SID of the domain not SID of GSMA Account