How to Merge Multiple Kubeconfig Files in Kubernetes

Since kubectl needs a kubeconfig to authenticate and connect to a cluster, it’s often easier to merge them into a single kubeconfig file for convenience.

In this guide, you’ll learn how to merge multiple kubeconfig files into one file, step-by-step, so you can seamlessly manage multiple clusters from one configuration. Ideally, kubernetes has this feature out of the box. If you supply e.g. export KUBECONFIG="${KUBECONFIG}:config-file-1:config-file-2 it will merge those three files. But it can be cumbersome so we will learn how to combine them into a single file.

What is a Kubeconfig File?

A kubeconfig file is where Kubernetes stores:

Cluster connection details
Authentication credentials
Namespaces
User contexts

By default, Kubernetes looks for the kubeconfig file at:

1
$HOME/.kube/config

You can have multiple clusters defined inside one kubeconfig, or use separate files and point kubectl to them using:

The KUBECONFIG environment variable
The --kubeconfig flag

Why Merge Kubeconfig Files?

You might need to merge kubeconfigs when:

You’ve just created or imported a new cluster and want it accessible alongside existing clusters.
You want to avoid remembering which kubeconfig file to use for each cluster.
You want a single file to back up or share.

Prerequisites

kubectl installed
At least two kubeconfig files (e.g., ~/.kube/config and ~/.kube/new.yml)
Access to the clusters defined in them

Step-by-Step: Merging Kubeconfig Files

Backup Your Existing Kubeconfig

Always create a backup before making changes:

1
cp ~/.kube/config ~/.kube/config.bk

This temporarily merges them in-memory, so kubectl can see both.

Export the KUBECONFIG Environment Variable

Tell kubectl to load both kubeconfig files:

1
export KUBECONFIG=~/.kube/config:~/.kube/new.yml

This temporarily merges them in-memory, so kubectl can see both.

Verify the Current Configuration

Check what kubectl sees right now:

1
kubectl config view

You should see clusters from both files.

Flatten the Configuration into One File

Combine them into a single, permanent file:

1
kubectl config view --flatten > /tmp/all-in-one-kubeconfig.yml

The --flatten flag removes duplicate and relative path references, producing a clean standalone file.

Replace the Old Kubeconfig

Move the merged file into place:

1
mv /tmp/all-in-one-kubeconfig.yml ~/.kube/config

Fix Permissions

Ensure your kubeconfig file is readable only by you:

1
chmod 600 ~/.kube/config

Remove the Backup (Optional)

If everything works fine:

1
rm ~/.kube/config.bk

Set the Active Context

Switch to your new cluster context:

1
kubectl config use-context $(kubectl config get-contexts --output=name | tail -n1)

Or manually select one:

1
kubectl config use-context <context-name>

Verify Your Clusters

List all clusters in the merged config:

1
kubectl config get-clusters

You should now see all clusters from both original files.

Quick Reference Commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Backup existing config
cp ~/.kube/config ~/.kube/config.bk

# Merge and flatten
export KUBECONFIG=~/.kube/config:~/.kube/new.yml
kubectl config view --flatten > /tmp/all-in-one-kubeconfig.yml

# Replace old config
mv /tmp/all-in-one-kubeconfig.yml ~/.kube/config
chmod 600 ~/.kube/config

# Verify
kubectl config get-clusters

Final Thoughts

Kubernetes makes it easy to merge kubeconfig files using the KUBECONFIG variable and kubectl config view –flatten. By keeping all your clusters in one file, you can save time, reduce mistakes, and simplify management.

If you frequently work with multiple clusters, consider using tools like kubectx and kubens to switch between contexts and namespaces quickly.