Kubernetes Cluster Access¶

This guide explains how to authenticate to Skatzi Kubernetes clusters using your Keycloak credentials.

Prerequisites¶

1. A Keycloak account in the skatzi realm
2. Membership in the appropriate Kubernetes access group for the cluster (e.g., mgmt-k8s-admins, prod-k8s-admins)
3. kubectl installed
4. kubelogin (OIDC authentication plugin) installed

Available Clusters¶

Additional clusters will be added as they are provisioned.

Install kubelogin¶

macOS (Homebrew)¶

brew install int128/kubelogin/kubelogin

Linux¶

# Download the latest release
curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
unzip kubelogin_linux_amd64.zip
sudo mv kubelogin /usr/local/bin/kubectl-oidc_login

Windows (Scoop)¶

scoop install kubelogin

Configure kubectl¶

Replace the placeholder values with the appropriate cluster details from the table above:

• <CLUSTER_NAME>: The name for this cluster in your kubeconfig (e.g., mgmt-cluster, prod-cluster)
• <OIDC_CLIENT_ID>: The OIDC client ID for the cluster (e.g., kubernetes-mgmt)
• <CONTEXT_NAME>: A name for the kubectl context (e.g., oidc-mgmt, oidc-prod)

Option 1: Add OIDC user to existing kubeconfig¶

If you already have a kubeconfig for the cluster, add the OIDC user:

# Add OIDC credentials (use a unique name per cluster)
kubectl config set-credentials oidc-<CLUSTER_NAME> \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://keycloak.prod.skatzi.com/realms/skatzi \
  --exec-arg=--oidc-client-id=<OIDC_CLIENT_ID>

# Create a context using the OIDC user
kubectl config set-context <CONTEXT_NAME> --cluster=<CLUSTER_NAME> --user=oidc-<CLUSTER_NAME>

Example for management cluster:

kubectl config set-credentials oidc-mgmt \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://keycloak.prod.skatzi.com/realms/skatzi \
  --exec-arg=--oidc-client-id=kubernetes-mgmt

kubectl config set-context oidc-mgmt --cluster=mgmt-cluster --user=oidc-mgmt

Option 2: Manual kubeconfig¶

Add the following to your ~/.kube/config, replacing placeholders:

users:
  - name: oidc-<CLUSTER_NAME>
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://keycloak.prod.skatzi.com/realms/skatzi
          - --oidc-client-id=<OIDC_CLIENT_ID>

contexts:
  - name: <CONTEXT_NAME>
    context:
      cluster: <CLUSTER_NAME>
      user: oidc-<CLUSTER_NAME>

Login Flow¶

1. Switch to the OIDC context or use it explicitly:

   # Switch default context
   kubectl config use-context <CONTEXT_NAME>
   
   # Or use explicitly
   kubectl --context=<CONTEXT_NAME> get nodes
   

2. On first use, your browser will open to the Keycloak login page.

3. Enter your Keycloak credentials (username and password).

4. After successful authentication, the browser will redirect and kubectl will complete the command.

5. Subsequent commands use the cached token until it expires (5 minutes).

Verify Access¶

Check your authenticated identity:

kubectl --context=<CONTEXT_NAME> auth whoami

Expected output:

ATTRIBUTE   VALUE
Username    https://keycloak.prod.skatzi.com/realms/skatzi#<your-username>
Groups      [<cluster-access-group> system:authenticated]

Troubleshooting¶

Clear cached tokens¶

If you need to re-authenticate or are having token issues:

rm -rf ~/.kube/cache/oidc-login

"Unauthorized" error¶

• Verify you are a member of the correct access group in Keycloak for the cluster
• Clear cached tokens and try again
• Check with your administrator if your group membership is correct

Browser doesn't open¶

• Ensure your default browser is set correctly
• Try running the command in a terminal that supports opening browsers
• Check if port 8000 or 18000 is available (kubelogin uses these for the callback)

"invalid_scope" error¶

The Kubernetes OIDC clients don't require extra scopes. Use the basic command without --oidc-extra-scope flags.

Connection refused¶

• Verify you can reach the Kubernetes API server for the cluster
• Check if you're on a network that can access the cluster (VPN may be required)

Security Notes¶

• Tokens are cached locally in ~/.kube/cache/oidc-login/
• Access tokens expire after 5 minutes (configurable in Keycloak)
• No client secrets or certificates are stored locally
• All authentication flows through Keycloak's secure OAuth2/OIDC
• Each cluster has its own OIDC client and access groups for isolation