kubectl Set Context: Switch Clusters and Namespaces Safely

Most kubectl mistakes I want to avoid come down to one question: which cluster and namespace is this command about to hit? Contexts are how kubectl answers that, and kubectl config set-context is the command that builds and edits them.

This post walks through creating, editing and overriding contexts in a safe local lab, then covers habits that keep you out of trouble on real clusters. If you are new to kubectl itself, start with Kubernetes on a Mac.

Short answer: kubectl config set-context vs use-context

kubectl config set-context creates a context or edits an existing one. kubectl config use-context selects which context kubectl uses by default. Editing a context with set-context does not switch to it, unless you edit the one that is already current.

According to the official kubectl config set-context reference, fields you supply are merged into an existing context, and --current modifies the current context.

Commands at a glance

What a kubectl context is

A context is a named bundle in your kubeconfig file: a cluster, a user (credentials), and optionally a default namespace. It is only a local mapping on your machine. Creating or editing a context does not create anything in a cluster and does not contact it.

The kubeconfig also stores a current-context value, which says which bundle kubectl uses when you do not say otherwise. For how kubeconfig files are located and merged, see the official organize cluster access with kubeconfig page.

1. Keep the lab away from your real kubeconfig

I ran everything below on macOS on 2026-11-09 with kubectl v1.35.0 (Kustomize v5.7.1). The kubeconfig lived in a temporary directory, the server address was the fake https://example.invalid, the user was an empty placeholder, and no real cluster was contacted.

To reproduce that, point KUBECONFIG at a throwaway file before you run anything:

export KUBECONFIG="$(mktemp -d)/config"

KUBECONFIG can also list several files separated by colons, and kubectl merges them. You can use the --kubeconfig flag to point a single command at one file instead. Both are described on the kubeconfig page linked above. Close the terminal (or unset KUBECONFIG) when you are done and your real config is untouched.

2. Create two contexts with kubectl config set-context

A context refers to a cluster and a user, so I first defined both, then created dev and prod contexts that share them and differ only in namespace. Then I switched to dev with use-context.

kubectl version --client
kubectl config set-cluster demo --server=https://example.invalid
kubectl config set-credentials demo-user
kubectl config set-context dev --cluster=demo --user=demo-user --namespace=dev
kubectl config set-context prod --cluster=demo --user=demo-user --namespace=prod
kubectl config use-context dev
kubectl config get-contexts

Client Version: v1.35.0
Kustomize Version: v5.7.1
Cluster "demo" set.
User "demo-user" set.
Context "dev" created.
Context "prod" created.
Switched to context "dev".
CURRENT   NAME   CLUSTER   AUTHINFO    NAMESPACE
*         dev    demo      demo-user   dev
          prod   demo      demo-user   prod

The * in the CURRENT column marks the context kubectl will use. Note the two “created” messages: set-context reports “created” for a new name.

3. Change the namespace of a context (set-context —current —namespace)

To change the default namespace for a named context, run set-context again with just the field you want to change. Because supplied fields are merged, the cluster and user stay as they were.

kubectl config set-context dev --namespace=team-a
kubectl config get-contexts
kubectl config current-context

Context "dev" modified.
CURRENT   NAME   CLUSTER   AUTHINFO    NAMESPACE
*         dev    demo      demo-user   team-a
          prod   demo      demo-user   prod
dev

When you want to change the namespace of whatever context is active, you do not need to know its name. Add --current, then read the value back with --minify, which limits the output to the current context:

kubectl config set-context --current --namespace=team-b
kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}{"\n"}'

Context "dev" modified.
team-b

This is the usual answer to “kubectl set namespace for context”: there is no separate command, it is set-context with --namespace.

4. Use a context for one command without switching

The --context flag runs a single command against another context and leaves current-context alone. Here I asked for the prod context while dev stayed selected:

kubectl --context=prod config view --minify -o jsonpath='{.contexts[0].name}{" "}{.contexts[0].context.namespace}{"\n"}'
kubectl config current-context
kubectl config get-contexts

prod prod
dev
CURRENT   NAME   CLUSTER   AUTHINFO    NAMESPACE
*         dev    demo      demo-user   team-b
          prod   demo      demo-user   prod

The first line shows kubectl resolved the prod context and its namespace. Afterwards, current-context is still dev. This is the safest way to touch another cluster, because nothing lingers after the command finishes.

5. What happens with a typo, and how to remove a namespace default

Switching to a context that does not exist fails and leaves the current context unchanged. I added echo "exit=$?" to show the exit code:

kubectl config use-context missing; echo "exit=$?"
kubectl config current-context

error: no context exists with the name: "missing"
exit=1
dev

To remove a namespace default from a context, unset the property. Without a namespace, kubectl falls back to default.

kubectl config unset contexts.dev.namespace
kubectl config view --minify

Property "contexts.dev.namespace" unset.
apiVersion: v1
clusters:
- cluster:
    server: https://example.invalid
  name: demo
contexts:
- context:
    cluster: demo
    user: demo-user
  name: dev
current-context: dev
kind: Config
users:
- name: demo-user
  user: {}

The dev context entry now has only cluster and user, with no namespace line.

Safety habits for real clusters

• Check before destructive commands. Run kubectl config current-context before delete, apply or drain. It is one short command and it prints one word.
• Prefer explicit --context in scripts. A script that relies on whatever was selected last will eventually run against the wrong place. kubectl --context=NAME ... makes the target part of the command.
• Name contexts clearly. Names like prod-eu-admin and staging-readonly beat cluster1 when you are tired.
• Show the context in your shell prompt. Many people add the current context and namespace to their prompt so the answer is always visible. Choose any approach you trust.
• Keep a namespace default per context so you do not forget -n and land in default.

If you want to understand what the cluster side looks like, see Kubernetes control plane components and cluster setup. The official multi-cluster configuration walkthrough is also worth reading.

Troubleshooting

”error: current-context is not set”

kubectl prints error: current-context is not set when the kubeconfig has no current-context, often because it is new or empty. Run kubectl config get-contexts to see what exists, then kubectl config use-context NAME.

I changed a context but requests still go elsewhere

Check what overrides it:

• A --context, --namespace or --kubeconfig flag in the command, or in a shell alias or wrapper.
• A KUBECONFIG variable pointing at a different file, or listing several files that are merged. See the kubeconfig page for precedence rules.
• Editing a different context than the active one. set-context NAME does not switch to NAME.

kubectl config view --minify shows what kubectl resolved for the current context.

The context exists but the API call fails

A valid context only means the local entry is well formed. Connectivity (server address, network, VPN) and authentication (credentials, expiry) are separate problems. In my lab, https://example.invalid is deliberately unreachable, so any real API call would fail by design.

FAQ

What is the difference between kubectl set-context and use-context?

set-context creates or edits a context entry. use-context selects which context is current. Creating a context does not select it.

How do I change the default namespace?

Run kubectl config set-context --current --namespace=NS for the active context, or kubectl config set-context NAME --namespace=NS for a named one.

How do I list contexts?

Run kubectl config get-contexts. The * in the CURRENT column marks the active one.

How do I delete a context?

Use kubectl config delete-context NAME. I did not run it in this lab, so I have no output to show for it.

Does set-context create a cluster or user?

No. It only references a cluster and user by name. Define those with kubectl config set-cluster and kubectl config set-credentials, as in step 2.

How do I see the current namespace?

Run kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}{"\n"}'. An empty line means no namespace is set, so kubectl uses default.