Tanzu Kubernetes Grid includes signed binaries for Gangway. Gangway is the Kubernetes authentication helper that you install on each Tanzu Kubernetes cluster for which you want to implement authentication. It allows users to use their IDP credentials to access Tanzu Kubernetes clusters that have been configured to use Dex as their OIDC server.

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.
  • Tanzu Kubernetes Grid provides Gangway exclusively for use in combination with Dex and in the manner that is documented here. Any other use of the provided Gangway implementation is not supported.

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 use a management cluster named auth-mgmt-cluster.
  • You have deployed a Tanzu Kubernetes cluster with an OIDC endpoint, as described in Deploy an Authentication-Enabled Tanzu Kubernetes Cluster. The examples in this topic use a Tanzu Kubernetes cluster named auth-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. The extensions folder tkg-extensions-v1.2.0+vmware.1 contains subfolders for each type of extension, for example, authentication, ingress, registry, and so on. At the top level of the folder there is an additional subfolder named extensions. The extensions folder also contains subfolders for authentication, ingress, registry, and so on. Take care to run commands from the location provided in the instructions. Commands are usually run from within the extensions folder.

Prepare the Tanzu Kubernetes Cluster for Gangway Deployment

Before you can deploy Gangway on an authentication-enabled Tanzu Kubernetes cluster, you must install the tools that the Gangway extension requires.

This procedure applies to Tanzu Kubernetes clusters running on vSphere, Amazon EC2, and Azure.

  1. While the context of kubectl is still set to the management cluster, obtain the CA certificate of the Dex service.

     kubectl get secret dex-cert-tls -n tanzu-system-auth -o 'go-template={{ index .data "ca.crt" }}' | base64 -d 
    Record the output. You will need it later.

  2. Get the credentials of the authentication-enabled cluster.

    tkg get credentials auth-cluster
    
  3. Set the context of kubectl to the authentication-enabled cluster.

    kubectl config use-context auth-cluster-admin@auth-cluster
    
  4. If you haven't already, install needed components on the Tanzu Kubernetes workload cluster by following the procedure Installing Extension Prerequisite Components to a Cluster.

  5. Create a namespace for the Gangway service on the Tanzu Kubernetes cluster.

    kubectl apply -f authentication/gangway/namespace-role.yaml
    

    You should see confirmation that a tanzu-system-auth namespace, service account, and RBAC role bindings are created.

    namespace/tanzu-system-auth created
    serviceaccount/gangway-extension-sa created
    role.rbac.authorization.k8s.io/gangway-extension-role created
    rolebinding.rbac.authorization.k8s.io/gangway-extension-rolebinding created
    
  6. Check that the new services are running by listing all of the pods that are running in the Tanzu Kubernetes cluster.

    kubectl get pods -A
    

    In the tanzu-system-tmc namespace, you should see the extension-manager and kapp-controller services running in a pod with names similar to extension-manager-7cbdf7cbf9-xzrbn and kapp-controller-cd55bbd6b-vt2c4.

    NAMESPACE              NAME                                  READY   STATUS    RESTARTS   AGE
    [...]
    vmware-system-tmc      extension-manager-7cbdf7cbf9-xzrbn    1/1     Running   0          52s
    vmware-system-tmc      kapp-controller-cd55bbd6b-vt2c4       1/1     Running   0          40s
    
  7. Use openssl to create a client secret and session key for the Gangway service.

    Run both of the following commands:

    CLIENT_SECRET=$(openssl rand -hex 16)
    
    SESSION_KEY=$(openssl rand -hex 16)
    
  8. Display the values of the client secret and session key variables.

    Run both of the following commands and record the output. You will need it later.

    echo $CLIENT_SECRET
    
    echo $SESSION_KEY
    

The Tanzu Kubernetes cluster is ready for you to deploy the Gangway service. For the next steps, see the procedure that corresponds to the infrastructure in which your Tanzu Kubernetes cluster is running:

Update the Gangway Configuration File for a Tanzu Kubernetes Cluster Running on vSphere

This procedure describes how to update the configuration file to enable Gangway on authentication-enabled clusters that you have deployed to vSphere.

  1. Make a copy of the gangway-data-values.yaml.example file and name it gangway-data-values.yaml.

    You use the same gangway-data-values.yaml file for connections to both LDAP servers and to OIDC providers.

    cp authentication/gangway/vsphere/gangway-data-values.yaml.example authentication/gangway/vsphere/gangway-data-values.yaml
    
  2. Update the configuration file with information about your management cluster and the authentication-enabled Tanzu Kubernetes cluster.

    • gangway.config.clusterName: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled Tanzu Kubernetes cluster.
    • gangway.config.MGMT_CLUSTER_IP: Replace <MGMT_CLUSTER_VIP> with the static virtual IP address of the management cluster, or the FQDN of the management cluster.
    • gangway.config.clientID: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled Tanzu Kubernetes cluster.
    • gangway.config.APISERVER_URL: Replace <WORKLOAD_CLUSTER_VIP> with the static virtual IP address of the authentication-enabled Tanzu Kubernetes cluster, or the FQDN of the cluster.
    • gangway.secret.sessionKey: Replace <SESSION_KEY> with the session key for the Gangway service that you obtained in the preceding procedure.
    • gangway.secret.clientSecret: Replace <CLIENT_SECRET> with the client secret for the Gangway service that you obtained in the preceding procedure.
    • dns.vsphere.ipAddresses: Replace <WORKLOAD_CLUSTER_VIP> with the static virtual IP address of the authentication-enabled Tanzu Kubernetes cluster.
    • dex.ca: Replace <INSERT_DEX_CA_CERT> with the contents of the CA file for the Dex service that you obtained in Prepare the Tanzu Kubernetes Cluster for Gangway Deployment above.

      IMPORTANT: Make sure that the CA file contents are indented by exactly 4 spaces. If the indentation is incorrect, the Kapp controller will not deploy the extension.

    For example:

    #@data/values
    #@overlay/match-child-defaults missing_ok=True
    ---
    infrastructure_provider: "vsphere"
    gangway:
      config:
        clusterName: auth-cluster
        MGMT_CLUSTER_IP: 192.168.100.55
        clientID: auth-cluster
        APISERVER_URL: 192.168.100.11
      secret:
        sessionKey: 02ab7df041fdfeace3952d7d832db6f9
        clientSecret: 7b0fb0244d7eb28da0db39a3588b23eb
    dns:
      vsphere:
        #@overlay/replace
        ipAddresses: [192.168.100.11]
    dex:
      ca: | 
        -----BEGIN CERTIFICATE-----
        MIIDJjCCAg6gAwIBAgIRAJ7NE8QscfIGDyiSOeqwGPYwDQYJKoZIhvcNAQELBQAw
        IzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQDEwd0a2ctZGV4MB4XDTIwMDkzMDA4
        NDcxMFoXDTIwMTIyOTA4NDcxMFowIzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQD
        Ewd0a2ctZGV4MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxxc+i/Cq
        qw2pr4puhy7rllNIUWsRGnxXPiqWdCMpIo1W0HQNtf65SMxU/7NwyHOSdRzz6XGL
        0BEdLv9IrO/BkDazg1WsTr2S6jTpH2CbJ2S5vmIW/3IIhr5rcQXVM5cWnKSpitRc
        8Q7kHHg53kCpRFyGFpGQvWPlHxxsJAqp6axV7konSpWqsyQmMVuEuD1VnJUeHLpa
        Za6ySdp4AwNzgIkwAKrza8TXkQZ3uL8uxH7JWgIrzXEqIfyRDxRiYYBqMOOorC0Z
        Ef46GgS0z8RGcFmwHJwVjwN0vs2EUbNiqsvgBUTZWrqpKaDQd2q9ciTYXR57YC+5
        Qxd5JmMpT4ssHwIDAQABo1UwUzAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
        AwIwDAYDVR0TAQH/BAIwADAkBgNVHREEHTAbggt0a2ctZGV4LmNvbYIMMjAuNTQu
        MjI2LjQyMA0GCSqGSIb3DQEBCwUAA4IBAQAp2eKubjZzYo4OAvBgqXje8PJOurmG
        B9vU5HpmqSO1GqAt6SJuiWgXbFeJmiZ4aDlAucVtwINPLnPYXunE9BZ0QQvUyozD
        pAbHdoLjvhf8srZV58cXr41OVs2lodFFymIt4PHvlZ3UuCXqMC2Nn9bowCTjmgMx
        u+iHem5/vWGASd37z0WmiwiwKzPbJNfGDhQY9I7WKOaL+azQBAiwjMWxUf+OLau7
        VFVtYD65uztsqU4wWoA3UswAP0dcJlRN0P5XQlxW/+ecVj8Kn0vFqGkMGCZTJCsW
        suqxb/OkRO5+EkOhwK8kpx+kHKce5/Olvp4Kcog62XMrfqLhn1Kg4eXR
        -----END CERTIFICATE-----
    
  3. Save the updated gangway-data-values.yaml file.
  4. Create a Kubernetes secret named gangway-data-values with the values that you set in gangway-data-values.yaml.

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/vsphere/gangway-data-values.yaml -n tanzu-system-auth
    

For the next steps, see Deploy Gangway on the Tanzu Kubernetes Cluster.

Update the Gangway Configuration File for a Tanzu Kubernetes Cluster Running on Amazon EC2

This procedure describes how to update the configuration file to enable Gangway on authentication-enabled clusters that you have deployed to Amazon EC2.

  1. Make a copy of the gangway-data-values.yaml.example file and name it gangway-data-values.yaml.

    cp authentication/gangway/aws/gangway-data-values.yaml.example authentication/gangway/aws/gangway-data-values.yaml
    
  2. Update the configuration file with information about your management cluster and the authentication-enabled Tanzu Kubernetes cluster.

    • gangway.config.clusterName: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled cluster.
    • gangway.config.DEX_SVC_LB_HOSTNAME: Replace <DEX_SVC_LB_HOSTNAME> with the host name of the Dex service load balancer that is running in the management cluster, that you identified in Obtain the Dex Load Balancer for Amazon EC2.
    • gangway.config.clientID: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled Tanzu Kubernetes cluster.
    • gangway.config.APISERVER_URL: Replace <API_SERVER_LB_HOSTNAME> with the host name of the Kubernetes API Server endpoint for the Tanzu Kubernetes cluster. This is the DNS name of the AWS load balancer, that has a name like auth-cluster-apiserver-1506126946.us-west-2.elb.amazonaws.com. You can find this DNS name in the Load Balancers view of your EC2 Dashboard.
    • gangway.secret.sessionKey: Replace <SESSION_KEY> with the session key for the Gangway service that you obtained in the preceding procedure.
    • gangway.secret.clientSecret: Replace <CLIENT_SECRET> with the client secret for the Gangway service that you obtained in the preceding procedure.
    • dns.aws.GANGWAY_SVC_LB_HOSTNAME: Do not update <GANGWAY_SVC_LB_HOSTNAME> yet. The Gangway service load balancer is created when you deploy the Gangway service, so you must update this value after you have deployed Gangway.
    • dex.ca: Replace <INSERT_DEX_CA_CERT> with the contents of the CA file for the Dex service that you obtained in Prepare the Tanzu Kubernetes Cluster for Gangway Deployment above.

      IMPORTANT: Make sure that the CA file contents are indented by exactly 4 spaces. If the indentation is incorrect, the Kapp controller will not deploy the extension.

    For example:

    #@data/values
    #@overlay/match-child-defaults missing_ok=True
    ---
    infrastructure_provider: "aws"
    gangway:
      config:
        clusterName: auth-cluster
        DEX_SVC_LB_HOSTNAME: aff037c12897xxxxxxxxxxxxxxf7668d-1246768892.us-west-2.elb.amazonaws.com
        clientID: auth-cluster
        APISERVER_URL: auth-cluster-apiserver-xxxxxxxxxx.us-west-2.elb.amazonaws.com
      secret:
        sessionKey: 02ab7df041fdfeace3952d7d832db6f9
        clientSecret: 7b0fb0244d7eb28da0db39a3588b23eb
    dns:
      aws:
        GANGWAY_SVC_LB_HOSTNAME: <GANGWAY_SVC_LB_HOSTNAME>
    
    dex:
      ca: | 
        -----BEGIN CERTIFICATE-----
        MIIDJjCCAg6gAwIBAgIRAJ7NE8QscfIGDyiSOeqwGPYwDQYJKoZIhvcNAQELBQAw
        IzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQDEwd0a2ctZGV4MB4XDTIwMDkzMDA4
        NDcxMFoXDTIwMTIyOTA4NDcxMFowIzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQD
        Ewd0a2ctZGV4MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxxc+i/Cq
        qw2pr4puhy7rllNIUWsRGnxXPiqWdCMpIo1W0HQNtf65SMxU/7NwyHOSdRzz6XGL
        0BEdLv9IrO/BkDazg1WsTr2S6jTpH2CbJ2S5vmIW/3IIhr5rcQXVM5cWnKSpitRc
        8Q7kHHg53kCpRFyGFpGQvWPlHxxsJAqp6axV7konSpWqsyQmMVuEuD1VnJUeHLpa
        Za6ySdp4AwNzgIkwAKrza8TXkQZ3uL8uxH7JWgIrzXEqIfyRDxRiYYBqMOOorC0Z
        Ef46GgS0z8RGcFmwHJwVjwN0vs2EUbNiqsvgBUTZWrqpKaDQd2q9ciTYXR57YC+5
        Qxd5JmMpT4ssHwIDAQABo1UwUzAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
        AwIwDAYDVR0TAQH/BAIwADAkBgNVHREEHTAbggt0a2ctZGV4LmNvbYIMMjAuNTQu
        MjI2LjQyMA0GCSqGSIb3DQEBCwUAA4IBAQAp2eKubjZzYo4OAvBgqXje8PJOurmG
        B9vU5HpmqSO1GqAt6SJuiWgXbFeJmiZ4aDlAucVtwINPLnPYXunE9BZ0QQvUyozD
        pAbHdoLjvhf8srZV58cXr41OVs2lodFFymIt4PHvlZ3UuCXqMC2Nn9bowCTjmgMx
        u+iHem5/vWGASd37z0WmiwiwKzPbJNfGDhQY9I7WKOaL+azQBAiwjMWxUf+OLau7
        VFVtYD65uztsqU4wWoA3UswAP0dcJlRN0P5XQlxW/+ecVj8Kn0vFqGkMGCZTJCsW
        suqxb/OkRO5+EkOhwK8kpx+kHKce5/Olvp4Kcog62XMrfqLhn1Kg4eXR
        -----END CERTIFICATE-----
    
  3. Save the updated gangway-data-values.yaml file.
  4. Create a Kubernetes secret named gangway-data-values with the values that you set in gangway-data-values.yaml.

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/aws/gangway-data-values.yaml -n tanzu-system-auth
    

For the next steps, see Deploy Gangway on the Tanzu Kubernetes Cluster.

Update the Gangway Configuration File for a Tanzu Kubernetes Cluster Running on Azure

This procedure describes how to update the configuration file to enable Gangway on authentication-enabled clusters that you have deployed to Azure.

  1. Make a copy of the gangway-data-values.yaml.example file and name it gangway-data-values.yaml.

    cp authentication/gangway/azure/gangway-data-values.yaml.example authentication/gangway/azure/gangway-data-values.yaml
    
  2. Update the configuration file with information about your management cluster and the authentication-enabled Tanzu Kubernetes cluster.

    • gangway.config.clusterName: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled cluster.
    • gangway.config.DEX_SVC_LB_HOSTNAME: Replace <DEX_SVC_LB_HOSTNAME> with the host name of the Dex service load balancer that is running in the management cluster, that you identified in Obtain the Dex Load Balancer for Azure.
    • gangway.config.clientID: Replace <WORKLOAD_CLUSTER_NAME> with the name of the authentication-enabled Tanzu Kubernetes cluster.
    • gangway.config.APISERVER_URL: Replace <API_SERVER_LB_HOSTNAME> with the host name of the Kubernetes API Server endpoint for the Tanzu Kubernetes cluster. This is the DNS name of the Azure load balancer, that has a name like auth-cluster-apiserver-1506126946.us-west-2.elb.amazonaws.com. You can find this DNS name by consulting the Resource group in your Azure account.
    • gangway.secret.sessionKey: Replace <SESSION_KEY> with the session key for the Gangway service that you obtained in the preceding procedure.
    • gangway.secret.clientSecret: Replace <CLIENT_SECRET> with the client secret for the Gangway service that you obtained in the preceding procedure.
    • dns.aws.GANGWAY_SVC_LB_HOSTNAME: Do not update <GANGWAY_SVC_LB_HOSTNAME> yet. The Gangway service load balancer is created when you deploy the Gangway service, so you must update this value after you have deployed Gangway.
    • dex.ca: Replace <INSERT_DEX_CA_CERT> with the contents of the CA file for the Dex service that you obtained in Prepare the Tanzu Kubernetes Cluster for Gangway Deployment above.

      IMPORTANT: Make sure that the CA file contents are indented by exactly 4 spaces. If the indentation is incorrect, the Kapp controller will not deploy the extension.

    For example:

    #@data/values
    #@overlay/match-child-defaults missing_ok=True
    ---
    infrastructure_provider: "azure"
    gangway:
      config:
        clusterName: auth-cluster
        DEX_SVC_LB_HOSTNAME: 20.54.226.42
        clientID: auth-cluster
        APISERVER_URL: 20.54.226.42
      secret:
        sessionKey: 02ab7df041fdfeace3952d7d832db6f9
        clientSecret: 7b0fb0244d7eb28da0db39a3588b23eb
    dns:
      azure:
        GANGWAY_SVC_LB_HOSTNAME: <GANGWAY_SVC_LB_HOSTNAME>
    dex:
      ca: | 
        -----BEGIN CERTIFICATE-----
        MIIDJjCCAg6gAwIBAgIRAJ7NE8QscfIGDyiSOeqwGPYwDQYJKoZIhvcNAQELBQAw
        IzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQDEwd0a2ctZGV4MB4XDTIwMDkzMDA4
        NDcxMFoXDTIwMTIyOTA4NDcxMFowIzEPMA0GA1UEChMGdm13YXJlMRAwDgYDVQQD
        Ewd0a2ctZGV4MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxxc+i/Cq
        qw2pr4puhy7rllNIUWsRGnxXPiqWdCMpIo1W0HQNtf65SMxU/7NwyHOSdRzz6XGL
        0BEdLv9IrO/BkDazg1WsTr2S6jTpH2CbJ2S5vmIW/3IIhr5rcQXVM5cWnKSpitRc
        8Q7kHHg53kCpRFyGFpGQvWPlHxxsJAqp6axV7konSpWqsyQmMVuEuD1VnJUeHLpa
        Za6ySdp4AwNzgIkwAKrza8TXkQZ3uL8uxH7JWgIrzXEqIfyRDxRiYYBqMOOorC0Z
        Ef46GgS0z8RGcFmwHJwVjwN0vs2EUbNiqsvgBUTZWrqpKaDQd2q9ciTYXR57YC+5
        Qxd5JmMpT4ssHwIDAQABo1UwUzAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
        AwIwDAYDVR0TAQH/BAIwADAkBgNVHREEHTAbggt0a2ctZGV4LmNvbYIMMjAuNTQu
        MjI2LjQyMA0GCSqGSIb3DQEBCwUAA4IBAQAp2eKubjZzYo4OAvBgqXje8PJOurmG
        B9vU5HpmqSO1GqAt6SJuiWgXbFeJmiZ4aDlAucVtwINPLnPYXunE9BZ0QQvUyozD
        pAbHdoLjvhf8srZV58cXr41OVs2lodFFymIt4PHvlZ3UuCXqMC2Nn9bowCTjmgMx
        u+iHem5/vWGASd37z0WmiwiwKzPbJNfGDhQY9I7WKOaL+azQBAiwjMWxUf+OLau7
        VFVtYD65uztsqU4wWoA3UswAP0dcJlRN0P5XQlxW/+ecVj8Kn0vFqGkMGCZTJCsW
        suqxb/OkRO5+EkOhwK8kpx+kHKce5/Olvp4Kcog62XMrfqLhn1Kg4eXR
        -----END CERTIFICATE-----
    
  3. Save the updated gangway-data-values.yaml file.
  4. Create a Kubernetes secret named gangway-data-values with the values that you set in gangway-data-values.yaml.

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/azure/gangway-data-values.yaml -n tanzu-system-auth
    

For the next steps, see Deploy Gangway on the Tanzu Kubernetes Cluster.

Deploy Gangway on the Tanzu Kubernetes Cluster

After you have prepared the authentication-enabled Tanzu Kubernetes cluster and updated the appropriate configuration file for your platform, you can deploy Gangway on the cluster.

This procedure applies to Tanzu Kubernetes clusters running on vSphere, Amazon EC2, and Azure.

  1. Deploy the Gangway extension.

    kubectl apply -f authentication/gangway/gangway-extension.yaml
    

    You should see the confirmation extension.clusters.tmc.cloud.vmware.com/gangway created.

  2. View the status of the Gangway extension.

    kubectl get extension gangway -n tanzu-system-auth
    

    You should see information about the Gangway extension.

    NAME      STATE   HEALTH   VERSION
    gangway   3
    
  3. View the status of the Gangway service itself.

    kubectl get app gangway -n tanzu-system-auth
    

    The status of the Dex app should show Reconcile Succeeded when Gangway has deployed successfully.

    NAME      DESCRIPTION           SINCE-DEPLOY   AGE
    gangway   Reconcile succeeded   9s             43s
    

    If the status is not Reconcile Succeeded, view the full status details of the Gangway service.

    Viewing the full status can help you to troubleshoot the problem.

    kubectl get app gangway -n tanzu-system-auth -o yaml
    
  4. Check that the Gangway service is running by listing all of the pods that are running in the Tanzu Kubernetes cluster.

    kubectl get pods -A
    

    In the tanzu-system-auth namespace, you should see the gangway service running in a pod with names similar to gangway-69657b8585-qdqg9.

    NAMESPACE              NAME                                  READY   STATUS    RESTARTS   AGE
    [...]
    tanzu-system-auth   gangway-69657b8585-qdqg9                                   1/1     Running   0          10m
    vmware-system-tmc   extension-manager-d7cc7fcbb-g6z9s                          1/1     Running   0          15m
    vmware-system-tmc   kapp-controller-7c98dff676-7hg8b                           1/1     Running   0          15m
    

If your Tanzu Kubernetes cluster is running on vSphere, for the next steps, see Register Gangway with the Dex Service.

If your Tanzu Kubernetes cluster is running on Amazon EC2 or Azure, for the next steps see Obtain the Gangway Load Balancer for Amazon EC2 or Obtain the Gangway Load Balancer for Azure.

Obtain the Gangway Load Balancer for Amazon EC2

If you deployed Gangway on a cluster that is running on Amazon EC2, you must perform additional steps to obtain the address of the Gangway service load balancer that is running in that cluster. You then need to update the Gangway configuration to use it.

  1. Obtain the hostname of the Gangway service load balancer.

    kubectl get svc gangwaysvc -n tanzu-system-auth -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
    
  2. Open authentication/gangway/aws/gangway-data-values.yaml in a text editor and update the GANGWAY_SVC_LB_HOSTNAME parameter with the address that you obtained in the preceding step.

    dns:
      aws:
        GANGWAY_SVC_LB_HOSTNAME: a708e794809d54af699834323c33a0a-463181988.us-west-2.elb.amazonaws.com
    
  3. Update the gangway-data-values secret to include the load balancer address.

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/aws/gangway-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    You should see the confirmation secret/dex-data-values replaced. The changes should show up in five minutes or less. This is handled by the Kapp controller, which synchronizes every five minutes.

For the next steps, see Register Gangway with the Dex Service.

Obtain the Gangway Load Balancer for Azure

If you deployed Gangway on a cluster that is running on Azure, you must perform additional steps to obtain the address of the Gangway service load balancer that is running in that cluster. You then need to update the Gangway configuration to use it.

  1. Obtain the IP address of the Gangway service load balancer.

    kubectl get svc gangwaysvc -n tanzu-system-auth -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    
  2. Open authentication/gangway/azure/gangway-data-values.yaml in a text editor and update the GANGWAY_SVC_LB_HOSTNAME parameter with the address that you obtained in the preceding step.

    dns:
      azure:
        GANGWAY_SVC_LB_HOSTNAME: 20.54.226.44
    
  3. Update the gangway-data-values secret to include the load balancer address.

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/azure/gangway-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    You should see the confirmation secret/gangway-data-values replaced. The Gangway extension will be reconciled using the new values you just added. The changes should show up in five minutes or less. This is handled by the Kapp controller, which synchronizes every five minutes.

For the next steps, see Register Gangway with the Dex Service.

Register Gangway with the Dex Service

After you have deployed Gangway on a Tanzu Kubernetes cluster, you must register the Gangway service with the Dex service that is running in the management cluster.

This procedure applies to Tanzu Kubernetes clusters running on vSphere, Amazon EC2, and Azure.

  1. Set the context of kubectl back to the management cluster.

    kubectl config use-context auth-mgmt-cluster-admin@auth-mgmt-cluster 
    
  2. Open the appropriate dex-data-values.yaml file in a text editor.

    • vSphere (LDAP): authentication/dex/vsphere/ldap/dex-data-values.yaml
    • vSphere (OIDC): authentication/dex/vsphere/oidc/dex-data-values.yaml
    • Amazon EC2: authentication/dex/aws/oidc/dex-data-values.yaml
    • Azure: authentication/dex/azure/ldap/dex-data-values.yaml
  3. Edit the dex.config.staticClients entry in the dex-data-values.yaml file with information about the Gangway service that is running in the Tanzu Kubernetes cluster.

    • dex.config.staticClients.id: Replace WORKLOAD_CLUSTER_NAME with the name of the Tanzu Kubernetes cluster on which you deployed Gangway. For example, auth-cluster.
    • dex.config.staticClients.redirectURIs:

      • vSphere: Replace WORKLOAD_CLUSTER_IP with the static virtual IP address that you set for the Tanzu Kubernetes cluster on which you deployed Gangway, or the FQDN of the cluster.
      • Amazon EC2: Replace GANGWAY_SVC_LB_HOSTNAME with the name of the Gangway service load balancer that you obtained in Obtain the Gangway Load Balancer for Amazon EC2.
      • Azure: Replace WORKLOAD_CLUSTER_IP with the IP of the Gangway service load balancer that you obtained in Obtain the Gangway Load Balancer for Azure.
    • dex.config.staticClients.name: Replace WORKLOAD_CLUSTER_NAME with the name of the Tanzu Kubernetes cluster on which you deployed Gangway. For example, auth-cluster.
    • dex.config.staticClients.secret: Replace <CLIENT_SECRET> with the client secret for the Gangway service that you obtained in Prepare the Tanzu Kubernetes Cluster for Gangway Deployment above.

    vSphere:

        staticClients:
        - id: auth-cluster
          redirectURIs:
          - 'https://192.168.100.11:30166/callback'
          name: auth-cluster
          secret: 7b0fb0244d7eb28da0db39a3588b23eb
    

    Amazon EC2:

        staticClients:
        - id: auth-cluster
          redirectURIs:
          - 'https://a708e794809d54af699834323c33a0a-463181988.us-west-2.elb.amazonaws.com:30166/callback'
          name: auth-cluster
          secret: 7b0fb0244d7eb28da0db39a3588b23eb
    

    Azure:

        staticClients:
        - id: auth-cluster
          redirectURIs:
          - 'https://20.54.226.44:30166/callback'
          name: auth-cluster
          secret: 7b0fb0244d7eb28da0db39a3588b23eb
    
  4. Recreate the dex-data-values Kubernetes secret with the new values that you set in dex-data-values.yaml.

    These commands assume that you are running then from tkg-extensions-v1.2.0+vmware.1/extensions.

    vSphere (LDAP):

    kubectl create secret generic dex-data-values --from-file=authentication/dex/vsphere/ldap/dex-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    vSphere (OIDC):

    kubectl create secret generic dex-data-values --from-file=authentication/dex/vsphere/oidc/dex-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    Amazon EC2:

    kubectl create secret generic dex-data-values --from-file=authentication/dex/aws/oidc/dex-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    Azure:

    kubectl create secret generic dex-data-values --from-file=authentication/dex/azure/ldap/dex-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    The Dex extension will be reconciled using the new values you just added. The changes should show up in five minutes or less. This is handled by the Kapp controller, which synchronizes every five minutes.

  5. Check that the update succeeded and that the Dex service has restarted.

    kubectl get app dex -n tanzu-system-auth
    

    You should see Reconcile succeeded and that the SINCE-DEPLOY value is recent.

    NAME   DESCRIPTION           SINCE-DEPLOY   AGE
    dex    Reconcile succeeded   61s            69m
    

What to Do Next

Dex and Gangway are now running on your management cluster and Tanzu Kubernetes cluster respectively. You can now use your the credentials from your external identity provider (IDP) to connect to the cluster, as described in Log In to the Authentication-Enabled Tanzu Kubernetes Cluster to Obtain Its kubeconfig.

Update a Gangway Deployment

If you need to make changes to the configuration of the Gangway extension, you can update the extension.

Perform the steps in this procedure if you modify either of the extensions/authentication/gangway/<INFRA_PROVIDER>/gangway-data-values.yaml or authentication/gangway/values.yaml files after the initial deployment of Gangway.

  1. Obtain the Contour data values from the Kubernetes secret.

    kubectl get secret gangway-data-values -n tanzu-system-auth -o 'go-template={{ ingangway .data "values.yaml" }}' | base64 -d > gangway-data-values.yaml
    
  2. Modify either or both of the extensions/authentication/gangway/<INFRA_PROVIDER>/gangway-data-values.yaml or authentication/gangway/values.yaml files to update your configuration.
  3. Update the Kubernetes secret.

    This command assumes that you are running it from tkg-extensions-v1.2.0+vmware.1/extensions.

    vSphere:

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/vsphere/gangway-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    Amazon EC2:

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/aws/gangway-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    Azure:

    kubectl create secret generic gangway-data-values --from-file=values.yaml=authentication/gangway/azure/gangway-data-values.yaml -n tanzu-system-auth -o yaml --dry-run | kubectl replace -f-
    

    Note that the final - on the kubectl replace command above is necessary to instruct kubectl to accept the input being piped to it from the kubectl create secret command.

    The Gangway extension will be reconciled using the new values you just added. The changes should show up in five minutes or less. This is handled by the Kapp controller, which synchronizes every five minutes.

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