Kubectl config set-context tutorial

The first time you configure kubectl, you need to place kubeconfig in the correct location before you’re able to issue commands to your Kubernetes cluster. There are three ways to do this.

One option is to place the kubeconfig file in $HOME/.kube/config, which is the default path kubectl looks for.

Another option is to use the flag --kubeconfig. If your kubeconfig is located somewhere other than the default path, you can specify it with this flag and issue commands:

The final option is to use the KUBECONFIG environment variable. This environment variable allows you to specify multiple kubeconfig files by setting the value to the paths of the files, delimited by colons:

If you are working with multiple Kubernetes clusters, it can quickly become cumbersome to manage configuration files like this as you are switching from one cluster to the other.

If your clusters have multiple namespaces, another pain point appears: the need to specify --namespace or -n every time you use kubectl. Combined with multiple clusters, every kubectl command is going to look something like kubectl --namespace <NAMESPACE_NAME> --kubeconfig <PATH_TO_KUBECONFIG> …, which is both time consuming and an easy place for errors to slip in.

This is where Kubernetes contexts come into the picture. You can think of Kubernetes contexts as a kind of shortcut that allows you to access cluster, user, and namespace parameters conveniently.

This allows you to define multiple contexts in your configuration file, which you can then use to target multiple Kubernetes clusters, or the same cluster with a different set of users or namespaces. You can quickly switch between clusters by using the kubectl config use-context command. To use that command, though, you need to configure contexts in your kubeconfig. This can be done with the kubectl config set-context command. In this article, you’ll take a closer look at how kubeconfig is structured, how to define contexts in kubeconfig, and how to effectively use set-context to manipulate different contexts.

What is Kubernetes context?

In Kubernetes, a context is an entity defined inside kubeconfig to alias cluster parameters with a human-readable name. It’s important to understand that a Kubernetes context only applies to the client side. The Kubernetes API server itself doesn’t recognize context the way it does other objects such as pods, deployments, or namespaces.

Let’s take a look at a cross section of a typical kubeconfig structure to see how cluster, user, and context tie up together.

Typically there are three parts to a kubeconfig:

• Clusters: This section lists all the clusters that you have access to. Each cluster contains details about the URL for the Kubernetes API server (where the cluster accepts commands from kubectl), certificate authority, and a name to identify the cluster.
• Contexts: This is the most relevant section to this tutorial, since it lists the available contexts. Each context consists of the cluster name, user, and namespace that you can access when you invoke it. Note that in the example, the namespace information is omitted because it’s using the default namespace.
• Users: The users section identifies each user by a unique name and includes the relevant authentication information, which could be client certificates (as is the case here), bearer tokens, or an authenticating proxy.

In this example, the kubeconfig contains only one cluster, user, and context. Interestingly, it also contains current-context which means all of the kubectl commands are going to run in that context unless that is changed.

Which brings us to kubectl set-context, which is used to set a context entry in kubeconfig.

Using kubectl config set-context

To follow this tutorial, you need to have access from your local machine to a Kubernetes deployment via the kubectl command-line tool.

• For instructions on how to install kubectl on your workstation, you can read official documentation.
• The easiest way to install Kubernetes is using minikube, Rancher Desktop, Docker Desktop, or a similar tool. All of these tools install Kubernetes locally and preconfigure kubectl to give you access to the deployment.

After setting up Kubernetes and kubectl, you can look at the set-context help using the following command:

You’ll get the following output:

What this says is that you can create or modify contexts in your kubeconfig file with the command kubectl config set-context. This command also accepts the name of the context to be changed (or --current if you want to change the current context), as well as --user, --cluster, and --namespace options. If the specified context already exists in the kubeconfig, this command is going to modify that entry with the parameters that are passed.

Basic usage of kubectl config set-context

Before you start modifying your kubeconfig, it’s helpful to know how to display its content. To do this, you can to use the following command:

The result will vary depending on the tool you use, since each tool names the users and clusters differently, but basically maintains the structure discussed earlier.

Say you want to create a new context for development called “dev-context”, which points to the namespace “dev-namespace”, and the user “dev-user”. For simplicity, let’s also assume that you’re using the same cluster you’re currently in.

The command to add a new context with the data described above is as follows:

If you run the kubectl config view command again, you’ll notice that the new context has been added:

You’ll also notice that the user was only added to the context section, which you’ll look at in more detail shortly. Now that you’ve learned how to add contexts to your kubeconfig, it’s time to learn how to modify an existing context.

Suppose you want to change the dev-namespace name to “development”. To do this, you can use the following command:

This will return the message “Context “dev-context” modified”, indicating that the change was successful.

The template to create or modify a context is as follows:

Since the point of creating contexts is to be able to switch to any of them as needed, you’ll want to familiarize yourself with the following commands:

Advanced usage of kubectl config set-context

In this section, you’ll look at how to configure access to other clusters in a more complex situation. There are scenarios where you can leverage the kubectl config set-context command to simplify your workflow.

As you may have already noticed, kubectl config set-context is only one of many commands that help you work with the kubeconfig file. Specifically, kubectl config set-context only modifies the section of kubeconfig corresponding to the context.

The following commands are the commands that allow you to add or modify cluster access and user credentials in your kubeconfig. You might notice some similarity to kubectl config set-context in its structure.

To add or modify a cluster, you can use the following template:

Similarly, you can use the following template to add or modify the user’s credentials:

Please note that for the purposes of this tutorial, client certificates are used to authenticate the user, and a certificate authority (CA) is used to authenticate to Kubernetes. For more information about other authentication methods, you can read the Kubernetes authentication overview.

Using the commands described above, you can now add a new cluster, a new context, and a new user to the kubeconfig.

Suppose you want to access a new cluster called “prod” with a specific IP address and credentials. To add it to kubeconfig, you can use a command like this:

To add a new context called “prod”, with a namespace called “production” and a user called “admin”, you can use the following command:

To complete this exercise, add the imaginary credentials for the user “admin”:

To review the changes, use the kubectl config view command. The output should be similar to the following:

Now, whenever you want to access the prod cluster in the production namespace as the user admin, all you have to do is use the command:

The use case shown is just an example of what you can achieve using the kubectl config set- commands. You can create any conceivable combination of contexts with different users, namespaces, and clusters.

Best practices when using kubectl config set-context

A common challenge IT departments face is agreeing on an appropriate naming convention. When you use the kubectl config set- context command, you’re actually creating an alias, a kind of shortcut that allows you to avoid the need to enter multiple flags on the command line. While this can speed up your workflow, it could become a problem if your team doesn’t follow a naming guideline.

Consider the example from the previous section. If you only work with a single cluster, the name “production” may be appropriate. But what if you need access to dozens of Kubernetes deployments? What if each of those clusters has several namespaces (production, testing, stage), and multiple users with different access permissions?

If your organization isn’t careful, each developer may end up using different names to refer to the same object, cluster, or namespace. In fact, even if you work alone, you can forget how to access a given cluster if you use a different naming convention every time.

To avoid situations like the one described above, the best practice is to plan a naming strategy for your organization in advance.

It’s also important to remember that your kubeconfig file is a kind of private key. Anyone who has access to this file will be able to authenticate to your Kubernetes deployment. It’s crucial that you take every precaution to keep your kubeconfig secure and private.

Final thoughts

In this article, you’ve learned what Kubernetes config contexts are, how they’re used, and how you can manipulate contexts in your kubeconfig file by using set-context to make your life easier when using kubectl commands.

If you’re using a complex Kubernetes deployment for your internal tooling and want a more maintenance-free solution, you should use Airplane. With Airplane, you can take your existing scripts built in bash, Python, Javascript, and more and turn them into secure, internally-sharable tools to empower your whole team.

Sign up for a free Airplane account or book a demo and get started building internal tools within minutes.