Complete Guide to Kubeconfig and Kubernetes Contexts
Tags: kubernetes
Published: 2023-06-16 09:04:18

---
title: Complete Guide to Kubeconfig and Kubernetes Contexts
published: true
description: "A beginner-friendly exploration of Kubeconfig and contexts, empowering developers to navigate clusters with ease!"
tags: ["Kubernetes"]
cover_image: https://aptakube.com/_next/image?url=%2Fimages%2Fblogcover%2Fcomplete-guide-to-kubeconfig-kubernetes-contexts.png&w=1920&q=75
canonical_url: https://aptakube.com/blog/complete-guide-to-kubeconfig-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](https://kubernetes.io/docs/tasks/tools/) and [Aptakube](/).

# Let's take a look at a Kubeconfig file

```yaml
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](https://minikube.sigs.k8s.io/docs/), 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:

```bash
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:

```bash
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:

```bash
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](https://aptakube.com) 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 😊