kubeconfig

How to manage multiple kubeconfigs and switch context

If you run clusters for many clients, you end up with multiple kubeconfigs: one per cloud, per client or per environment. kubectl merges those files and switches context without copying anything by hand. These are the commands, and how Kubepier organizes the same clusters by client.

1. List the contexts in your kubeconfig

Each context ties a cluster to a user and, optionally, to a namespace. The asterisk marks the current one:

kubectl config get-contexts
kubectl config current-context

2. Switch context with kubectl config use-context

use-context changes the current context for every command after it. For a single command, without changing the current one, use --context:

kubectl config use-context <context>
kubectl config set-context --current --namespace=<namespace>

# Only for this command:
kubectl get pods --context <context> -n <namespace>

3. KUBECONFIG with several files

The KUBECONFIG variable takes a list of files, separated by colons on Linux and macOS and by semicolons on Windows. kubectl reads them all as if they were one, and get-contexts lists the contexts from all of them.

If the same context, cluster or user name shows up in two files, the one from the first file in the list wins. That is why each context deserves a unique name.

# Linux and macOS (bash/zsh)
export KUBECONFIG=~/.kube/config:~/.kube/client-a.yaml:~/.kube/client-b.yaml

# Windows (PowerShell)
$env:KUBECONFIG = "$HOME\.kube\config;$HOME\.kube\client-a.yaml"

4. Merge the kubeconfigs into one file

To keep a single file, build the merged version with --flatten, which also embeds certificates that lived in separate files. Write it to a new file, back up the original and only then swap them:

cp ~/.kube/config ~/.kube/config.bak
KUBECONFIG=~/.kube/config:~/.kube/client-a.yaml kubectl config view --flatten > /tmp/kubeconfig-merged
mv /tmp/kubeconfig-merged ~/.kube/config
chmod 600 ~/.kube/config

Do not redirect the output straight into ~/.kube/config: the shell empties the file before kubectl reads it.

Context names that help

Put the client and the environment in the context name: client-a-prd, client-a-stg. You know where you are before running a command.
kubectl config rename-context <old> <new> renames it without touching the cluster or the user.
On AKS, az aks get-credentials --context <name> writes the context with the name you pick; on EKS, aws eks update-kubeconfig --alias <name>.
kubectl config delete-context <name> deletes only the context. The cluster and the user stay in the file until you delete them with delete-cluster and delete-user.
kubectx and kubens switch context and namespace with less typing.

Care with multiple kubeconfigs

A kubeconfig carries a token or a certificate: keep the file readable only by your user (chmod 600) and do not send it over chat.
Before a command that changes something, check the current context. The wrong context is the most common way to change another client’s cluster.
Contexts with an exec plugin (kubelogin, aws, gke-gcloud-auth-plugin) depend on the binary on your machine; the file alone is not enough on another machine.

How Kubepier organizes clusters by client

In Kubepier, every cluster belongs to a client, with a name, a color and a keyword. A cluster whose name contains the keyword joins the client on its own, and you can fix the assignment in the cluster’s details drawer.

On desktop, clusters come from your machine’s kubeconfig (~/.kube/config), including contexts with exec plugins; other files and folders are added under Preferences › Kubernetes, in Kubeconfig Syncs, as in Freelens. The catalog groups them all by owning client, and you set up clients under Preferences › TR Clients.

On the web, you paste the kubeconfig under Clusters › Paste kubeconfig: each context in the file becomes a cluster, and the client comes from the keyword or from the client you pick for the import. Contexts the web does not accept (exec plugin, credentials in a local file) show up with the reason; the others in the same file are imported. AKS and EKS can also come in through the cloud account, with no kubeconfig.

Start for free