Skip to content

End-to-end: Using Gitlab as an external OIDC for vSphere Supervisor

This guide is an end-to-end walkthrough for setting up Gitlab external OIDC access to VKS clusters.
The guide has been written for vSphere 8 and has not been tested against VCF/VVF 9. The process will probably not change drastically but small differences may occur.

Why?

When you deploy workload clusters in your organization, you want to control who gets to do what on which cluster. RBAC is essential and vSpher eSupervisor offers two options out of the box:

  1. vSphere SSO - This leverages the vSphere SSO configuration.
  2. External OIDC - This allows you to connect and external OIDC provider directly to the supervisor and VKS clusters.

In this guide, we are going to use Gitlab as an external OIDC provider to authenticate users. Enabling an external OIDC provider also allows you to create a kubeconfig that can be shared among developers, since there are no credentials stored in the kubeconfig file. All authentication is done through pinniped.

Administrator tasks

Setting up Gitlab

  1. In the Gitlab admin area, go to the application page and create a new application.
  2. Grab the redirect URL from the supervisor (Configure -> Identity Providers in the vsphere Supervisor UI)
  3. Select Trusted and Confidential. Under scopes, select openid, profile and email.
  4. Copy the user id and the secret. The secret can only be read now!

Configuring the supervisor

  1. Back in the vSphere UI, create a new identity provider.
  2. fill in the following provider configuration:
    1. Issuer URL: this is the Gitlab fqdn.
    2. Username claim: nickname
    3. Group claim: groups
  3. Next, fill in the user id and secret.
  4. In additional settings, you must fill in openid in "Additional Scopes". Otherwise pinniped will automatically request the offline_access scope which does not exist in gitlab.
  5. If your gitlab instance is signed by a private CA, add the CA certificate.

Verifying the OIDC connection

A siimple way of checking whether your Supervisor has succesfully connected to the OIDC provider is to get the OIDCIdentityProvider object in the vmware-system-pinniped namespace on the Supervisor.

  1. Log into the supervisor. Generally you'll do this through the vSphere SSO
    kubectl vsphere login --server dkv-tanzu-mgmt.dklab.be -u administrator@dklab.be
  2. Grab the active OIDCIdentityProvider and verify it's status is Ready 
kubectl get OIDCIdentityProvider -n vmware-system-pinniped
NAME       ISSUER                 STATUS   AGE
oidc-idp   https://git.dklab.be   Ready    20h
  1. Describe the resulting object if you want more details
    kubectl describe OIDCIdentityProvider oidc-idp -n vmware-system-pinniped

Setting up the Tanzu cli and generating the kubeconfig file

The next step is to generate a kubeconfig that leverages pinniped to connect to Gitlab.

  1. Check the correct version to download from this Compatibility matrix at the bottom of the page. For vSphere Supervisor and VKS, this is version 1.1.0.
  2. Once you've installed the tanzu binary, install the basic TKG group:
tanzu plugin install --group vmware-tkg/default
  1. With the basic tanzu cli set up, connect to the supervisor cluster as an administrator. This will open a browser window to gitlab.
tanzu context create SVC_CLUSTER_NAME --endpoint https://SUPERVISOR_IP
  1. Once you are logged in, check the cluster state
tanzu cluster list -n VSPHERE_NAMESPACE
  1. Once you've verified your cluster is visible in the namespace, you can grab the user kubeconfig file
tanzu cluster kubeconfig get CLUSTER_NAME -n VSPHERE_NAMESPACE --export-file KUBECONFIG_FILE_PATH

Now you have exported a kubeconfig file that can be shared among developers. This kubeconfig file does not contain any user credentials but relies on the tanzu cli and the pinniped-auth plugin to connect to Gitlab and provide user authentication.

Setting user rights on the cluster and/or namespace

The Authentication piece has been completed, but users still need the correct authorization on the vSphere namespace and/or workload cluster to do their job.
See the flowchart and explanation here

Developer/user tasks

As a developer, there are less steps to execute to be able to connect to the workload cluster.

Downloading and configuring the Tanzu cli

You can follow the same matrix as in the previous chapter to determine what Tanzu cli version you require. As mentioned above, for vSphere Supervisor on vSphere 8 this means version 1.1.0.

  1. Install the correct Tanzu cli version.
  2. Install the basic TKG group (this contains the required pinniped plugin)
tanzu plugin install --group vmware-tkg/default

Using the generated kubeconfig

As a part of the Administrator workflow, you as a developer or user should have received a kubeconfig file from a platform administrator.
You can now use the kubeconfig file as usual with kubectl. On first use, a browser window will open requiring you to log into Gitlab. Once logged in you can manage your resources according to what's allowed in the assigned RoleBinding or ClusterRoleBinding.