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 Source: CKA Day 24 Source: CKA Day 25

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 kubectl create token for short-lived tokens
4. Inject the token into the CI/CD runner as a kubeconfig user.token field

For direct REST API calls from outside the cluster, you can also pass the ServiceAccount bearer token with curl instead of client certificates:

curl -k https://<control-plane-ip>:6443/api/v1/namespaces/default/pods \
  -H "Authorization: Bearer $(kubectl create token deployer -n dev)"

This pattern is increasingly preferred over long-lived client certificates for automation because tokens can be scoped and rotated easily. Source: CKA Day 25

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

Practical Practice

Exam-style hands-on tasks for this topic. Complete each task before reviewing the solution. Time yourself — CKA tasks average 5–7 minutes.

Task 1: Add a New Cluster, User, and Context You are asked to add cluster prod-cluster (server https://prod.example.com:6443, CA at /etc/kubernetes/ca.crt) and user admin (client cert /etc/kubernetes/admin.crt, key /etc/kubernetes/admin.key) to the kubeconfig, then create and switch to context prod-admin. Requirements: Use imperative kubectl config commands only. Verification: kubectl config current-context returns prod-admin. Solution:

kubectl config set-cluster prod-cluster --server=https://prod.example.com:6443 --certificate-authority=/etc/kubernetes/ca.crt
kubectl config set-credentials admin --client-certificate=/etc/kubernetes/admin.crt --client-key=/etc/kubernetes/admin.key
kubectl config set-context prod-admin --cluster=prod-cluster --user=admin
kubectl config use-context prod-admin
kubectl config current-context

Task 2: Switch Context and Verify You are asked to switch to the existing context named staging and confirm the active context. Requirements: Do not modify the kubeconfig file directly. Verification: kubectl config current-context outputs staging. Solution:

kubectl config use-context staging
kubectl config current-context

Task 3: Fix an Unable-to-Connect Error A kubectl command fails with Unable to connect to the server: dial tcp ...: connect: connection refused. You inspect the current context and discover the server URL points to an old IP. Requirements: Update the server URL in the current context to https://192.168.1.10:6443. Verification: kubectl cluster-info succeeds. Solution:

# View current cluster server
kubectl config view --minify | grep server
# Update the cluster server for the current context's cluster
kubectl config set-cluster $(kubectl config view --minify -o jsonpath='{.contexts[0].context.cluster}') --server=https://192.168.1.10:6443
kubectl cluster-info

Related Pages

• Kubernetes Authentication & Authorization — how kubeconfig credentials flow through the API server auth pipeline
• Kubernetes RBAC — permissions that the kubeconfig identity requests
• Kubernetes Service Account — embedding ServiceAccount tokens into kubeconfig for CI/CD automation
• Kubernetes Architecture — API server TLS and the request path from kubectl to etcd
• Kubeadm Cluster Setup — admin.conf generated by kubeadm init becomes the default kubeconfig for cluster administration
• 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
• Kubernetes Control Plane Troubleshooting — Day 38: certificate expiry breaks API server connectivity and kubeconfig validity

---

Tags: kubernetes kubeconfig kubectl security cka context-switching tls