Kubernetes Kubeconfig

The client-side credential bundle that tells kubectl which cluster to talk to, how to authenticate, and which Namespace to target by default. Mastering kubeconfig context switching is an essential CKA exam skill. Source: CKA Day 22 Source: CKA Day 23

File Structure

A kubeconfig file (default ~/.kube/config) contains three top-level sections plus a current-context pointer:

apiVersion: v1
kind: Config
clusters:
- name: production
  cluster:
    server: https://prod-api.example.com:6443
    certificate-authority-data: <base64-ca-cert>
users:
- name: admin
  user:
    client-certificate-data: <base64-client-cert>
    client-key-data: <base64-client-key>
contexts:
- name: prod-admin
  context:
    cluster: production
    user: admin
    namespace: default
current-context: prod-admin

Clusters

Each cluster entry defines:

• server — The API server HTTPS endpoint
• certificate-authority-data — Base64-encoded CA certificate used to verify the API server’s TLS certificate
• insecure-skip-tls-verify: true — Dangerous flag that disables TLS verification (never use in production)

Users

Each user entry defines authentication credentials. Kubernetes supports multiple credential types per user:

Credential Field	Authentication Method
client-certificate-data + client-key-data	X.509 client certificate
token	Bearer token (static or ServiceAccount token)
username + password	Basic auth (deprecated)
exec	External credential plugin (e.g., aws-iam-authenticator, kubelogin for OIDC)

Contexts

A context is a named tuple that binds:

• cluster — Which API server endpoint to use
• user — Which credentials to present
• namespace — The default Namespace for kubectl commands (optional; defaults to default)

Switching contexts is the primary way to move between clusters or assume different identities:

kubectl config use-context prod-admin

Imperative kubectl config Commands

The kubectl config subcommand manipulates kubeconfig without hand-editing YAML:

Task	Command
View current config	kubectl config view
View raw file	kubectl config view --raw
Switch context	kubectl config use-context <name>
Set current namespace	kubectl config set-context --current --namespace=<ns>
Add cluster	kubectl config set-cluster <name> --server=<url> --certificate-authority=<path>
Add credentials	kubectl config set-credentials <name> --client-certificate=<path> --client-key=<path>
Add context	kubectl config set-context <name> --cluster=<cluster> --user=<user> --namespace=<ns>
Delete context	kubectl config delete-context <name>

Exam speed tip: kubectl config current-context confirms where you are before running destructive commands. Many CKA tasks begin with a context switch, and answering in the wrong cluster is an instant zero. Source: CKA Day 22

Multiple Kubeconfig Files

You can merge or select kubeconfig files via the KUBECONFIG environment variable:

export KUBECONFIG=~/.kube/config:~/.kube/prod-config
kubectl config view --merge

This is useful for separating personal, staging, and production credentials. The files are merged in memory; no file is modified unless you explicitly write back with --merge and redirection.

Context in CI/CD and Automation

In automated pipelines, ServiceAccount tokens are preferred over long-lived client certificates. The typical pattern:

1. Create a dedicated ServiceAccount (e.g., deployer)
2. Grant it a minimal Role or ClusterRole (e.g., edit in a single Namespace)
3. Extract the token from the ServiceAccount’s Secret or use projected volume tokens
4. Inject the token into the CI/CD runner as a kubeconfig user.token field

This avoids storing human admin certificates in build systems and limits blast radius via least-privilege RBAC. Source: CKA Day 22

Adding a New User: Practical Workflow

When creating a new user via client certificates (common in CKA security tasks), three commands wire the identity into kubeconfig:

# 1. Add the user's credentials (embeds cert/key as base64 data)
kubectl config set-credentials krishna \
  --client-certificate=./krishna.crt \
  --client-key=./krishna.key
 
# 2. Create a context binding user + cluster
kubectl config set-context krishna \
  --cluster=kind-cka-cluster-2 \
  --user=krishna
 
# 3. Switch to the new context
kubectl config use-context krishna
 
# Verify
kubectl config current-context
kubectl config view --raw

Certificate expiry trap: If the client certificate expires (e.g., set with 1-day validity during CSR creation), kubectl returns Unauthorized or certificate errors. Regenerate via the CSR workflow: create CSR → kubectl certificate approve → extract signed cert → re-run set-credentials with the new certificate. Source: CKA Day 23

Common Pitfalls

Pitfall	Symptom	Fix
Wrong context	Commands affect unexpected cluster	kubectl config current-context and kubectl config use-context
Expired certificate	x509: certificate has expired	Renew certs with kubeadm certs renew all or regenerate client cert
Missing namespace	Commands land in default instead of target	kubectl config set-context --current --namespace=<target>
CA mismatch	x509: certificate signed by unknown authority	Ensure certificate-authority-data matches the cluster CA
Token in shell history	Security leak	Use exec plugins or credential helpers instead of inline tokens

Related Pages

• Kubernetes Authentication & Authorization — how kubeconfig credentials flow through the API server auth pipeline
• Kubernetes RBAC — permissions that the kubeconfig identity requests
• Kubernetes Architecture — API server TLS and the request path from kubectl to etcd
• TLS Fundamentals — certificate anatomy and the CA trust chain that kubeconfig validates
• Kubernetes Namespaces — how the namespace field in a context sets the default scope
• CKA Certification — exam tasks requiring rapid context switches and kubeconfig edits

---

Tags: kubernetes kubeconfig kubectl security cka context-switching tls