Authenticate Windows Clusters with Active Directory

This topic describes how to integrate Microsoft Active Directory (AD) with your Tanzu Kubernetes Grid Integrated Edition (TKGI) Windows worker-based Kubernetes clusters.

Overview

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:

• Create and Integrate a Cluster with AD Authentication
• Change a Cluster’s Active Directory Authentication
• Integrate a Cluster with Active Directory
• View a Cluster’s gMSA Configuration

Prerequisites

To use AD to control access to Windows worker-based Kubernetes clusters, you need an AD server configured with:

• A gMSA account
• A security group that includes the gMSA account

Create and Integrate a Cluster with AD Authentication

To create a TKGI cluster configured with AD gMSA authentication:

1. Define the gMSA settings in a configuration file on your local filesystem. For configuration information, see GMSA Configuration Settings, below.

2. Pass the file location to the --config-file flag of tkgi create-cluster. For information about creating clusters, see Creating Clusters.

3. Integrate the cluster with the AD gMSA as described in Integrate the Cluster with Active Directory, below.

Change a Cluster’s Active Directory Authentication

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.

1. Define the gMSA settings in a configuration file on your local filesystem:

   • To retain a previous setting, do not include it in the configuration file.
   • To unset a previous setting, set it to {} (for an object) or "" (for a string) in the configuration file.

   For configuration information, see GMSA Configuration Settings, below.

2. If you are updating a cluster that uses a public cloud CSI driver, see Limitations on Using a Public Cloud CSI Driver in Release Notes for additional requirements.

3. 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.

4. Integrate the cluster with the AD gMSA as described in Integrate the Cluster with Active Directory, below.

Integrate a Cluster with Active Directory

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.

1. Install the GMSACredentialSpec CRD.

2. To prepare for the next step, download the example script deploy-gmsa-webhook.sh and update its CA_BUNDLE setting:

   1. bosh ssh into the cluster’s control plane node. For more information, see SSH into a Kubernetes Cluster VM.
   2. Fetch the /var/vcap/jobs/kube-controller-manager/config/cluster-signing-ca.pem file and name it locally as ca-master.pem.

   3. 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)"
      

3. 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.

4. 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.

5. Configure cluster role to enable RBAC on specific GMSA credential specs for the credential specs created in the previous step.

6. Assign role to service accounts to use specific GMSA credspecs for the role created in the previous step.

7. Configure GMSA credential spec reference in Pod spec for the Pod spec created earlier.

View a Cluster’s gMSA Configuration

You can see a cluster’s current gMSA configuration by viewing its BOSH manifest:

1. Identify the names of your cluster deployments:

   bosh deployments
   

   Note: Cluster deployment names start with service-instance_.

2. 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.

3. Search the manifest for gMSA configuration settings. For configuration information, see GMSA Configuration Settings, below.

GMSA Configuration Settings

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"
}