Configuring kubectl Context in Linux: A Complete Guide

Introduction / Why This Is Needed

When working with Kubernetes, especially in production environments or when managing multiple clusters (dev, staging, prod), you constantly need to switch between them. kubectl context is the mechanism that stores the "cluster + user + namespace" combination and allows instant switching between different environments with a single command.

After completing this guide, you will be able to:

• View all available contexts.
• Create and configure new contexts.
• Quickly switch between clusters.
• Manage default namespaces for each context.

Prerequisites / Preparation

Before you begin, ensure:

1. kubectl is installed and functional (version 1.20 or higher).
2. You already have access to at least one Kubernetes cluster (i.e., there is at least one working context in ~/.kube/config).
3. You possess the necessary permissions to access the clusters (usually via a kubeconfig file or aws eks, etc.).
4. You are working in a Linux environment (Ubuntu, CentOS, Fedora, etc.) with a bash-compatible shell.

Step-by-Step Instructions

Step 1: Check Your Current Configuration

First, find out what already exists in your configuration.

# Show all contexts from the current kubeconfig
kubectl config get-contexts

The output will resemble a table:

CURRENT   NAME                      CLUSTER                   AUTHINFO                  NAMESPACE
*         my-prod-cluster           prod-cluster.example.com  prod-user                 default
          my-dev-cluster            dev-cluster.example.com   dev-user                  staging

An asterisk (*) in the CURRENT column indicates the currently active context.

It's also useful to view the full configuration file:

kubectl config view

This YAML-formatted output will show all clusters, users (credentials), and contexts.

Step 2: Create a New Context

Assume you already have:

• A cluster named staging-cluster (already added to the config).
• A user (auth info) named admin-staging (already added).

Now create a context staging-admin that will use the monitoring namespace by default:

kubectl config set-context staging-admin \
  --cluster=staging-cluster \
  --user=admin-staging \
  --namespace=monitoring

What this command does:

• set-context — the create/update context operation.
• staging-admin — the name of the new context.
• --cluster, --user — reference existing entries in kubeconfig.
• --namespace — sets the default namespace for this context (optional parameter).

💡 Tip: If you want the context to have no default namespace, simply omit the --namespace flag. Then default will be used.

Step 3: Switch to the New Context

Now make the newly created context active:

kubectl config use-context staging-admin

After this, all subsequent kubectl commands (e.g., kubectl get pods) will execute against the staging-cluster with the admin-staging user and in the monitoring namespace.

Step 4: Verify the Result

1. Ensure the context has changed:

kubectl config current-context

The output should be: staging-admin

2. Make a test API request to the cluster:

kubectl get nodes

If you see a list of nodes from your staging-cluster — the context is working correctly.

3. Check that the default namespace is set:

kubectl get pods

The command will show pods only from the monitoring namespace (if any exist there).

Step 5: (Optional) Delete an Unneeded Context

If a context is no longer needed, remove it from the configuration:

kubectl config delete-context staging-admin

⚠️ Important: This command deletes only the context entry, but does not delete the cluster (clusters.staging-cluster) and user (users.admin-staging) records themselves from the kubeconfig file. They will remain and can be used in other contexts.

Verification

Success criteria:

1. kubectl config current-context returns the name of your new context.
2. kubectl get ... commands interact with the correct cluster.
3. (If a namespace is set) kubectl get pods shows resources only in the specified namespace.
4. The ~/.kube/config file contains a new contexts: section with your parameters.

Troubleshooting

Error: error: no context exists with name ...

Cause: A context with that name was not found in the configuration. Solution: Check the name using kubectl config get-contexts and use the exact spelling.

Error: Unable to connect to the server: dial tcp ...: i/o timeout

Cause: The context points to an incorrect cluster or the cluster is unreachable. Solution: Verify that --cluster specifies the correct cluster name from kubectl config get-clusters. Ensure you have network access to the cluster's API server.

Error: You must be logged in to the server (Unauthorized)

Cause: The context uses a user (auth info) that lacks permissions or has missing/invalid credentials. Solution: Check that the user (--user) exists in the config and that correct tokens/certificates are set for it. You may need to update your kubeconfig using aws eks update-kubeconfig or a similar tool.

Context switched, but commands still target the old cluster

Cause: The command explicitly uses the --context flag or the KUBECONTEXT environment variable. Solution: Ensure you are not overriding the context in the command itself or in aliases/scripts.

Default namespace is not applied

Cause: The context was created without the --namespace flag, or the command explicitly specifies --namespace. Solution: Recreate the context with the desired namespace or explicitly specify the namespace in each command: kubectl get pods -n monitoring.

Additional Capabilities

Using Multiple kubeconfig Files

You can merge configurations from different files:

export KUBECONFIG=~/.kube/config:~/.kube/eks-config
kubectl config view --flatten > merged-config

This is convenient if you have separate configs for EKS, GKE, and on-premise clusters.

Setting a Namespace for a Specific Command Without Creating a New Context

If you need to execute a command in a different namespace just once, without switching contexts, use:

kubectl get pods -n <namespace>

However, for frequent switching between different projects within the same cluster, it is still more convenient to create separate contexts with different --namespace values.