Organize Kubernetes Cluster Access with Kubeconfig Files

Kubeconfig files configure Kubectl, the default Kubernetes client tool. These essential files define the cluster Kubectl commands will target and the user credentials they’ll authenticate with.

Kubectl automatically loads the Kubeconfig file stored at ~/.kube/config. You can access multiple clusters with one Kubectl installation by specifying a different file, either by setting the KUBECONFIG environment variable or using Kubectl’s --kubeconfig flag:

This approach is inconvenient when you have several different clusters, however. You need to remember the path to each Kubeconfig file and must specify it each time you run Kubectl.

A better alternative is to merge your files into one, then use Kubectl’s built-in config management features to switch between clusters seamlessly. Let’s see how.

Switching to a single Kubeconfig file lets you more efficiently organize your Kubernetes cluster access.

Here are some of the benefits you’ll gain:

• One file can contain all your clusters and users. No more duplication of Kubeconfig files each time you need to connect as a new user account, or register an additional cluster.
• You can quickly switch between configs by running Kubectl commands. Kubectl natively supports multiple config contexts within a single Kubeconfig file. The CLI includes commands for inspecting your active context and switching to another – we’ll see these below.
• You don’t have to remember to set KUBECONFIG or –kubeconfig every time you use Kubectl. Kubeconfig contexts you select within Kubectl are automatically persisted until you make another change. You don’t have to repeat the –kubeconfig flag with every command, or restore the value of KUBECONFIG after you reopen your terminal window.
• You can easily inspect the file to view the complete list of clusters you’ve used. Ever forgotten which clusters you have access to, or misplaced an important Kubeconfig file? This is a common problem for admins working with multiple clusters, where Kubeconfigs can become scattered across your storage drives. When you use a single file, you can view all your clusters in one location.

These advantages mean a single Kubeconfig file is often the most effective option for Kubernetes developers and administrators. This doesn’t mean they’re always the best approach, though – in some situations, it can make sense to split up connections, such as when different files require unique security characteristics or are intended for specific situations.

Let’s get started adding some cluster connections to Kubeconfig. Use the config set-cluster command to register a new cluster. You must supply a name for the cluster, its API server URL, and the path to its TLS certificate authority file:

To add another cluster, simply repeat the command with different arguments:

If you’re running a local cluster without TLS, you can disable TLS verification instead of supplying certificate authority data:

View all the clusters present in your active Kubeconfig file with the config get-clusters command:

Next you need to add user credentials for each of your clusters. The config set-credentials command registers credentials in several different formats.

Specify the name of your new credentials entry as the command’s first argument. This name will be used to refer to the credentials when you link them to your cluster in the next step. 

Flags must also be set to supply the user’s authentication data. This example creates a user entry called production-admin that authenticates with a token:

Token-based auth is the correct method when your user is a service account created within Kubernetes. Use --username and --password instead if you’re using HTTP Basic Auth, or set --client-certificate and --client-key for certificate-based authentication.

Repeat the command to add another user for your staging cluster:

After you’ve added your credentials, you can view them with the config get-credentials command:

Now you’re ready to link your clusters and credentials together as functioning configuration contexts. A context is a combination of cluster and credentials; Kubectl connects to the cluster specified by your selected context, using its configured credentials.

Contexts are created by the config set-context command. Specify the name of your new context as the command’s argument, then set the --cluster and --user flags to reference the respective entries in your Kubeconfig file:

You can view the contexts within your Kubeconfig file by running config get-contexts:

Once you’ve created your contexts, you can switch between them by running the config use-context command. Kubectl will mark the specified context as the current one. The cluster and user it specifies will be targeted by all subsequent commands, until you switch away to a different context.

The currently selected context is indicated by an asterisk in the get-contexts command’s output:

You can override the current context for a specific command with Kubectl’s --context flag:

This avoids having to switch context twice when you need to quickly run one command against a particular cluster, then revert to the previous one.

Contexts can also specify a default namespace. Kubectl commands will target the namespace set in the context, unless you override it with the --namespace or -n flag.

To assign a namespace to a context, run config set-context and include the --namespace flag:

Kubectl merges your new config values with the context’s existing ones when you run set-context. You only need to supply new values for the fields you want to update.

Switching between contexts with kubectl config use-context is simpler and less repetitive than juggling separate Kubeconfig files with KUBECONFIG or --kubeconfig. You can make it even easier by installing two Kubectl plugins: kubectx and kubens. These let you rapidly switch between contexts and namespaces using quick shortcuts.

It’s easiest to install the tools using Krew, Kubectl’s plugin manager. Run the script on the Krew website to download it if you need to.

Afterwards, run the following commands to install the plugins:

With the plugins installed, you can view the contexts available in your Kubeconfig file by running kubectl ctx:

The active context will be highlighted. Switch to a different context by supplying its name as an argument to the ctx command:

Similarly, kubectl ns lists and navigates between namespaces in your active cluster:

These time-saving aliases for kubectl config commands help you efficiently work across clusters and environments.

Kubeconfig lets you edit your config files at any time. Change the properties of clusters, contexts, and users by repeating the set-cluster, set-context, and set-user commands with appropriate flags to apply the change you need:

You can always check which context you’ve selected by running config current-context:

Clusters, contexts, and users can be deleted with their respective delete- commands.

There’s no confirmation prompt, so check you’ve typed the correct name before pressing enter!

To view the contents of your current Kubeconfig file, run kubectl config view:

It displays the same content as if you’d accessed the file directly, including the clusters, users, and contexts you’ve registered.

Got lots of existing Kubeconfig files for different clusters? You can merge them into a single file, then set up contexts to access your environments.

First, set the KUBECONFIG environment variable to reference all your files. Separate each file’s path with a colon (:) character:

Next use Kubectl’s config view command with the --flatten flag to export a new combined Kubeconfig file:

The resulting Kubeconfig will be the product of merging all the individual files together. You can now use the clusters and users in the merged file to set up your contexts.

Kubeconfig files are sensitive assets that should be treated with caution. Whether you merge your files or keep them separate, remember that anyone with access to them can connect to your cluster.

Avoid sharing Kubeconfigs and ensure they don’t get accidentally committed to code repositories. If you know or suspect that a file has been leaked, you should immediately take action to invalidate the credentials it contained. Replace the secrets for service accounts and revoke any user tokens that may have been exposed from your identity provider.

You should also be wary of using Kubeconfig files you don’t trust. It’s possible to create malicious Kubeconfig files that execute arbitrary code on your host. Kubeconfigs you receive are best treated similarly to shell scripts. Don’t use them without inspecting their content, even if the source seems to be genuine.

Kubeconfig files work with more than just Kubectl. Other Kubernetes ecosystem tools such as Helm and graphical clients like Lens also support the clusters, users, and contexts you create. Opening Lens after following the steps in this tutorial will automatically show your cluster connections, for example:

Multi-cluster Kubernetes access doesn’t have to mean multiple Kubeconfigs, cumbersome environment variables, and confusion over which file is correct for each situation. Merging your Kubeconfigs into one file lets you use Kubectl’s built-in commands for quickly switching between clusters, users, and contexts.

While this simplifies ease-of-use, it still requires you to share sensitive cluster credentials and certificates before users can connect. Use a centralized infrastructure automation platform like Spacelift to avoid this risky practice. Spacelift provides precise guardrails that let your developers ship straight to Kubernetes clusters without breaking security and compliance requirements.

Want to learn more about Kubernetes and Kubectl? Try our beginners tutorial, or check out the advanced topics on the Spacelift blog.