Kubernetes Multi-Cluster Management

Managing multiple Kubernetes clústers across different regions or environments requires centralized tools and workflows. Esta guía cubre kubeconfig management, context switching with kubectx, federation, Rancher for clúster orchestration, and Cluster API for declarative clúster management on your VPS and baremetal infrastructure.

Tabla de contenidos

• 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 clústers in different locations
• Load Distribution: Spread workloads across clústers
• Compliance: Data residency requirements
• Cost Optimization: Burst capacity in different regions

Arquitectura Patterns

Hub and Spoke: Central control plane with multiple workload clústers

Mesh: All clústers peer with each other

Federation: Kubernetes native multi-clúster support

Kubeconfig Management

Understanding kubeconfig

Kubeconfig files contain clúster 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 clúster 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 clúster:

# 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 espacio de nombres for context:

kubectl config set-context prod --namespace=production

Context Inspection

View full context details:

kubectl config view

View specific clúster info:

kubectl cluster-info

kubectx Tool

Instalaing 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 espacio de nombress quickly:

# List namespaces
kubens

# Switch namespace
kubens production
kubens monitoring

# Switch to previous namespace
kubens -

Rancher Multi-Cluster Management

Instalaing Rancher

Rancher provides centralized management of multiple Kubernetes clústers.

Instala on local clúster:

# 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 clústers 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 clúster

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 clústers

Multi-Tenancy: Create projects and enforce RBAC

Workload Deployment: Deploy apps across clústers

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 clúster management using CRDs.

Instalaing Cluster API

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

Verifica la instalación:

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

Creating Clusters Declaratively

Define clúster 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 clúster:

kubectl apply -f cluster.yaml

Monitor clúster creation:

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

Federation

Kubernetes Federation Overview

Federation (kubefed) enables cross-clúster resource management:

• FederatedDeployment: Deployment across clústers
• FederatedService: Service across clústers
• FederatedNamespace: Namespace across clústers

Instalaing 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 clústers 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 implementación:

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

Ejemplo: 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

Ejemplo: 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

Conclusión

Multi-clúster Kubernetes management requires careful planning and the right tools. Whether using simple kubeconfig management with kubectx for small implementacións, 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-clúster implementacións grow on your VPS and baremetal infrastructure.