kubectl config set-context

When to Use kubectl config set-context

kubectl config set-context is used to create or modify context entries in your kubeconfig file. A context is a named combination of cluster, user, and default namespace. This command does not switch the active context — it only defines or updates context entries.

Setting a Default Namespace

The most common use case is setting a default namespace for the current context so you don't have to type -n <namespace> on every command:

# Set the default namespace to "development"
kubectl config set-context --current --namespace=development

# Now these are equivalent:
kubectl get pods                   # uses "development" namespace
kubectl get pods -n development    # explicit, same result

This is especially useful when you work in a single namespace for extended periods. Verify the change with:

kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}'
# Output: development

Creating New Contexts

When you have cluster and user entries but need to assemble them into a usable context:

# First, check available clusters and users
kubectl config view -o jsonpath='{.clusters[*].name}'
kubectl config view -o jsonpath='{.users[*].name}'

# Create a context combining them
kubectl config set-context staging \
  --cluster=staging-cluster \
  --user=staging-developer \
  --namespace=staging

# Switch to the new context
kubectl config use-context staging

Modifying Existing Contexts

You can update individual fields of an existing context without redefining everything:

# Change only the namespace of the "production" context
kubectl config set-context production --namespace=monitoring

# Change the user for a context
kubectl config set-context production --user=read-only-user

Unspecified fields remain unchanged. This makes it easy to adjust a single parameter.

The --current Flag

The --current flag targets whichever context is currently active, saving you from typing the context name:

# Without --current (must know the name)
kubectl config set-context my-context --namespace=app

# With --current (works regardless of context name)
kubectl config set-context --current --namespace=app

This is particularly useful in scripts that should work across different environments without hardcoding context names.

Multi-Team kubeconfig Setup

In organizations with multiple teams sharing clusters, you can create per-team contexts with appropriate namespace defaults:

# Team A gets their namespace by default
kubectl config set-context team-a \
  --cluster=shared-cluster \
  --user=team-a-user \
  --namespace=team-a

# Team B gets their namespace by default
kubectl config set-context team-b \
  --cluster=shared-cluster \
  --user=team-b-user \
  --namespace=team-b

Each developer switches to their team context and automatically targets the correct namespace.

Validation and Cleanup

set-context does not validate that the referenced cluster or user exists. You can create a context with non-existent references:

# This succeeds even if "ghost-cluster" doesn't exist
kubectl config set-context broken --cluster=ghost-cluster --user=nobody

It will fail only when you try to use the context. To find and clean up orphaned contexts:

# List all contexts
kubectl config get-contexts

# Delete a context
kubectl config delete-context broken

# Verify
kubectl config get-contexts

Scripting Patterns

In CI/CD pipelines, set-context is used to dynamically configure access:

#!/bin/bash
# Configure cluster access from environment variables
kubectl config set-cluster ci-cluster --server="$K8S_SERVER" --certificate-authority="$CA_FILE"
kubectl config set-credentials ci-user --token="$K8S_TOKEN"
kubectl config set-context ci --cluster=ci-cluster --user=ci-user --namespace="$DEPLOY_NS"
kubectl config use-context ci

# Deploy
kubectl apply -f manifests/

This pattern is common in GitHub Actions, GitLab CI, and Jenkins pipelines where the kubeconfig is built from secrets at runtime.