Cluster Configuration

kubeconfig Anatomy

A kubeconfig answers two questions: which cluster, and which identity.

clusters:
- name: prod
  cluster:
    server: https://api.prod:6443
    certificate-authority-data: <base64 CA>
users:
- name: alice
  user: { client-certificate-data: <base64 cert>, client-key-data: <base64 key> }
contexts:
- name: prod-alice
  context: { cluster: prod, user: alice, namespace: payments }
current-context: prod-alice

kubectl reads $KUBECONFIG (colon-separated paths merged left to right) and then ~/.kube/config. Only current-context is active. A context binds one cluster to one user plus a default namespace; user entries may hold client certs, bearer tokens, or an exec plugin such as the AWS or gcloud credential helper.

Multi-Cluster Workflows

kubectl config get-contexts
kubectl config use-context prod-alice
kubectl --context=staging get nodes
KUBECONFIG=~/.kube/prod:~/.kube/staging kubectl config get-contexts
kubectl config set-context --current --namespace=payments
kubectl config delete-cluster old-ephemeral

For automation, prefer short-lived credentials: cloud helpers refresh tokens on demand through exec plugins instead of embedding long-lived secrets. Keep the file private — chmod 600 ~/.kube/config — because it often carries cluster-admin certificates.

A naming scheme like env-role-team on contexts prevents applying staging manifests to production during a stressful incident.

Pitfalls and Debugging

Pitfall 1 — certificate SAN mismatches. "x509: certificate signed by unknown authority" or "certificate is valid for ... not this host" usually means the wrong CA or an apiserver certificate missing the endpoint's SAN — common when the API server is first reached through a new load balancer DNS name. Compare kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}' against the certificate SANs.

Pitfall 2 — stale exec-plugin tokens. Expired cached tokens surface as 401 or 403; re-run the cloud login before blaming RBAC.

Interview-ready: explain the cluster/user/context split, then your debug order: current-context, token or certificate expiry, kubectl auth can-i list pods --namespace=prod, and finally apiserver audit logs for the rejected request.