kubectl config use-context

When to Use kubectl config use-context

kubectl config use-context changes the active context in your kubeconfig. A context binds together a cluster endpoint, user credentials, and an optional default namespace. Switching contexts is how you move between clusters — development, staging, production — or between different user identities on the same cluster.

How Contexts Work

Each context in kubeconfig is a named triple:

contexts:
- name: production
  context:
    cluster: prod-cluster
    user: prod-admin
    namespace: default
- name: staging
  context:
    cluster: staging-cluster
    user: staging-developer
    namespace: staging

When you run kubectl config use-context production, kubectl sets current-context: production in the kubeconfig file. All subsequent commands use the prod-cluster endpoint with prod-admin credentials.

Safe Context Switching

Context switching modifies the kubeconfig file on disk. This means every terminal window using the same kubeconfig is affected. To avoid running commands against the wrong cluster:

# Always verify before running commands
kubectl config current-context
# Output: staging

# Switch and immediately verify
kubectl config use-context production
kubectl cluster-info

Using --context Instead of Switching

For one-off commands, the --context flag is safer because it does not modify the kubeconfig:

# Run against production without switching
kubectl get pods --context=production

# Compare resources across clusters
kubectl get nodes --context=staging
kubectl get nodes --context=production

This is particularly important in scripts where you need to interact with multiple clusters:

#!/bin/bash
for ctx in staging production; do
  echo "=== $ctx ==="
  kubectl get pods -n monitoring --context="$ctx"
done

Per-Terminal Context with KUBECONFIG

To isolate context switching per terminal session, set KUBECONFIG to a copy:

# In terminal 1 — working with staging
export KUBECONFIG=~/.kube/config
cp ~/.kube/config /tmp/kubeconfig-$$
export KUBECONFIG=/tmp/kubeconfig-$$
kubectl config use-context staging

# In terminal 2 — working with production (unaffected)
kubectl config current-context
# Still shows whatever was set before

Tools like kubectx simplify this workflow, but understanding the underlying mechanism is essential for interviews and for debugging.

Namespace Defaults per Context

Each context can define a default namespace. When you switch contexts, the default namespace changes too:

# Set a default namespace for a context
kubectl config set-context staging --namespace=staging

# Now switching to staging defaults all commands to the staging namespace
kubectl config use-context staging
kubectl get pods  # equivalent to kubectl get pods -n staging

This eliminates repetitive -n flags when you always work in a specific namespace per cluster.

Safety Patterns for Production

Accidental operations against production are a common incident cause. Consider these patterns:

# 1. Shell prompt showing current context (add to .bashrc/.zshrc)
export PS1="\$(kubectl config current-context 2>/dev/null) \w $ "

# 2. Alias with confirmation for production
alias kprod='echo "WARNING: PRODUCTION" && kubectl --context=production'

# 3. Use admission webhooks or OPA policies to block dangerous operations

Troubleshooting Context Switches

If switching fails or commands behave unexpectedly after switching:

# Verify the context exists
kubectl config get-contexts

# Check which kubeconfig file is being used
echo $KUBECONFIG  # empty means ~/.kube/config

# View the full merged config
kubectl config view --minify

# Test connectivity to the new context
kubectl cluster-info

Common issues include expired tokens (especially with cloud provider exec plugins), revoked certificates, or stale kubeconfig entries pointing to decommissioned clusters.