Skip to main content

Configure kubectl for the Hub

Overview​

This page configures a kubectl context named hub that talks to the Upbound Platform Hub. The Hub serves a Kubernetes-style API, so once you configure kubectl, standard commands like get and describe work with Hub resources like controlplanes, spaces, and resources.

Prerequisites​

  • The Hub's API URL, such as https://<hub-host>. If the 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/main/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, environment variables, and token-resolution order.

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.

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:

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

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 the Hub API:

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 the cluster stanza. Confirm you set --certificate-authority (or certificate-authority in the kubeconfig file) to the correct path.

Commands stop working after a while​

Your cached tokens expired. Log in again:

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

Next steps​

  • Connect a control plane: Register a control plane and deploy a connector to observe its resources.
  • Connect a Space: Register a Space and deploy a connector to observe its resources and control planes.
  • Query your fleet: Search, filter, and count the resources the Hub aggregates from your connected control planes.
  • Access management: Grant users and groups access across the Hub.
  • CLI and AI agent login: Log in interactively and print a token for other clients, instead of wiring up a kubectl context.