To use the Dex service that is running in the management cluster so that you can authenticate connections to the Tanzu Kubernetes clusters that it manages, the Tanzu Kubernetes clusters must be correctly configured to connect to that Dex service.

IMPORTANT: Tanzu Kubernetes Grid v1.3 introduces user authentication with Pinniped and Dex, that run automatically in management clusters if you enable identity management during deployment. Due to this change in authentication mechanism in v1.3, if you have not already manually deployed the Dex and Gangway extensions in v1.2.x, it is strongly recommended not to do so. To implement cluster authentication, it is strongly recommended to upgrade to Tanzu Kubernetes Grid v1.3 and to use the built-in Pinniped and Dex identity management service that the newer version provides.

The Tanzu Kubernetes Grid CLI provides an option to deploy Tanzu Kubernetes clusters that are enabled for authentication with an IDP provider. The clusters that you deploy with this option include a Dex OIDC endpoint that allows the cluster to connect, via the Dex service in the management cluster, to either an LDAP or OIDC Identity Provider.

Prerequisites

  • You have completed the appropriate procedures in Deploy Dex on Management Clusters to deploy Dex on a management cluster that is running on vSphere, Amazon EC2, or Azure. The examples in this topic section use a management cluster named auth-mgmt-cluster.
  • Run all of the commands in this procedure from the folder that contains the unpacked Tanzu Kubernetes Grid extension manifest files, tkg-extensions-v1.2.0+vmware.1/extensions.

Procedure

This procedure applies to deploying authentication-enabled Tanzu Kubernetes clusters to management clusters that are running on vSphere, Amazon EC2, or Azure.

  1. Make sure that kubectl is still set to the context of the management cluster on which you deployed Dex.

    kubectl config use-context auth-mgmt-cluster-admin@auth-mgmt-cluster
    
  2. Set one of the following environment variables, depending on whether your management cluster is running on vSphere, Amazon EC2 or Azure.

    On Windows platforms, use the SET command instead of export.

    vSphere:

    export OIDC_ISSUER_URL=https://<MGMT_CLUSTER_IP>:30167
    

    Replace <MGMT_CLUSTER_IP> with the static virtual IP address that you provided when you deployed the management cluster, or the FQDN of the management cluster.

    Amazon EC2:

    export OIDC_ISSUER_URL=https://<DEX_SVC_LB_HOSTNAME>
    

    Replace <DEX_SVC_LB_HOSTNAME> with the hostname of the Dex service load balancer that is running in your management cluster. You obtained this address in Obtain the Dex Load Balancer for Amazon EC2 in the previous procedure.

    Azure:

    export OIDC_ISSUER_URL=https://<DEX_SVC_LB_HOSTNAME>
    

    Replace <DEX_SVC_LB_HOSTNAME> with the IP address of the Dex service load balancer that is running in your management cluster. You obtained this address in Obtain the Dex Load Balancer for Azure in the previous procedure.

  3. For all platforms, set the following environment variables.

    export OIDC_USERNAME_CLAIM=email
    
    export OIDC_GROUPS_CLAIM=groups
    
  4. Obtain the ca.crt certificate of the Dex service that is running in the management cluster.

    Run the following command without changes.

     export OIDC_DEX_CA=$(kubectl get secret dex-cert-tls -n tanzu-system-auth -o 'go-template={{ index .data "ca.crt" }}' | base64 -d | gzip | base64) 

  5. Deploy a Tanzu Kubernetes cluster named auth-cluster by using the tkg create cluster command with the --enable-cluster-options oidc option.

    The --enable-cluster-options oidc option configures the Tanzu Kubernetes cluster so that it can connect to the Dex service that is running in the management cluster.

    vSphere:

    tkg create cluster auth-cluster --enable-cluster-options oidc --plan dev --vsphere-controlplane-endpoint <WORKLOAD_CLUSTER_IP_OR_FQDN>
    

    Replace <WORKLOAD_CLUSTER_IP_OR_FQDN> with a static virtual IP (VIP) address for the control plane of the Tanzu Kubernetes cluster. Ensure that this IP address is not in the DHCP range, but is in the same subnet as the DHCP range. If you mapped a fully qualified domain name (FQDN) to the VIP address, you can specify the FQDN instead of the VIP address.

    Amazon EC2 and Azure:

    tkg create cluster auth-cluster --enable-cluster-options oidc --plan dev
    
  6. Wait for confirmation that the deployment of the Tanzu Kubernetes cluster is successful.

    Validating configuration...
    Creating workload cluster 'auth-cluster'...
    Waiting for cluster to be initialized...
    Waiting for cluster nodes to be available...
    Waiting for addons installation...  
    Workload cluster 'auth-cluster' created
    

What to Do Next

Now that you have deployed Dex on the management cluster and deployed an authentication-enabled cluster, you must enable Gangway on the cluster and connect it to the Dex service. See Deploy Gangway on Tanzu Kubernetes Clusters.

check-circle-line exclamation-circle-line close-line
Scroll to top icon