Background

As someone who juggles multiple Kubernetes clusters daily, both local and remote, I’ve often found managing the ~/.kube/config file to be a mess.

When you work with multiple clusters, it’s common to copy individual kubeconfig files, merge them manually into your local ~/.kube/config, and clean them up when no longer needed. Add the occasional overwrite mishaps, and you’ll quickly want a better way to manage multiple kubeconfig files.

Sure, tools like kubectx and kubens help with Kubernetes context and namespace switching. You can find more about these great tools on their GitHub repo. But they assume you’ve already handled the messy kubeconfig merging part.

That’s why I built a lightweight Bash script and called it kubeconfig-manager.sh, which I alias as kcfg. This little tool keeps my kubeconfig life sane.

What the Script Does

The kcfg script makes working with multiple Kubernetes clusters a breeze. With a few simple commands, I can:

  • Copy a remote kubeconfig via SCP, fix the 127.0.0.1 issue, rename the context, and merge it automatically.
  • Add an existing kubeconfig file into my main ~/.kube/config.
  • Remove a context (cluster, user, and context) from ~/.kube/config.
  • Export a specific context from the merged kubeconfig to a separate file.
  • List all current contexts.
  • Automatically keep only the last 5 kubeconfig backups to avoid clutter.

The script outputs are clean, colorized, and informative — just the way I like them.

Prerequisites

In addition to having kubectl installed, make sure you have the following tools:

1
2

sudo snap install yq
sudo apt install fzf

You’ll also want to install kubectx and kubens. Check the GitHub link above for platform-specific instructions. SSH access to your remote clusters is required as well.

Setup Instructions

  1. Create the kube directory
1

mkdir -p ~/.kube
  1. Save the script

Save the script as ~/.kube/kubeconfig-manager.sh and make it executable. You can grab the latest version of the script from my repo.

1
2

nano ~/.kube/kubeconfig-manager.sh
chmod +x ~/.kube/kubeconfig-manager.sh
  1. Add alias

Add the following line to your ~/.bash_aliases:

1

alias kcfg="$HOME/.kube/kubeconfig-manager.sh"

Make sure your ~/.bashrc sources it:

1
2
3

if [ -f ~/.bash_aliases ]; then
  . ~/.bash_aliases
fi

Then reload your shell:

1

source ~/.bashrc
  1. Optional: My Handy Aliases
1
2
3
4
5

alias ll="ls -la"
alias k="kubectl"
alias kctx="kubectx"
alias kns="kubens"
alias kctxns="kubectx $(kubectl config view --minify -o jsonpath="{..namespace}")"

How to Use kcfg

Here are common usage scenarios for kcfg. You can always run the command without parameters to see all supported options:

1

kcfg

And you’ll get this output:

1
2
3
4
5
6

Usage:
  kcfg add <name>
  kcfg scp <user@host:/path/to/kubeconfig> <name>
  kcfg remove <name>
  kcfg list
  kcfg export <name>

Copy kubeconfig from a remote server

I run this command when I have a new cluster that I need to add to my local ~/.kube/config file.

1

kcfg scp admin@server01:/etc/rancher/k3s/k3s.yaml k3s-test

This:

  • Copies the config from server01
  • Backs up the current config
  • Replaces 127.0.0.1 with server01
  • Renames the cluster/context to k3s-test
    • Merges it into ~/.kube/config

This is the sample output in the terminal:

1
2
3
4
5

📥 Copying from admin@server01:/etc/rancher/k3s/k3s.yaml to /home/admin/.kube/kubeconfig-k3s-test.yaml
🔧 Patching 127.0.0.1 to server01 in /home/admin/.kube/kubeconfig-k3s-test.yaml
🔧 Renaming cluster, context, and current-context to k3s-test
🛟 Backing up current config to /home/admin/.kube/config.backup.20250326111635
✅ Merging /home/admin/.kube/kubeconfig-k3s-test.yaml into /home/admin/.kube/config

Add a local kubeconfig file

This is the scenario when I already have individual config yaml file and just need to add the context to the local ~/.kube/config file.

1

kcfg add k3s-test

With the sample terminal output like this:

1
2

🛟 Backing up current config to /home/admin/.kube/config.backup.20250326114837
✅ Merging /home/admin/.kube/kubeconfig-k3s-test.yaml into /home/admin/.kube/config

Remove a context

This deletes the context, user, and cluster from my main local ~/.kube/config file.

1

kcfg remove k3s-home

And the sample terminal output:

1
2
3

🧹 Removing context, cluster, and user: k3s-home
deleted context k3s-home from /home/admin/.kube/config
deleted cluster k3s-home from /home/admin/.kube/config

List all contexts

This command lists all the context from my local ~/.kube/config file.

1

kcfg list

With sample terminal output:

1
2
3

📋 Available contexts:
k3s-home
k3s-test

Export a single context

Sometimes I need to export specific cluster context as an individual config file.

1

kcfg export k3s-home

This creates a new file:

1

📤 Exporting context k3s-home to /home/admin/.kube/kubeconfig-k3s-home.yaml

Backup Cleanup

After multiple imports, my ~/.kube folder looks like this:

1
2
3
4
5
6
7
8
9

-rw-rw-r--  config
-rw-rw-r--  config.backup.20250326114112
-rw-rw-r--  config.backup.20250326114539
-rw-rw-r--  config.backup.20250326114837
-rw-rw-r--  config.backup.20250326115328
-rw-rw-r--  config.backup.20250326115835
-rw-------  kubeconfig-k3s-home.yaml
-rw-------  kubeconfig-k3s-test.yaml
-rwxrwxr-x  kubeconfig-manager.sh

The script automatically keeps only the last 5 backups to keep the folder clean.

Final Thoughts

This script isn’t a replacement for kubectl, kubectx, or kubeadm, but it bridges the gap in kubeconfig management when dealing with multiple Kubernetes clusters. It’s helped me streamline my local environment, avoid mistakes, and work faster.

You can grab the latest version of the script at my GitHub repo.