Access and authentication

Why OpenID Connect

Your kubeconfig contains no password, token or key. Instead, kubectl asks kubelogin for a short-lived token whenever it needs one, and kubelogin gets it by signing you in through your browser, with GitHub, at https://auth.ctrlplane.run/dex (ctrlplane’s OpenID Connect provider).

That means:

• Nothing to leak. A kubeconfig that ends up in a repo or a chat gives nobody access.
• One identity everywhere. You’re the same user in the site and in kubectl, and suspending an account in ctrlplane removes its API access.
• No rotation chores. Tokens expire on their own (sessions last a day); kubelogin signs you in again when needed.

What’s in your kubeconfig

clusters:
- name: <you>-dev
  cluster:
    server: https://<id>.api.ctrlplane.run
    certificate-authority-data: …          # your control plane's own CA
users:
- name: oidc
  user:
    exec:                                    # kubectl runs: kubectl oidc-login get-token …
      command: kubectl
      args: [oidc-login, get-token, --oidc-issuer-url=https://auth.ctrlplane.run/dex,
             --oidc-client-id=ctrlplane-cli, --oidc-extra-scope=email, …]
contexts:
- name: <you>-dev
  context: {cluster: <you>-dev, user: oidc, namespace: <you>-dev}

kubelogin caches the token in ~/.kube/cache/oidc-login/. To sign in again from scratch, delete that directory.

On a machine without a browser

kubelogin signs you in through a local web page on port 8000 of the machine running kubectl. From a remote shell, forward that port and open the URL kubelogin prints in your own browser:

ssh -L 8000:localhost:8000 remote-host
kubectl get crds    # prints http://localhost:8000/…: open it locally

Who you are

You appear as github:<login>, for example github:alice:

kubectl auth whoami

What you may do

As an owner of a control plane you may:

• do anything in its namespace (named after the control plane): Secrets, ConfigMaps, ServiceAccounts, Roles and RoleBindings, leases, and your namespaced custom resources;
• manage CustomResourceDefinitions, and your custom resources in any namespace (many are cluster-scoped);
• read events in default, where events about cluster-scoped objects go.

You can’t create other namespaces, touch kube-system, or change the RBAC that ctrlplane manages for owners and controllers. Within your namespace, grant others access with ordinary Roles and RoleBindings, for example for a CI service account.

Tokens for automation

For CI or a dashboard, use a service account in your namespace instead of your own login. A new service account may only read your metrics and logs; grant it what it needs with a RoleBinding:

kubectl create serviceaccount ci
kubectl create rolebinding ci-edit --clusterrole=edit --serviceaccount=<you>-dev:ci
kubectl create token ci --duration=720h

edit covers the namespace’s built-in objects. For your custom resources, bind a Role that names their API group, for example:

kubectl create role vms --verb='*' --resource=virtualmachines.proxmox.example.com
kubectl create rolebinding ci-vms --role=vms --serviceaccount=<you>-dev:ci

Your controllers’ full access comes from their own credentials, which only ctrlplane issues; service accounts you create never get it.