Complete Guide to Kubeconfig and Kubernetes Contexts

What the heck is Kubeconfig anyway?

When interacting with a SQL database such as Postgres, for example, developers often need the so called Connection String, which is a string that contains all the information needed to connect to the database. This includes the database host, port, username, password, and so on. All this information is often stored in a single string, which is then used by the application to connect to the database.

Kubeconfig is sort of a connection string, but for Kubernetes clusters. It contains all the information needed to connect to a Kubernetes cluster, including the cluster host, port, authentication method, and so on.

However, unlike the connection string, Kubeconfig is a file. It's often stored in the ~/.kube/config file and it's used by pretty much all Kubernetes tools, such as kubectl and Aptakube.

Let's take a look at a Kubeconfig file

apiVersion: v1
kind: Config
current-context: minikube
clusters:
  - cluster:
      certificate-authority: /Users/goenning/.minikube/ca.crt
      server: https://127.0.0.1:51171
    name: minikube-local
contexts:
  - context:
      cluster: minikube-local
      namespace: default
      user: admin
    name: minikube
users:
  - name: admin
    user:
      client-certificate: /Users/goenning/.minikube/profiles/minikube/client.crt
      client-key: /Users/goenning/.minikube/profiles/minikube/client.key

This is a Kubeconfig file generated by Minikube, which is a tool that creates a single-node Kubernetes cluster on your local machine. It's a great tool for learning Kubernetes and for developing applications locally.

Each kubeconfig file contains three main sections: clusters, contexts, and users. These sections are defined as an array of objects because you can have multiple clusters, contexts, and users in a single kubeconfig file. However, when working with multiple clusters it's often recommended to keep a separate kubeconfig file for each cluster, or at least group some clusters together in a single kubeconfig file based on whatever they have in common.

The context is what links the cluster and the user together. Every operation you perform in Kubernetes is done in a context, which is why kubectl has a --context parameter for you to specific which cluster you want to interact with.

The cluster object defines where the cluster is located (server) and what client certificate (certificate-authority) to use during the SSL handshake. This section may also contain other settings such as proxy-url in cases where the cluster can only be accessed through a proxy.

The user object defines the authentication method to be used when connecting to the cluster. In this case, the user is using a client certificate, which is a common authentication method for local clusters.

Using the Kubeconfig file with kubectl

When using kubectl (or any other Kubernetes tool), by default it will look for the kubeconfig file in the ~/.kube/config path. However, you can specify a different path using the --kubeconfig parameter or the KUBECONFIG environment variable. Here are some examples:

kubectl get pods # uses ~/.kube/config
kubectl get pods --kubeconfig /path/to/kubeconfig # uses config from /path/to/kubeconfig
KUBECONFIG=/path/to/kubeconfig kubectl get pods # same as above

In case you have multiple clusters in your kubeconfig file, you can use the --context parameter to specify which cluster you want to interact with:

kubectl get pods --context prod-europe # uses the prod-europe context from the ~/.kube/config
kubectl get pods --context prod-europe --kubeconfig /path/to/kubeconfig # uses the prod-europe context from /path/to/kubeconfig

Setting the --kubeconfig parameter on every command is tedious, so you can also set the KUBECONFIG environment variable to point to the kubeconfig file you want to use. This is especially useful when you have multiple kubeconfig files that you interact with constantly.

If you're on macOS or Linux, you can set the KUBECONFIG on your shell profile (e.g. ~/.bash_profile or ~/.zshrc) so that it's always available on future shell session and you don't have to set it manually every time.

Here's a cheat sheet with some useful context related commands:

kubectl config get-contexts             # display list of contexts
kubectl config current-context          # display the current-context
kubectl config use-context prod-europe  # set the default context to my-cluster-name

kubectl config use-context basically modifies your Kubeconfig file and sets the current-context to the one you specified. This is useful when you want to switch between contexts without having to specify the --context parameter every time.

Authentication and Security

Last topic we'd like to cover is related to how to keep your Kubeconfig file secure. The Kubeconfig file may contain sensitive information such as tokens and private keys, so it's important to keep it safe. However, the the best option to protect your cluster is by not having any sensitive information in your Kubeconfig file.

Authentication is where things can get tricky. There are many ways to authenticate to a Kubernetes cluster, and some of them are more secure than others. Some popular ones are:

• Token: This is by far the worst authentication method in terms of security. If you Kubeconfig gets leaked, unless you've got some other network protection, anyone can use the token to access your cluster. Avoid using this for any important cluster, but it's generally OK to use on local clusters for testing/development purposes.
• Client Certificate: This is somewhat similar to a token, however it can slightly safer if the content of the certificate is usually stored in a separate file. So even if the Kubeconfig gets leaker, the attacked might not have got access to the certificates.
• Exec Plugins: This is what most cloud providers and managed Kubernetes services would recommend you to use. It's essentially an extension of Kubeconfig to use external CLI tools (such as the aws CLI, az CLI or gcloud CLI) to perform the authentication using a cloud-based IAM mechanism. This is the most secure authentication method because it doesn't require any sensitive information to be stored in the Kubeconfig file. However, it's also the most complex one to setup as it requires additional knowledge of each cloud provider and how to use their CLI tools.

Connecting to multiple clusters simultaneously

When working with multiple Kubernetes clusters, it might be useful to connect to more than one cluster at the same time so you can see the status of your application across multiple clusters in one view. This is especially useful when you're running an application across different regions or even multi-cloud.

Aptakube is GUI application for Kubernetes that uses the same Kubeconfig files we mentioned above and can connect to multiple clusters at the same time. It essentially presents all your Kubernetes resources as if it was a single clusters. We invite you to try it out free today 😊