Connecting with kubectl

kubectl talks to a cluster using a kubeconfig file. In Hyperkub you get one by creating a cluster credential.

Why credentials are separate objects

A credential is issued per person or per machine, not per cluster. That means you can revoke one laptop’s access without disturbing anyone else, and you can see which credentials exist for a cluster.

Credentials are also short-lived. Expect to reissue them periodically rather than storing one forever.

Create and download

1. Open the cluster in the control plane.
2. Go to Credentials → Create credential.
3. Download the file when prompted.

Caution

The file contains everything needed to administer the cluster. Treat it like a private key: never commit it, and prefer a secret store for CI.

Point kubectl at it

For a single cluster, the simplest approach is an environment variable:

export KUBECONFIG=~/.kube/hyperkub-production.yaml
kubectl get nodes

To make it the default, save it as ~/.kube/config instead.

Working with several clusters

KUBECONFIG accepts a list, and kubectl merges the files:

export KUBECONFIG=~/.kube/config:~/.kube/hyperkub-production.yaml

List what merged, then switch between them:

kubectl config get-contexts
kubectl config use-context hyperkub-production

To avoid running the right command against the wrong cluster, set the context per command instead of switching globally:

kubectl --context hyperkub-staging get pods

Use in CI

Do not commit the kubeconfig. Store its contents in a masked CI variable and write it to disk at job start:

deploy:
  script:
    - echo "$KUBECONFIG_PRODUCTION" > "$CI_PROJECT_DIR/kubeconfig"
    - export KUBECONFIG="$CI_PROJECT_DIR/kubeconfig"
    - kubectl rollout restart deployment/api

Issue a dedicated credential for CI so it can be revoked independently of anyone’s laptop.

Troubleshooting

Unable to connect to the server: dial tcp ... i/o timeout

The cluster is probably not running yet. Check its status in the control plane — a cluster in provisioning does not answer.

error: You must be logged in to the server (Unauthorized)

The credential has expired or been revoked. Create a new one.

kubectl get nodes returns nothing

You are connected, but the pool has no nodes. Check the pool’s node count.

The wrong cluster responds

You have several files merged and the active context is not the one you meant. Run kubectl config current-context to confirm.