Kubeconfig Structure

The kubeconfig file is how kubectl knows which cluster to talk to and how to authenticate. By default, kubectl looks for this file at ~/.kube/config. Understanding its three main sections is essential for working with multiple Kubernetes environments.

The Three Sections

Every kubeconfig file has three top-level sections: clusters, users, and contexts.

apiVersion: v1
kind: Config
current-context: dev-cluster

clusters:
  - name: dev-cluster
    cluster:
      server: https://dev.example.com:6443
      certificate-authority-data: LS0tLS1CRUdJ...
  - name: prod-cluster
    cluster:
      server: https://prod.example.com:6443
      certificate-authority: /path/to/ca.crt

users:
  - name: dev-admin
    user:
      client-certificate-data: LS0tLS1CRUdJ...
      client-key-data: LS0tLS1CRUdJ...
  - name: prod-readonly
    user:
      token: eyJhbGciOiJSUzI1NiIs...

contexts:
  - name: dev
    context:
      cluster: dev-cluster
      user: dev-admin
      namespace: default
  - name: prod
    context:
      cluster: prod-cluster
      user: prod-readonly
      namespace: production

How the Sections Connect

• clusters define API server endpoints and CA certificates
• users define authentication credentials (certificates, tokens, or auth plugins)
• contexts bind a cluster to a user and optionally set a default namespace

The current-context field tells kubectl which context to use when no --context flag is provided.

Viewing Your Config

# See the full kubeconfig
kubectl config view

# See just the current context
kubectl config current-context

Key Takeaways

• The kubeconfig lives at ~/.kube/config by default
• Clusters, users, and contexts are independent entries that get linked together
• The current-context field determines your active connection