A Kubernetes context is a triplet of cluster, user, and namespace that defines your current working environment for kubectl.
Let’s see this in action. Imagine you’re working with two clusters: dev and prod.
# List all available contexts
kubectl config get-contexts
# CURRENT NAME AUTHINFO CLUSTER NAMESPACE
# * dev-context dev-user dev-cluster default
# prod-context prod-user prod-cluster production
Here, the asterisk * indicates the dev-context is the currently active one. If you want to switch to prod-context, you’d run:
# Switch to the production context
kubectl config use-context prod-context
# Switched to context "prod-context".
Now, any kubectl command you run will target the prod-cluster using the prod-user credentials and the production namespace.
# Verify the current context
kubectl config current-context
# prod-context
This system of contexts is managed by your kubeconfig file, typically located at ~/.kube/config. This file is a YAML document that stores information about your clusters, authentication credentials, and the named contexts that combine these elements. When you use kubectl config use-context, you’re not changing any cluster configurations; you’re simply telling kubectl which entry in your local kubeconfig file to use for subsequent operations.
The core problem contexts solve is managing interactions with multiple Kubernetes clusters efficiently. Without them, you’d have to manually specify cluster endpoints, user credentials, and namespaces for every single command, which is error-prone and time-consuming. Contexts abstract this complexity into a single, easy-to-switch identifier.
Internally, when you execute a kubectl command, it reads your kubeconfig file, identifies the current context, and then uses the associated cluster API server URL, client certificate/key (or token), and default namespace to construct and send the request.
The specific levers you control are the names of your contexts, the clusters they point to, the users (authentication methods) they use, and the default namespaces within those clusters. You can also define multiple contexts pointing to the same cluster but with different users or namespaces, allowing for fine-grained control over your environment.
You can also rename contexts, delete them, or even merge multiple kubeconfig files. For instance, to merge a prod.yaml file into your main ~/.kube/config:
KUBECONFIG=~/.kube/config:~/.kube/prod.yaml kubectl config view --flatten > ~/.kube/config.tmp && mv ~/.kube/config.tmp ~/.kube/config
This command concatenates the two kubeconfig files and flattens the output, ensuring all cluster, user, and context definitions are in a single, valid file.
Most people know that kubectl config use-context switches their active context. What they often overlook is how kubectl prioritizes which kubeconfig file to read. If you have multiple kubeconfig files, kubectl follows a specific order: first, it checks the KUBECONFIG environment variable, which can be a list of files separated by colons. If KUBECONFIG is not set, it falls back to the default ~/.kube/config file. This hierarchy is crucial for managing different sets of credentials or cluster configurations without overwriting your main file.
The next concept you’ll encounter is managing service accounts and role-based access control (RBAC) within your chosen context.