top of page
  • Writer's pictureNathan

Kubernetes - Using kubectl with kubeconfig files

Updated: Aug 27, 2022

kubectl is the command-line tool that is used to interact with Kubernetes clusters. But, how does kubectl know which clusters to connect to and how to authenticate to them? That's where kubeconfig files come in.


kubeconfig files are nothing more than YAML files that specify the following 3 items:

1 - Users

In this section you list one or more user accounts that will be used to connect to your Kubernetes clusters. Each User gets a specific name as well as a set of credentials, which could be a username/password combo, certificates, or tokens.

2 - Clusters

In this section you list one or more Kubernetes clusters that you will connect to. Each Cluster gets a specific name as well as details on how to connect to the cluster, such as the address to connect to and the SSL settings to use.

3 - Contexts

In this section you list one or more Contexts, which are nothing more than a specific combination of a User and a Cluster.

So, for example, Context-A would map User-A to Cluster-A, then Context-B would map User-B to Cluster-B, and so on. Each Context gets its own specific name that you can reference it by.

Contexts can optionally be scoped to a specific Kubernetes Namespace, if you wish. For example, Context-A could map User-A to Cluster-A, and also limit them to only Namespace-A.


So, what does kubectl do with this file? To over-simplify things, kubectl connects to one of the Contexts inside the file. The default Context that is used by kubectl is specified by the line current-context in the kubeconfig file.

If you have multiple Contexts defined, then how do you switch between them?

  • You can switch Contexts on a per-command basis by using the --context flag on your kubectl commands.

  • You can switch Contexts permanently by using the kubectl config use-context command. This will actually change and update the current-context line in your kubeconfig file to the Context that you specify.

Example kubeconfig file:


Using kubeconfig files

There are three main ways to point kubectl at your kubeconfig files:

1 - The --kubeconfig flag

You can pass this flag on every kubectl command that you run. This flag will force kubectl to read from the kubeconfig file that you specify. You can only use one kubeconfig file this way. Also, you can only specify one instance of this flag on the command-line. This way is a little cumbersome as you have to type this for every kubectl command.

2 - The KUBECONFIG environment variable

You can also set a special environment variable named KUBECONFIG. The value points at the kubeconfig file that you would like to use. This variable can be pointed at multiple kubeconfig files, if you wish. Just make sure to separate the files with colons (on Linux & Mac) or semi-colons (on Windows). If you specify multiple kubeconfigs this way, then kubectl will merge them all into one config and use that merged version.

3 - The default config file

By default, the kubectl command-line tool will look for a kubeconfig file simply named config (no file extension) in the .kube directory of the user's profile:

  • Linux default kubeconfig file:

    • $HOME/.kube/config

  • Windows default kubeconfig file:

    • %USERPROFILE%\.kube\config

This is the easiest method to use, in my opinion. Simply place a file in the correct directory, and kubectl will automatically read it and use it.


Some useful kubectl commands


How to create kubeconfig files?

I'm going to save this and use it as the subject of another article. Stay tuned.


Extra Credit

Check out the 3rd party tool call kubectx. This tool saves you a lot of typing when dealing with multiple kubectl contexts.

You could also install fzf which gives you an interactive menu when you run kubectx, so just type kubectx and then pick your selected Context from the menu.



bottom of page