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.
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:
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.
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.
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.
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
--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.
~/.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 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 leaked, the attacker might not have gotten 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'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 😊