Skip to content

6.08 KubeConfig in Kubernetes

🎯 What is KubeConfig?

KubeConfig is a YAML configuration file used by kubectl to:

  • Connect to Kubernetes API Server
  • Authenticate using client certificates
  • Select cluster, user, and namespace context

Without kubeconfig, you would need to run:

kubectl get pods \
  --server https://my-kube-playground:6443 \
  --client-key admin.key \
  --client-certificate admin.crt \
  --certificate-authority ca.crt

KubeConfig eliminates this repetition.

📁 Default Location

$HOME/.kube/config

Override with:

kubectl --kubeconfig=my-config.yaml get pods

🧩 KubeConfig Structure

A kubeconfig file contains three main sections:

Section Purpose
clusters API server endpoints
users Authentication credentials
contexts Link user + cluster (+ namespace)

🏗 Basic Example

apiVersion: v1
kind: Config

clusters:
- name: my-kube-playground
  cluster:
    certificate-authority: /etc/kubernetes/pki/ca.crt
    server: https://my-kube-playground:6443

users:
- name: my-kube-admin
  user:
    client-certificate: /etc/kubernetes/pki/users/admin.crt
    client-key: /etc/kubernetes/pki/users/admin.key

contexts:
- name: my-kube-admin@my-kube-playground
  context:
    cluster: my-kube-playground
    user: my-kube-admin
    namespace: default

current-context: my-kube-admin@my-kube-playground

🔗 How Context Works

Context binds:

  • Cluster
  • User
  • Namespace (optional)

Switch context:

kubectl config use-context prod-user@production

View current config:

kubectl config view

📦 Multiple Clusters Example

  • development
  • production
  • google
  • my-kube-playground
  • admin
  • dev-user
  • prod-user
  • admin@production
  • dev@google
  • prod-user@production

📌 Namespaces in Context

You can define namespace per context:

context:
  cluster: production
  user: admin
  namespace: finance

Now:

kubectl get pods

Automatically runs in finance namespace.

🔐 Certificates in KubeConfig

Two ways to define CA:

Option 1: File Path

certificate-authority: /etc/kubernetes/pki/ca.crt

Option 2: Embedded (Base64)

certificate-authority-data: LS0tLS1CRUdJTiBDRV...

Encode certificate:

cat ca.crt | base64 -w 0

Decode:

echo "<BASE64_DATA>" | base64 --decode

🛡 Production Best Practices

✅ DO

Success

  • Restrict kubeconfig file permissions (600)
  • Use separate kubeconfig per environment
  • Rotate certificates regularly
  • Use short-lived client certificates
  • Store production kubeconfigs securely
  • Use RBAC to limit privileges

❌ DON'T

Danger

  • Do NOT share admin kubeconfig publicly
  • Do NOT commit kubeconfig to Git
  • Do NOT embed long-lived credentials
  • Do NOT use admin context for automation
  • Do NOT mix production and dev contexts carelessly

🚨 Common Production Risks

Issue Risk
Stolen kubeconfig Full cluster access
Wrong current-context Deploy to wrong cluster
Expired client cert kubectl failures
Embedded cert exposure Secret leakage

🔄 Operational Commands

kubectl config get-contexts
kubectl config current-context
kubectl config use-context <name>
kubectl config set-context
kubectl config delete-context

🎯 Summary

  • KubeConfig manages cluster access configuration
  • Context links user + cluster (+ namespace)
  • Supports multiple environments
  • Handles client certificates
  • Must be secured like a private key

Quote

A kubeconfig file is effectively your cluster access passport — protect it like root credentials.