Cluster Access - Kubeconfig

Cluster Access - Kubeconfig

Private Cloud Director provides Kubernetes cluster access via kubeconfig — a YAML file containing cluster connection details and authentication configuration. For more information, refer to the Kubernetes kubeconfig documentation.

The kubeconfig file works with kubectl, Kubernetes client libraries (Go, Python, Java, etc.), and any tool that supports the standard kubeconfig format.

Download Kubeconfig

In order to access your clusters outside of the Private Cloud Director UI, you need a kubeconfig file that is properly configured for authenticating with your cluster.

The kubeconfig file can be obtained by following these steps:

1. In the Private Cloud Director UI, navigate to the Kubernetes cluster you want to access.
2. Click the Download Kubeconfig button in the top right of the page.

The kubeconfig file will be downloaded to your system's default Downloads folder.

Using kubeconfig

To connect to the cluster using the kubeconfig, follow these steps:

1. Download the kubeconfig (see above).
2. Install kubectl on your machine.
3. Install kubelogin, the OIDC plugin for kubectl:

   # Homebrew (macOS and Linux)
   brew install kubelogin
   
   # Krew (macOS, Linux, Windows and ARM)
   kubectl krew install oidc-login
   
   # Chocolatey (Windows)
   choco install kubelogin

   Alternatively, you can install kubelogin manually by downloading the binary from the releases page and placing it in your PATH as a kubectl plugin:

   unzip kubelogin_linux_amd64.zip -d /tmp/kubelogin/
   mv /tmp/kubelogin/kubelogin /usr/local/bin/kubectl-oidc_login
   chmod +x /usr/local/bin/kubectl-oidc_login

   Verify the plugin is detected:

   kubectl plugin list
   # Expected output:
   # The following compatible plugins are available:
   # /usr/local/bin/kubectl-oidc_login

4. Export the KUBECONFIG environment variable in your terminal:

   export KUBECONFIG=~/Downloads/<cluster-name>.kubeconfig

5. Use kubectl to access the resources on the cluster:

   • The first time you log in, you will be redirected to a browser page granting your Private Cloud Director account access to the Kubernetes workloads.
   • Once authenticated, use kubectl normally. For example:

     kubectl get nodes

To skip the browser-based login and authenticate directly in the terminal, add --grant-type=password as an argument to the oidc-login command in your kubeconfig. This will prompt for your username and password in the terminal instead.

Troubleshooting

• kubelogin not found — Ensure kubelogin is installed and available on your PATH. See the kubelogin installation guide.
• Browser does not open for OIDC login — Verify that your default browser is configured and that the redirect URI is reachable from your machine.
• KUBECONFIG not set — If kubectl cannot find your cluster, make sure the KUBECONFIG environment variable points to the correct file path.