• Nathan

Kubernetes - Using kubectl with kubeconfig files

Updated: Mar 20

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 will list one or more user accounts that you would like to use to connect to your Kubernetes clusters. You will give each User a specific name, and then you will specify the credentials to use for that account, whether that's a username/password combo, certificates, or tokens.

2 - Clusters

In this section you will list one or more kubernetes clusters that you would like to connect to. You will give each Cluster a specific name, and then specify the address to connect to and the SSL settings to use for each Cluster.

3 - Contexts

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

So, for example, Context A would map User A to Cluster A, 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 also 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 of the kubectl tool.

  • 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 a 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 of this variable 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:

  • $HOME/.kube/config

  • Windows:

  • %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 pick it up and use it.


Some useful kubectl commands

# show everything (all lines) from your kubeconfig file:
  kubectl config view

# show the current-context value from your kubeconfig file:
  kubectl config current-context

# show all the Contexts defined in your kubeconfig file:
  kubectl config get-contexts

# change contexts:
  kubectl config use-context contextName

# show all the Users defined in your kubeconfig file:
  kubectl config get-users

# show all the Clusters defined in your kubeconfig file:
  kubectl config get-clusters


How to create kubeconfig files?

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