Introduction

kubectl can use more than one kubeconfig file at the same time, so you usually do not need to hand-edit YAML to combine cluster access. The normal pattern is to point KUBECONFIG at both files, inspect the merged view, and only then write the flattened result back if you want a single persistent config.

What a kubeconfig Actually Stores

A kubeconfig is a collection of named entries. The main sections are:

• clusters
• users, or authentication entries
• contexts, which pair a cluster with a user and optional namespace

When kubectl reads multiple kubeconfig files, it merges those named objects into one effective configuration in memory. That means merging is mostly about names and references, not just about concatenating YAML documents.

The Standard Merge Workflow

On macOS and Linux, list both files in KUBECONFIG separated by ::

export KUBECONFIG="$HOME/.kube/config:/path/to/other-config.yaml"

On Windows, the separator is ; instead.

Once the variable is set, ask kubectl to show the merged result:

kubectl config view --merge --flatten

--merge tells kubectl to combine the file list. --flatten resolves references and inlines data so the output is self-contained, which is useful if you want to save the result as one file.

Writing the Merged Result Back Safely

If you want the final merged config to become your new default ~/.kube/config, make a backup first:

1cp "$HOME/.kube/config" "$HOME/.kube/config.backup"
2
3KUBECONFIG="$HOME/.kube/config:/path/to/other-config.yaml" \
4  kubectl config view --merge --flatten > "$HOME/.kube/config.merged"
5
6mv "$HOME/.kube/config.merged" "$HOME/.kube/config"

That workflow is safer than redirecting straight into the original file because it leaves you with a known-good backup if the new file is invalid or incomplete.

Verify Before Replacing Anything

It is better to validate the merged configuration before you overwrite the default file. Start by listing contexts:

KUBECONFIG="$HOME/.kube/config:/path/to/other-config.yaml" \
  kubectl config get-contexts

Then inspect the effective YAML if needed:

KUBECONFIG="$HOME/.kube/config:/path/to/other-config.yaml" \
  kubectl config view --merge --flatten

This lets you confirm that:

• the new cluster appears at all
• credentials still point to the expected user entry
• the context names are not colliding with existing names

Name Collisions Are the Real Danger

Merging kubeconfigs is easy when names are unique. Problems appear when both files contain the same cluster name, user name, or context name for different targets. In that case, one entry can override the other, and the merged result can look valid while pointing to the wrong system.

If a context name is too generic, rename it before or after the merge:

kubectl config rename-context old-name prod-eu-cluster

Clear naming makes merged configs much safer, especially if you use several production and staging clusters.

You Do Not Always Need a Permanent Merge

A common misunderstanding is that a merge must end with rewriting ~/.kube/config. That is optional. Sometimes it is cleaner to keep the external file separate and only combine it at runtime:

KUBECONFIG="$HOME/.kube/config:/path/to/temp-cluster.yaml" \
  kubectl get namespaces

That approach is useful when:

• the second config is temporary
• you are debugging or testing
• you do not want to pollute the main config with short-lived access

In other words, the in-memory merge is often enough.

Why Manual YAML Editing Is Usually Worse

Hand-editing two kubeconfig files into one file works in principle, but it creates unnecessary risks:

• duplicate names
• broken indentation
• lost certificate data
• mismatched context references

kubectl config view --merge --flatten uses the tool that already understands kubeconfig structure. That is usually safer than manual copy-and-paste editing.

Common Pitfalls

• Overwriting ~/.kube/config with the new file instead of actually merging it deletes your existing contexts.
• Forgetting that KUBECONFIG uses : on Unix-like systems and ; on Windows leads to confusing missing-context behavior.
• Ignoring name collisions can make a familiar context suddenly point to the wrong cluster.
• Writing the merged result back without taking a backup first makes recovery harder.
• Assuming a permanent rewrite is required when a temporary KUBECONFIG merge would do the job.

Summary

• 'kubectl can merge multiple kubeconfig files through KUBECONFIG.'
• Use kubectl config view --merge --flatten to produce a combined self-contained result.
• Back up your current ~/.kube/config before replacing it.
• Verify contexts and watch for cluster, user, and context name collisions.
• In many cases, keeping the files separate and using a runtime merge is cleaner than rewriting the default config.