Kubectl contexts allow you to work easily with multiple Kubernetes clusters using one kubectl installation. Once you've set up some contexts, you can switch between them to change the cluster that your Kubectl operations target.

You'll often need to check which context is selected and list the alternatives available in your kubeconfig file. This guide provides a cheat sheet for the kubectl config commands you can use.

What is a kubectl context?

A kubectl context is a named collection of settings that sets up a connection to a Kubernetes cluster. Using contexts makes it much more convenient to manage workflows involving multiple clusters. For example, you could have a production context that connects to your live Kubernetes cluster and a separate staging context that lets you target your QA environment.

Each Kubernetes context contains the following properties:

• The cluster's URL and certificate authority (CA) file
• The user credentials to connect with
• The default namespace to apply to Kubectl commands

The contexts you create are stored within your kubeconfig file. After you've set up a context, it will remain available each time you use Kubectl, so you don't have to manually select cluster URLs, certificates, and users whenever you change clusters.

What is the get context kubectl command?

The kubectl config get-contexts is a command that lists all the contexts defined in the Kubernetes configuration file and provides an overview of cluster configurations with user access settings. It's a handy way to see and manage the different environments and configurations you're working with, ensuring you can easily switch between them as needed.

This kubectl command uses the following syntax:

kubectl config get-contexts

This will output a table with information about each context, including the current context, which is marked with an asterisk (*).

Here's a quick summary of commands used to interact with the Kubernetes contexts.

• Get the current context: kubectl config current-context

• Get all available contexts: kubectl config get-contexts

• Set a specific context: kubectl config use-context <context-name>

• Add a new context with a specific cluster, user, and namespace: kubectl config set-context <context-name> --cluster=<cluster-name> --user=<user-name> --namespace=<namespace>

• Delete contexts: kubectl config delete-context <context-name>

• Display the contents of the kubeconfig file: kubectl config view

Always ensure that you replace placeholders (like <context-name>, <cluster-name>, <user-name>, and <namespace>) with actual values relevant to your Kubernetes setup.

How to get the current context in Kubernetes?

You can view the name of your currently active context using the kubectl config current-context command:

$ kubectl config current-context

minikube

In this case, you can see the context is called minikube.

If no context is selected, you'll receive an error message:

$ kubectl config current-context

error: current-context is not set

This normally occurs when your Kubeconfig file is empty because you haven't configured any clusters yet  You will also see this message if you manually clear the current-context key within your Kubeconfig file.

How to list all Kubectl contexts?

You can retrieve a list of all the contexts available in your Kubeconfig file by running kubectl config get-contexts:

$ kubectl config get-contexts

CURRENT   NAME               CLUSTER            AUTHINFO                 NAMESPACE
          do-lon1-heronweb   do-lon1-heronweb   do-lon1-heronweb-admin   default
*          minikube           minikube           minikube                 default

This displays a helpful table that contains the details of each context, including the name of the cluster it targets and the authentication details it connects with. A * in the first column highlights the currently selected context --- this is the one that appears in the current-context command's output.

💡 You might also like:

• K3s vs K8s: Differences, Use Cases & Alternatives
• Kubectl Describe Command – Pods, Deployments & More
• Kubernetes HPA Horizontal Pod Autoscaler Guide

How to switch between Kubectl contexts?

To switch between contexts, you need to run kubectl config use-context and pass the name of the context you want to activate:

$ kubectl config use-context do-lon1-heronweb

Switched to context "do-lon1-heronweb".

Your Kubectl commands will now be directed to the cluster targeted by your newly selected context. The selection will persist until you repeat the kubectl config use-context command to move to a different context instead.

Overriding context settings

Selecting a context doesn't prevent you from overriding its settings. You can still use regular Kubectl flags such as --cluster, --user, and --namespace to make changes as you run your commands. For example, the following command will list the Pods in the example namespace of the cluster defined by your active context while connecting as the demo user from your kubeconfig file:

$ kubectl get pods --user demo --namespace example

No resources found in example namespace.

This does not modify the context; if you next run the same command without the --user flag, the user specified in your context's configuration will be selected.

Kubectl contexts and multiple kubeconfig files

Kubectl context data is always saved in your active kubeconfig file. This can be changed by setting the --kubeconfig flag or KUBECONFIG environment variable to specify a different path:

$ export KUBECONFIG=~/custom-kubeconfig

Your  context choices will now be the ones defined within the file you've selected:

$ kubectl config get-contexts

CURRENT   NAME   CLUSTER   AUTHINFO   NAMESPACE

In this example, the referenced kubeconfig file is empty, so no contexts are available.

Managing kubectl contexts

Kubectl contexts are managed using the kubectl config set-context command. It allows you to save cluster, user, and namespace combinations to new or existing contexts. The basic usage is as follows:

$ kubectl config set-context my-context\
    --cluster demo\
    --user spacelift\
    --namespace sample-app

This creates or updates the context called my-context. The context will target the demo cluster as the spacelift user, with the default namespace set to sample-app.

The cluster and user you reference must already exist in your kubeconfig file. You can define them using the kubectl config set-cluster and kubectl config set-credentials commands, respectively.

The options passed to set-context can each be specified individually if you're updating an existing context --- there's no need to repeat unchanged values. In addition, if you're modifying your currently active context, you can pass the --current flag instead of identifying the context by its name.

Managing Kubernetes with Spacelift

If you need assistance managing your Kubernetes projects, look at Spacelift. It brings with it a GitOps flow, so your Kubernetes Deployments are synced with your Kubernetes Stacks, and pull requests show you a preview of what they're planning to change. 

To take this one step further, you could add custom policies to reinforce the security and reliability of your configurations and deployments. Spacelift provides different types of policies and workflows that are easily customizable to fit every use case. For instance, you could add plan policies to restrict or warn about security or compliance violations or approval policies to add an approval step during deployments. 

You can try Spacelift for free by creating a trial account or booking a demo with one of our engineers.

Key points

We've looked at how you can check your current Kubectl context, list the contexts available in your kubeconfig file, and switch to a different context. These basic operations are easy to learn, but they have a big impact on the ease with which you can administer your Kubernetes environments.

Correctly utilizing contexts allows you to switch efficiently between clusters and swap sets of user credentials, all while using a single kubeconfig file. Use the kubectl config get-contexts command to list all the available contexts, including the current context. You can keep adding new contexts to your configuration and use the kubectl config use-context command to enable them. This is easier and less error-prone than maintaining multiple Kubeconfig files, where you must remember to correctly set the --kubeconfig flag or KUBECONFIG environment variable with each command.

Written by James Walker