How to Merge Kubeconfig Files - Simplified

Introduction

Managing multiple Kubernetes clusters means dealing with multiple kubeconfig files. Each cluster generates its own configuration file containing authentication details, server endpoints, and context information. As your infrastructure grows, manually switching between different kubeconfig files becomes tedious and error-prone.

Merging kubeconfig files into a single configuration allows you to switch between clusters using kubectl config use-context or kubectx commands instead of managing separate files. This approach simplifies cluster management, reduces configuration overhead, and minimizes the risk of applying changes to the wrong cluster.

Step-by-Step Implementation

Understanding Kubeconfig Structure

Before merging files, understand the kubeconfig structure. Each configuration contains three main sections:

Method 1: Using kubectl config Commands

The kubectl config command provides built-in functionality to merge configurations:

# View current config
kubectl config view

# Merge multiple kubeconfig files
export KUBECONFIG=~/.kube/config:~/.kube/cluster2-config:~/.kube/cluster3-config

# Make the merge permanent
kubectl config view --flatten > ~/.kube/merged-config

# Set the merged config as default
cp ~/.kube/merged-config ~/.kube/config

Method 2: Manual File Merging

For more control over the merge process:

# Backup existing config
cp ~/.kube/config ~/.kube/config.backup

# Create a temporary merged config
kubectl config view --flatten --kubeconfig=~/.kube/config > /tmp/merged-config
kubectl config view --flatten --kubeconfig=~/.kube/cluster2-config >> /tmp/merged-config

# Apply the merged configuration
cp /tmp/merged-config ~/.kube/config

Method 3: Using kubecfg Tool

Install and use the kubecfg tool for advanced merging:

# Install kubecfg
curl -L https://github.com/kubecfg/kubecfg/releases/latest/download/kubecfg-linux-amd64 -o kubecfg
chmod +x kubecfg
sudo mv kubecfg /usr/local/bin/

# Merge configurations
kubecfg merge ~/.kube/config ~/.kube/cluster2-config > ~/.kube/merged-config

Handling Naming Conflicts

When merging files with duplicate cluster or context names, rename them before merging:

# Rename context in source file
kubectl config rename-context old-context-name new-context-name --kubeconfig=~/.kube/cluster2-config

# Rename cluster
kubectl config set clusters.new-cluster-name clusters.old-cluster-name --kubeconfig=~/.kube/cluster2-config
kubectl config unset clusters.old-cluster-name --kubeconfig=~/.kube/cluster2-config

Verifying the Merge

After merging, verify all contexts are available:

# List all available contexts
kubectl config get-contexts

# Test switching between contexts
kubectl config use-context cluster1-context
kubectl get nodes

kubectl config use-context cluster2-context  
kubectl get nodes

Setting Default Namespace per Context

Configure default namespaces for each context to avoid confusion:

# Set default namespace for specific context
kubectl config set-context cluster1-context --namespace=production
kubectl config set-context cluster2-context --namespace=development

Automation Script

Create a script to automate the merging process:

#!/bin/bash
# merge-kubeconfigs.sh

BACKUP_DIR="$HOME/.kube/backups"
MERGED_CONFIG="$HOME/.kube/config"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Backup current config
cp "$MERGED_CONFIG" "$BACKUP_DIR/config-$(date +%Y%m%d-%H%M%S)"

# Collect all kubeconfig files
KUBECONFIG_FILES=""
for config in "$HOME"/.kube/cluster-*.config; do
    if [ -f "$config" ]; then
        KUBECONFIG_FILES="$KUBECONFIG_FILES:$config"
    fi
done

# Merge configurations
export KUBECONFIG="$MERGED_CONFIG$KUBECONFIG_FILES"
kubectl config view --flatten > "$HOME/.kube/merged-temp"

# Replace current config
mv "$HOME/.kube/merged-temp" "$MERGED_CONFIG"

echo "Kubeconfig files merged successfully"
kubectl config get-contexts

Conclusion

Merging kubeconfig files eliminates the complexity of managing multiple configuration files in multi-cluster environments. The kubectl config commands provide the most straightforward approach, while manual methods offer greater control over the merge process.

Always backup your existing configurations before merging, and verify connectivity to all clusters after the merge. Setting appropriate default namespaces for each context prevents accidental deployments to wrong environments.

This unified approach to cluster management reduces operational overhead and minimizes configuration errors in complex Kubernetes environments.

KubeNine specializes in Kubernetes architecture and enterprise implementation. Visit kubenine.com for expert guidance on Kubernetes infrastructure design and optimization.