On this page
Every kubectl command has to answer three questions: which cluster should it talk to, who are you, and which namespace should it use? The answers live in one file, the kubeconfig. You write them down once and kubectl reads them every time.
Think of kubeconfig as an address book for clusters. Instead of typing an API address, a username and a certificate on every command, you save them once and give each entry a short name.
kubectl looks for the file at ~/.kube/config on Linux and macOS, and at %USERPROFILE%\.kube\config on Windows. One file can describe many clusters, many users and many environments.
What you will learn
- How the three building blocks (clusters, users and contexts) fit together
- How to read a kubeconfig file line by line
- The commands you will use every day to inspect, switch and edit contexts
- How to work with several kubeconfig files at the same time
The big picture
A kubeconfig has three lists. A context pairs one cluster with one user, and optionally sets a default namespace. One context is always marked as the current one.
| Section | What it stores | Real-world analogy |
|---|---|---|
| clusters | API server address and CA certificate of each cluster | The address of an office building |
| users | Credentials (certificate, token or username/password) for each identity | Your employee ID badge |
| contexts | A named pairing of a cluster, a user and an optional namespace | A saved shortcut: "go to building A as employee 42" |
Anatomy of a kubeconfig file
Below is a minimal kubeconfig with one cluster, one user that authenticates with a bearer token, and one context that ties them together.
kubectl apply on it. Save it as ~/.kube/config, or point to it with the KUBECONFIG environment variable.clusters
Each entry describes one Kubernetes API server. Two fields matter most: server (the HTTPS address of the API) and certificate-authority-data (the base64-encoded CA certificate that proves the server is who it says it is).
users
Each entry holds the credentials kubectl shows to the API server. The most common types are:
- client-certificate-data + client-key-data: mutual TLS, most common in kubeadm clusters
- token: a bearer token, common for ServiceAccounts and OIDC flows
- exec: an external command that produces a token, used by cloud providers such as EKS, GKE and AKS
contexts
A context is a named combination of a cluster and a user, with an optional namespace. Switching context switches all three at once.
current-context
The top-level current-context field tells kubectl which context to use when you do not name one. You can read it, set it and switch it with commands, so you never need to edit the file by hand.
kubectl config view hides secrets, while --raw prints them in plain text.Everyday commands
These five cover most of your daily work:
| I want to… | Command |
|---|---|
| See which context is active | kubectl config current-context |
List all contexts (the active one has a *) | kubectl config get-contexts |
| Switch to another context | kubectl config use-context <name> |
| Change the default namespace of the active context | kubectl config set-context --current --namespace=<ns> |
| Print the whole config with secrets hidden | kubectl config view |
Inspect what is in the file
Add a cluster, a user and a context
You can register new entries from the command line instead of editing the YAML. First the cluster:
Then a user. Use a bearer token…
…or a client certificate and key:
Finally the context that pairs them, with a default namespace:
Remove entries you no longer need
Hands-on: manage two clusters
Imagine you work against two clusters: a local development cluster created with kind, and a remote staging cluster. You will register both, create a context for each environment and switch between them.
Step 1 — Check where you start
See which contexts already exist:
Step 2 — Confirm the development cluster
If you use kind, running kind create cluster already adds the cluster entry for you. Verify it:
Step 3 — Add the staging cluster
Your ops team gives you the API server address, a CA certificate file and a bearer token. Register them:
Step 4 — Create one context per environment
A context for development that defaults to the dev namespace:
A context for staging that defaults to the staging namespace:
Step 5 — Switch to development and verify
Expected output:
Confirm you are talking to the right cluster by listing its nodes:
Step 6 — Switch to staging
use-context command replaces long URLs and flags. Before any destructive command, run kubectl config current-context to confirm which cluster you are about to change.Using more than one kubeconfig file
You do not have to keep everything in one file. Three techniques cover most needs.
Combine files on the fly with KUBECONFIG
Set KUBECONFIG to a list of file paths, separated by a colon (a semicolon on Windows). Kubernetes merges them in memory, so kubectl config get-contexts lists the contexts from every file.
Merge files permanently
To collapse several files into one, combine KUBECONFIG with kubectl config view --flatten:
cp overwrites ~/.kube/config. Keep the backup until you have checked the merged file with kubectl config get-contexts.Override the file for a single command
Use the --kubeconfig flag to target one file for one command, without touching environment variables or your default file:
Which file wins?
kubectl picks its kubeconfig in this order, highest priority first:
- The
--kubeconfigflag on the command line - The
KUBECONFIGenvironment variable (a merged list of files) - The default file at
~/.kube/config
Summary
The kubeconfig file tells kubectl how to reach your clusters and who you are. It has three sections: clusters (API server addresses), users (credentials) and contexts (named pairings of cluster, user and namespace).
kubectl config get-contextsshows every environment you can reach.kubectl config use-context <name>switches between them instantly.kubectl config set-context --current --namespace=<ns>changes your default namespace.KUBECONFIGlets you work with several files at once, and--kubeconfigoverrides the file for a single command.- Keep kubeconfig private: it holds credentials.
Once you are comfortable with contexts, multi-cluster work, CI/CD pipelines and limited namespace access for teammates all build on the same few commands.