Skip to content
Kupe Cloud Kupe Cloud Kupe Cloud Docs

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 SSO 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 itRecommended
You, at your laptopOIDC kubeconfig
A teammate, also at a laptopOIDC kubeconfig
GitHub Actions / CIToken kubeconfig
Cron job, daemon, K8s jobToken kubeconfig

Person → OIDC. Machine → token.

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, neither flavour can be revoked on the spot. Token kubeconfigs embed a Kubernetes ServiceAccount token issued via the TokenRequest API, so there is nothing to revoke individually; let it expire or rotate the cluster credential. OIDC kubeconfigs are no different in practice: signing the user out of the console ends their browser SSO session and stops future silent re-authentication, but an access token already cached by kubelogin keeps working until it expires (up to 8 hours). Treat the remaining token lifetime as the real exposure window, and remove the user’s platform access if the leak warrants it.
Section titled “Related”