Skip to content

Cluster Access

Connect kubectl, Helm, and other Kubernetes tools to a Kupe cluster.

Every cluster offers two kubeconfig flavours, downloadable from the cluster’s CLI Access dialog in the console. Pick the one that matches who’s using it.

OIDC kubeconfig, for engineers

Section titled “OIDC kubeconfig, for engineers”

The recommended option for engineers working interactively.

Sign in with the same credentials you use for the console. The kubeconfig holds no long-lived secrets. It triggers a browser sign-in when you first run kubectl, and the resulting access token is valid for 8 hours before another sign-in is needed.

Setup

  1. Install kubelogin, the small helper that brokers the browser sign-in for kubectl.

  2. In the console, open your cluster → CLI Access → Download OIDC kubeconfig.

  3. Use it:

    Terminal window
    kubectl --kubeconfig ./<cluster>-oidc.kubeconfig get ns

The first command opens your browser; subsequent commands reuse the cached token until it expires.

Token kubeconfig, for automation

Section titled “Token kubeconfig, for automation”

The right option for CI pipelines, GitHub Actions, scheduled jobs, and anything that can’t open a browser.

The token is embedded in the kubeconfig and you choose the lifetime when you generate it. Available lifetimes: 8 hours, 24 hours, 7 days, 30 days, 90 days, 365 days. Shorter is safer.

Setup

  1. In the console, open your cluster → CLI Access → Download token kubeconfig, picking the shortest lifetime that fits your workflow.

  2. Use it:

    Terminal window
    kubectl --kubeconfig ./<cluster>-token.kubeconfig get pods -A

No additional tooling is required; kubectl consumes the embedded token directly.

Choosing between them

Section titled “Choosing between them”
Who’s using it Recommended
You, at your laptop OIDC kubeconfig
A teammate, also at a laptop OIDC kubeconfig
GitHub Actions / CI Token kubeconfig
Cron job, daemon, K8s job Token kubeconfig

Person → OIDC. Machine → token.

A shell in a pod, from the console

Section titled “A shell in a pod, from the console”

You do not need a kubeconfig on your machine to get a shell inside a running container. Open the cluster in the console, find the pod, and use the terminal on its detail page.

Your tenant role controls terminal access. Read-only members cannot open a pod shell. The image must contain a shell; for images without one, use logs or kubectl debug with a suitable debugging image.

Keeping it safe

Section titled “Keeping it safe”
  • A kubeconfig is a credential. Treat it like a password.
  • Don’t commit kubeconfigs to git. Use a secret manager for CI.
  • Pick the shortest token lifetime that gets the job done; rotate the long ones.
  • If a kubeconfig leaks, contact support promptly. Issued tokens can remain usable until expiry, so removing a browser session alone is insufficient.
Section titled “Related”