Kubernetes Contexts: Complete Guide for Developers

When interacting with a SQL database such as Postgres or MySQL, developers will need the so-called Connection String. The connection string contains all the information required to connect to a database, which includes a hostname (or IP), port, username and password. All this information is often stored in a single string, which is then used by the application to connect to the database.

In Kubernetes world, the equivalent of the connection string is a Context. The context contains all the information required to connect to a Kubernetes cluster, such as the cluster hostname, port, authentication method, and so on. However, unlike the connection string, the context is not a string, but a YAML object stored in a file known as Kubeconfig.

Multiple contexts can be stored in a single Kubeconfig file, and each context can be used to connect to a different cluster. Alternatively, a kubeconfig file can be split into multiple files, each containing a one or more contexts. This is what I would recommend doing if you have many clusters, as it'll keep things more organized and easier to manage.

The default location of where the Kubeconfig is stored is ~/.kube/config. This location is used by pretty much all Kubernetes tools, such as kubectl and Aptakube, however custom locations are also supported.

If you've used kubectl before, you probably have a Kubeconfig in your machine. Curious to see what's in it? If you're on macOS or Linux, you can use the following command:

cat ~/.kube/config

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.

I highly recommend it if you're new to Kubernetes!

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, as previously mentioned, I'd recommend using separate files for each cluster, or at least group some clusters together based on whatever they have in common.

• Cluster: this object defines where the cluster's API Server is located (host:port) 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.

• User: this 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. Other authentication methods include token, username/password, and exec. We'll cover these in more detail in the next section.

• 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. This means you can have multiple contexts pointing to the same cluster, but with different users, which is useful when you have different roles in the same cluster.

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 constantly interact with multiple kubeconfig files.

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.

Most Kubernetes tools make use of Kubeconfig files, which makes it very easy to adopt and try new apps without having to install or configure anything extra. Here's an example of how Aptakube uses contexts.

You can connect to multiple clusters at the same time, which is something not possible with kubectl.

We can't talk about Kubeconfig without mentioning the security aspect of it. These files may contain sensitive information such as tokens and private keys, so it's important to keep it safe.

The best option to protect your cluster is to not store any sensitive information in your Kubeconfig file. Authentication is where things can get complicated. There are many ways to authenticate to a Kubernetes cluster, and some of them are more secure than others. These are the most popular ones:

• 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 like a VPN/Proxy, anyone can use the token to access your cluster. Avoid using tokens for any important cluster. It's generally OK to use on local clusters though.
• Client Certificate: This is somewhat similar to a token, however it can slightly safer as the content of the certificate is usually stored in a separate file. So even if the Kubeconfig content gets leaked, the attacker might not have access to the certificates. The Kubeconfig example we showed earlier uses client certificates.
• Exec Plugins (Recommended): 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, az or gcloud CLI) to perform the authentication using a cloud-based IAM mechanism. This is the most secure authentication method because it doesn't include any sensitive information in the Kubeconfig file. However, it's also more complex to setup as it requires additional knowledge of each cloud provider and how to use their CLI tools.

When working with multiple Kubernetes clusters, it's often useful being able to connect to more multiple clusters so you can see the status of your application in one view. This is especially useful when you're running an application across different regions or even multi-cloud. There are few different ways to achieve that and we've documented a few on our How to list resources such as pods from multiple clusters blog post. Go check it out!

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 😊

That's all folks! 🎉

I'd like to encourage you to see what's in your Kubeconfig file, you'd be surprised how much you can learn from simply looking at it. Most Kubernetes users don't even know there's an API server URL in there!

• Official documentation for Kubernetes Context
• Complete Spec for Kubeconfig