Kubernetes Multi-Cluster Management

Managing multiple Kubernetes clusters across different regions or environments requires centralized tools and workflows. This guide covers kubeconfig management, context switching with kubectx, federation, Rancher for cluster orchestration, and Cluster API for declarative cluster management on your VPS and baremetal infrastructure.

Table of Contents

• Multi-Cluster Fundamentals
• Kubeconfig Management
• Context Switching
• kubectx Tool
• Rancher Multi-Cluster Management
• Cluster API
• Federation
• Practical Examples
• Conclusion

Multi-Cluster Fundamentals

Why Multi-Cluster?

• High Availability: Failover between regions
• Disaster Recovery: Backup clusters in different locations
• Load Distribution: Spread workloads across clusters
• Compliance: Data residency requirements
• Cost Optimization: Burst capacity in different regions

Architecture Patterns

Hub and Spoke: Central control plane with multiple workload clusters

Mesh: All clusters peer with each other

Federation: Kubernetes native multi-cluster support

Kubeconfig Management

Understanding kubeconfig

Kubeconfig files contain cluster definitions, users, and contexts.

Default location: ~/.kube/config

kubeconfig Structure

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1C...
    server: https://api.cluster1.example.com:6443
  name: cluster1-prod
- cluster:
    certificate-authority-data: LS0tLS1C...
    server: https://api.cluster2.example.com:6443
  name: cluster2-staging
contexts:
- context:
    cluster: cluster1-prod
    user: prod-admin
  name: prod
- context:
    cluster: cluster2-staging
    user: staging-admin
  name: staging
current-context: prod
kind: Config
preferences: {}
users:
- name: prod-admin
  user:
    client-certificate-data: LS0tLS1C...
    client-key-data: LS0tLS1C...
- name: staging-admin
  user:
    client-certificate-data: LS0tLS1C...
    client-key-data: LS0tLS1C...

Merging kubeconfig Files

Combine multiple kubeconfig files:

# Export current kubeconfig
export KUBECONFIG=~/.kube/config:~/.kube/cluster2:~/.kube/cluster3

# View merged contexts
kubectl config get-contexts

# Permanently merge files
KUBECONFIG=~/.kube/config:~/.kube/cluster2:~/.kube/cluster3 \
kubectl config view --flatten > ~/.kube/config.merged

mv ~/.kube/config.merged ~/.kube/config

Adding Clusters

Get kubeconfig from cluster and merge:

# Get kubeconfig from cluster2
scp admin@cluster2:~/.kube/config ~/.kube/cluster2

# Rename context to avoid conflicts
kubectl config rename-context kubernetes-admin@kubernetes cluster2-admin --kubeconfig ~/.kube/cluster2

# Merge
KUBECONFIG=~/.kube/config:~/.kube/cluster2 kubectl config view --flatten > ~/.kube/merged
mv ~/.kube/merged ~/.kube/config

Creating Service Accounts for External Access

Create external access to a cluster:

# Create service account
kubectl create serviceaccount external-admin -n kube-system
kubectl create clusterrolebinding external-admin --clusterrole=cluster-admin --serviceaccount=kube-system:external-admin

# Get token
TOKEN=$(kubectl get secret -n kube-system $(kubectl get secret -n kube-system | grep external-admin-token | awk '{print $1}') -o jsonpath='{.data.token}' | base64 -d)

# Get API server address
API_SERVER=$(kubectl cluster-info | grep 'Kubernetes master' | awk '/https/ {print $NF}' | sed 's/\x1b\[[0-9;]*m//g')

# Get CA certificate
CA_CERT=$(kubectl get secret -n kube-system $(kubectl get secret -n kube-system | grep external-admin-token | awk '{print $1}') -o jsonpath='{.data.ca\.crt}')

# Create kubeconfig
kubectl config set-cluster cluster2 --server=$API_SERVER --certificate-authority-data=$CA_CERT
kubectl config set-credentials external-admin --token=$TOKEN
kubectl config set-context cluster2-admin --cluster=cluster2 --user=external-admin

Context Switching

Basic Context Commands

List contexts:

kubectl config get-contexts

Switch context:

kubectl config use-context prod

Get current context:

kubectl config current-context

Set default namespace for context:

kubectl config set-context prod --namespace=production

Context Inspection

View full context details:

kubectl config view

View specific cluster info:

kubectl cluster-info

kubectx Tool

Installing kubectx

kubectx makes context switching faster and easier.

# Using git
git clone https://github.com/ahmetb/kubectx /opt/kubectx
sudo ln -s /opt/kubectx/kubectx /usr/local/bin/kubectx
sudo ln -s /opt/kubectx/kubens /usr/local/bin/kubens

Using package manager:

# macOS
brew install kubectx

# Arch
yay -S kubectx

# Ubuntu/Debian (from source)
curl https://raw.githubusercontent.com/ahmetb/kubectx/master/kubectx | sudo tee /usr/local/bin/kubectx > /dev/null
sudo chmod +x /usr/local/bin/kubectx

Using kubectx

List contexts with abbreviations:

kubectx

Switch context:

kubectx prod
kubectx staging

Switch to previous context:

kubectx -

Display current context:

kubectx -c

Using kubens

Switch namespaces quickly:

# List namespaces
kubens

# Switch namespace
kubens production
kubens monitoring

# Switch to previous namespace
kubens -

Rancher Multi-Cluster Management

Installing Rancher

Rancher provides centralized management of multiple Kubernetes clusters.

Install on local cluster:

# Add Helm repository
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update

# Create namespace
kubectl create namespace cattle-system

# Install Rancher
helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.example.com \
  --set bootstrapPassword=InitialPassword123 \
  --set ingress.tls.source=rancher

Wait for installation:

kubectl wait --for=condition=ready pod -l app=rancher -n cattle-system --timeout=300s

Importing Clusters

Import existing clusters into Rancher:

1. Access Rancher UI: https://rancher.example.com
2. Clusters → Add Cluster → Import Existing
3. Copy provided kubectl command
4. Run on target cluster

Or via kubectl:

# Get import command from Rancher
# Then run on target cluster:
kubectl apply -f https://rancher.example.com/v3/import/xxxxx.yaml

Rancher Features

Cluster Management: Monitor, update, and manage clusters

Multi-Tenancy: Create projects and enforce RBAC

Workload Deployment: Deploy apps across clusters

Monitoring: Integrated with Prometheus

Logging: Centralized log aggregation

Example Rancher Catalog App

Deploy application from catalog:

# Via Rancher UI or
kubectl apply -f - <<EOF
apiVersion: management.cattle.io/v3
kind: GlobalRole
metadata:
  name: custom-app-deployer
rules:
- apiGroups: [""]
  resources: ["*"]
  verbs: ["*"]
EOF

Cluster API

Cluster API Overview

Cluster API provides declarative Kubernetes cluster management using CRDs.

Installing Cluster API

# Install required components
clusterctl init --infrastructure aws --bootstrap kubeadm --control-plane kubeadm

Verify installation:

kubectl get crds | grep cluster.x-k8s.io

Creating Clusters Declaratively

Define cluster with Cluster API:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: prod-cluster-1
  namespace: default
spec:
  clusterNetwork:
    services:
      cidrBlocks: ["10.96.0.0/12"]
    pods:
      cidrBlocks: ["10.244.0.0/16"]
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: prod-cluster-1-control-plane
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AWSCluster
    name: prod-cluster-1
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSCluster
metadata:
  name: prod-cluster-1
spec:
  region: us-east-1
  sshKeyName: my-key
  vpcCidr: "10.0.0.0/16"
---
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
metadata:
  name: prod-cluster-1-control-plane
spec:
  replicas: 3
  machineTemplate:
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: AWSMachineTemplate
      name: prod-cluster-1-control-plane
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSMachineTemplate
metadata:
  name: prod-cluster-1-control-plane
spec:
  template:
    spec:
      iamInstanceProfile: control-plane
      instanceType: t3.large
      sshUserName: ubuntu

Deploy cluster:

kubectl apply -f cluster.yaml

Monitor cluster creation:

clusterctl describe cluster prod-cluster-1
kubectl get cluster -w

Federation

Kubernetes Federation Overview

Federation (kubefed) enables cross-cluster resource management:

• FederatedDeployment: Deployment across clusters
• FederatedService: Service across clusters
• FederatedNamespace: Namespace across clusters

Installing Kubefed

# Add Helm repository
helm repo add kubefed-charts https://raw.githubusercontent.com/kubernetes-sigs/kubefed/master/charts

# Install kubefed
helm install kubefed kubefed-charts/kubefed \
  -n kube-federation-system \
  --create-namespace

Creating a Federation

Define clusters in federation:

apiVersion: core.kubefed.io/v1beta1
kind: KubeFedCluster
metadata:
  name: cluster-us-east
  namespace: kube-federation-system
spec:
  apiEndpoint: https://cluster1.example.com:6443
  caBundle: LS0tLS1CRUd...
  secretRef:
    name: cluster-us-east-secret
---
apiVersion: core.kubefed.io/v1beta1
kind: KubeFedCluster
metadata:
  name: cluster-us-west
  namespace: kube-federation-system
spec:
  apiEndpoint: https://cluster2.example.com:6443
  caBundle: LS0tLS1CRUd...
  secretRef:
    name: cluster-us-west-secret

Federated Workloads

Deploy federated deployment:

apiVersion: types.kubefed.io/v1beta1
kind: FederatedDeployment
metadata:
  name: multi-cluster-app
  namespace: production
spec:
  template:
    metadata:
      labels:
        app: multi-cluster-app
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: multi-cluster-app
      template:
        metadata:
          labels:
            app: multi-cluster-app
        spec:
          containers:
          - name: app
            image: my-app:1.0
  placement:
    clusters:
    - name: cluster-us-east
    - name: cluster-us-west
  overrides:
  - clusterName: cluster-us-east
    clusterOverrides:
    - path: /spec/replicas
      value: 2
  - clusterName: cluster-us-west
    clusterOverrides:
    - path: /spec/replicas
      value: 1

Practical Examples

Example: Multi-Cluster kubeconfig Setup

#!/bin/bash

# Setup kubeconfig with multiple clusters
export KUBECONFIG=$HOME/.kube/config

# Add production cluster
kubectl config set-cluster prod-cluster \
  --server=https://prod.example.com:6443 \
  --certificate-authority=/path/to/prod-ca.crt

kubectl config set-credentials prod-admin \
  --client-certificate=/path/to/prod-cert.crt \
  --client-key=/path/to/prod-key.key

kubectl config set-context prod \
  --cluster=prod-cluster \
  --user=prod-admin \
  --namespace=production

# Add staging cluster
kubectl config set-cluster staging-cluster \
  --server=https://staging.example.com:6443 \
  --certificate-authority=/path/to/staging-ca.crt

kubectl config set-credentials staging-admin \
  --client-certificate=/path/to/staging-cert.crt \
  --client-key=/path/to/staging-key.key

kubectl config set-context staging \
  --cluster=staging-cluster \
  --user=staging-admin \
  --namespace=staging

# View all contexts
kubectl config get-contexts

# Switch to prod
kubectl config use-context prod

Example: Rancher Multi-Cluster Deployment

# Via Helm deploy app to multiple Rancher clusters

helm repo add myapp https://charts.example.com
helm repo update

# Deploy to all clusters through Rancher
kubectl apply -f - <<EOF
apiVersion: batch.cattle.io/v1
kind: ClusterTask
metadata:
  name: deploy-app-clusters
spec:
  clusters:
  - name: prod-us-east
  - name: prod-us-west
  - name: staging
  template:
    spec:
      helm:
        repo: myapp
        chart: myapp
        version: 1.0.0
        values:
          environment: production
EOF

Conclusion

Multi-cluster Kubernetes management requires careful planning and the right tools. Whether using simple kubeconfig management with kubectx for small deployments, Rancher for centralized UI-based management, or Cluster API for declarative infrastructure-as-code approaches, choose the solution that matches your organizational needs and complexity. Start with basic kubeconfig management, add kubectx for convenience, then progress to Rancher or Cluster API as your multi-cluster deployments grow on your VPS and baremetal infrastructure.