Skip to main content
Version: 1.2

Configure kubectl for the Hub

Overview​

This page sets up a kubectl context named hub that signs you in to Hub. Once the context works, Use Hub APIs with kubectl covers how to work with Hub APIs through it.

Prerequisites​

  • Your Hub API URL, such as https://<hub-host>, which your platform team provides. If Hub isn't served with a publicly trusted certificate, you also need its CA certificate.
  • An identity in an OIDC provider registered with the Hub, for interactive login. For machine or CI environments, provide an IdP-issued JWT instead, covered under Log in to the Hub.
  • kubectl installed.

Step 1: Install hub-credential-helper​

hub-credential-helper is a CLI that authenticates you to the Hub. It runs the device-authorization and token-exchange flows to get a Hub token, caches it, and refreshes it as it expires.

Download the binary for your platform:

os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m)
case "$arch" in
  x86_64) arch=amd64 ;;
  aarch64) arch=arm64 ;;
esac
curl -fsSLo hub-credential-helper \
  "https://storage.googleapis.com/upbound-hub-artifacts/stable/v1.2/current/bin/${os}_${arch}/hub-credential-helper"
chmod +x hub-credential-helper
sudo mv hub-credential-helper /usr/local/bin/

Verify the install:

hub-credential-helper --help

hub-credential-helper --help also documents the full flag set and environment variables.

Step 2: Log in to the Hub​

Set the Hub URL used by the commands that follow:

HUB_URL=https://<hub-host>

Log in:

hub-credential-helper login --hub-url="$HUB_URL"

The helper prints a verification URL and code and opens your browser. Approve the request there to sign in through the Hub's identity provider. The helper then caches a Hub access token and a refresh token, so you don't log in again until the refresh token expires.

If the Hub isn't served with a publicly trusted certificate, pass its CA certificate to the helper with --ca-file. The helper makes its own TLS connections to the Hub and doesn't read the CA from your kubeconfig:

hub-credential-helper login --hub-url="$HUB_URL" --ca-file=/path/to/ca.crt
CI and headless environments

With no browser to complete the device flow, skip the interactive login. Write an IdP-issued JWT (such as a mounted Kubernetes ServiceAccount token) to a file and add --token-file=/path/to/token to the exec args when you create the kubectl context in the next step. The helper exchanges it for a Hub token. See Workload identities for how a CI job or ServiceAccount gets that JWT and what its Hub username looks like.

Step 3: Add the Hub context to your kubeconfig​

Add a hub context that runs hub-credential-helper to fetch and refresh tokens, so kubectl authenticates on its own.

The recommended commands merge the context into your existing kubeconfig. The alternative writes a standalone kubeconfig file that you point KUBECONFIG at per command.

Merge a hub context into your existing kubeconfig:

kubectl config set-cluster hub --server="$HUB_URL"

kubectl config set-credentials hub-user \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-command=hub-credential-helper \
  --exec-arg=exec-credential \
  --exec-arg=--hub-url="$HUB_URL" \
  --exec-interactive-mode=IfAvailable

kubectl config set-context hub --cluster=hub --user=hub-user

For a Hub served with a private CA, include its certificate on the cluster, and pass it to the helper with --ca-file:

kubectl config set-cluster hub --server="$HUB_URL" \
  --certificate-authority=/path/to/ca.crt --embed-certs=true

kubectl config set-credentials hub-user \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-command=hub-credential-helper \
  --exec-arg=exec-credential \
  --exec-arg=--hub-url="$HUB_URL" \
  --exec-arg=--ca-file=/path/to/ca.crt \
  --exec-interactive-mode=IfAvailable

Step 4: Verify the context​

Confirm the context authenticates and reaches the Hub.

kubectl auth whoami shows your username and groups as the Hub sees them, which confirms authentication works. See Verifying your identity for how to read the output:

kubectl --context=hub auth whoami

A read such as get controlplanes confirms the context reaches Hub:

kubectl --context=hub get controlplanes

The same context works against IAM resources too:

kubectl --context=hub get realmrolebindings -n <realm>
kubectl --context=hub get identityproviders

What a get returns depends on the caller's access, not just the resource type. See Filtering and self-review for why.

Troubleshooting​

The helper isn't found​

kubectl runs hub-credential-helper as an exec plugin, so the binary must be on your PATH:

command -v hub-credential-helper

If this prints nothing, reinstall the binary or move it onto your PATH.

auth whoami fails​

Check the identity the Hub resolves for you:

kubectl --context=hub auth whoami

A failure points to the wrong Hub URL (check --hub-url and the cluster server) or an identity provider the Hub doesn't recognize.

Certificate errors reaching the Hub​

A Hub served with a private CA needs its certificate in two places: in the cluster stanza, for kubectl, and in the helper's --ca-file flag, for login and token refresh. Confirm you set --certificate-authority (or certificate-authority in the kubeconfig file) and the --ca-file exec argument to the correct path. Pass --ca-file to hub-credential-helper login too.

Commands stop working after a while​

Your cached tokens expired. Log in again:

hub-credential-helper login --hub-url="$HUB_URL"

Next steps​