This topic describes how to integrate Microsoft Active Directory (AD) with your Tanzu Kubernetes Grid Integrated Edition (TKGI) Windows worker-based Kubernetes clusters.
Windows Server with Active Directory can control access to Windows worker-based Kubernetes clusters in TKGI. To enable this, you integrate a group Managed Service Account (gMSA) in AD with the cluster’s Windows pods and containers.
Note: Once a cluster has been created or updated to use AD authentication, you cannot update it to stop using AD authentication.
For information about gMSAs see Group Managed Service Accounts Overview in the Microsoft Windows Server documentation.
To manage AD integration with a TKGI-provisioned Windows worker-based Kubernetes cluster:
To use AD to control access to Windows worker-based Kubernetes clusters, you need an AD server configured with:
To create a TKGI cluster configured with AD gMSA authentication:
Define the gMSA settings in a configuration file on your local filesystem. For configuration information, see GMSA Configuration Settings, below.
Pass the file location to the --config-file
flag of tkgi create-cluster
. For information about creating clusters, see Creating Clusters.
Integrate the cluster with the AD gMSA as described in Integrate the Cluster with Active Directory, below.
To configure an existing TKGI cluster for Active Directory gMSA authentication, or to change its gMSA configuration:
Note: Once a cluster has been created or updated to use AD authentication, you cannot update it to stop using AD authentication.
Define the gMSA settings in a configuration file on your local filesystem:
{}
(for an object) or ""
(for a string) in the configuration file.For configuration information, see GMSA Configuration Settings, below.
Run the following command to update the cluster with the configuration file:
tkgi update-cluster CLUSTER-NAME --config-file CONFIG-FILE-NAME
Where:
CLUSTER-NAME
is the name of the existing Kubernetes cluster.CONFIG-FILE-NAME
is the path and filename of the configuration file you want to apply to the cluster. For information about GMSA command line configuration, see GMSA Configuration Settings below.WARNING: Update the configuration file only on a TKGI cluster that has been upgraded to the current TKGI version. For more information, see Tasks Supported Following a TKGI Control Plane Upgrade in About Tanzu Kubernetes Grid Integrated Edition Upgrades.
Integrate the cluster with the AD gMSA as described in Integrate the Cluster with Active Directory, below.
Once you have a cluster configured in Tanzu Kubernetes Grid and AD to access the gMSA, you need to run the following Kubernetes operations to integrate the cluster with the gMSA at the Kubernetes level.
This procedure is described in Configure GMSA for Windows Pods and containers in the Kubernetes documentation, with one exception. The exception is that you used the --config-file
flag in the tkgi
CLI to add the Windows nodes into the AD, instead of following the step Configure GMSAs and Windows nodes in Active Directory in the Kubernetes documentation. For information about GMSA command line configuration, see GMSA Configuration Settings below.
To prepare for the next step, download the example script deploy-gmsa-webhook.sh
and update its CA_BUNDLE
setting:
bosh ssh
into the cluster’s control plane node. For more information, see SSH into a Kubernetes Cluster VM./var/vcap/jobs/kube-controller-manager/config/cluster-signing-ca.pem
file and name it locally as ca-master.pem
.Edit CA_BUNDLE
setting in the deploy-gmsa-webhook.sh
example script linked above to read as follows:
CA_BUNDLE="$(cat ca-master.pem|base64 -w 0)"
Run the script to install two webhooks into the cluster that populate and validate gMSA credential spec references at the Pod or container level. For more information, see Install webhooks to validate GMSA users.
Log in to Active Directory and create gMSA credential spec resources using the domain_service_account
and the domain information in your configuration file. For more information, see Create GMSA credential spec resources.
This step includes converting your configuration file from JSON to YAML.
Configure cluster role to enable RBAC on specific GMSA credential specs for the credential specs created in the previous step.
Assign role to service accounts to use specific GMSA credspecs for the role created in the previous step.
Configure GMSA credential spec reference in Pod spec for the Pod spec created earlier.
You can see a cluster’s current gMSA configuration by viewing its BOSH manifest:
Identify the names of your cluster deployments:
bosh deployments
Note: Cluster deployment names start with service-instance_
.
For any cluster you want to view, download its manifest:
bosh -d DEPLOYMENT-NAME manifest > /tmp/YOUR-DEPLOYMENT-MANIFEST.yml
Where:
DEPLOYMENT-NAME
is the name of your Kubernetes cluster deployment.YOUR-DEPLOYMENT-MANIFEST
is the name of your Kubernetes cluster deployment manifest.Search the manifest for gMSA configuration settings. For configuration information, see GMSA Configuration Settings, below.
The tkgi
CLI uses a JSON-formatted cluster configuration file to add the cluster’s Windows nodes into the AD domain server and security groups, giving them access to the gMSA. You pass the file’s location to the CLI’s --config-file
flag.
Note: Cluster configuration files can also include settings for non-gMSA features, such as proxies. You combine all such settings into a single, general-purpose configuration file to pass to the –config-file
flag.
gMSA settings in the cluster configuration file are:
enable_gmsa
: Boolean. true
to configure gMSA for a cluster. false
to ignore all settings below.domain_controller_ip_address
: Address of the AD server with the gMSA account.domain_fqdn
: FQDN to add the cluster nodes to, created in AD.domain_user_username
: Username for an AD account with permission to add nodes to a new domain.domain_user_password
: Password the AD account.domain_security_group
: AD security group that the gMSA account is included under.domain_service_account
: AD gMSA account.For example:
{
"enable_gmsa": true,
"domain_controller_ip_address": "10.199.17.52",
"domain_fqdn": "tkgi-ad.local",
"domain_user_username": "tkgi-admin",
"domain_user_password": "Passw0rd",
"domain_security_group": "WebApp01Hosts",
"domain_service_account": "WebApp01"
}