Skip to main content

Migration Procedures Reference

This document provides detailed procedures for migrating between different KubeZero configurations and versions.

Pre-Migration Checklist​

Before starting any migration, ensure you have:

  1. Complete backup of your current cluster
  2. Migration plan with rollback procedures
  3. Maintenance window scheduled
  4. Access credentials verified
  5. Monitoring in place to track migration progress

Version Migration​

Minor Version Updates​

For minor version updates (e.g., 1.2.0 to 1.2.1):

# Update the KubeZero stack version
kubectl patch stack my-stack --type='merge' -p='{"spec":{"version":"1.2.1"}}'

# Monitor the rollout
kubectl get pods -n kubezero-system -w

Major Version Updates​

For major version updates (e.g., 1.x to 2.x):

# Create backup before migration
kubectl apply -f backup-job.yaml

# Update stack configuration
kubectl apply -f new-stack-config.yaml

# Monitor migration progress
kubectl describe stack my-stack

Stack Migration​

Migrating Between Stack Types​

From EKS to GKE​

  1. Prepare new GKE cluster:
# Deploy base GKE stack
kubectl apply -f gke-stack.yaml
  1. Migrate workloads:
# Export workloads from EKS
kubectl get all --all-namespaces -o yaml > workloads-backup.yaml

# Apply to GKE cluster
kubectl apply -f workloads-backup.yaml
  1. Update DNS and load balancers:
# Update external DNS records
kubectl patch service ingress-nginx-controller -p '{"spec":{"loadBalancerIP":"NEW_IP"}}'

Module Migration​

Adding New Modules​

# Add new module to existing stack
spec:
  modules:
    - name: monitoring
      version: "1.0.0"
      enabled: true
      config:
        prometheus:
          retention: "30d"
        grafana:
          adminPassword: "secretPassword"

Removing Modules​

# Disable module before removal
spec:
  modules:
    - name: old-module
      enabled: false

Wait for resources to be cleaned up, then remove from configuration.

Data Migration​

Persistent Volume Migration​

Cloud Provider Migration​

For migrating persistent volumes between cloud providers:

# Create volume snapshots
kubectl apply -f volume-snapshot.yaml

# Restore in new cluster
kubectl apply -f volume-restore.yaml

Storage Class Migration​

# Update storage class for volumes
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  annotations:
    volume.beta.kubernetes.io/storage-class: "new-storage-class"

Database Migration​

PostgreSQL Migration​

# Create database dump
kubectl exec postgres-pod -- pg_dump mydb > backup.sql

# Restore in new cluster
kubectl exec new-postgres-pod -- psql mydb < backup.sql

Configuration Migration​

GitOps Repository Migration​

  1. Create new repository structure:
# Clone existing repo
git clone https://github.com/old-org/kubezero-config.git

# Update repository structure
mv kubezero-config kubezero-config-new
cd kubezero-config-new
  1. Update ArgoCD configuration:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kubezero-app
spec:
  source:
    repoURL: https://github.com/new-org/kubezero-config.git
    path: stacks/production

Secret Migration​

External Secrets Migration​

# Update secret store references
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://new-vault.example.com"
      path: "secret"

Post-Migration Validation​

Health Checks​

# Verify all pods are running
kubectl get pods --all-namespaces

# Check service endpoints
kubectl get endpoints

# Validate ingress connectivity
curl -I https://myapp.example.com

Performance Testing​

# Run load tests
kubectl apply -f load-test-job.yaml

# Monitor resource usage
kubectl top nodes
kubectl top pods

Rollback Procedures​

Emergency Rollback​

If migration fails, execute immediate rollback:

# Restore from backup
kubectl apply -f cluster-restore.yaml

# Revert DNS changes
# Update load balancer targets
# Notify stakeholders

Gradual Rollback​

For non-critical issues:

# Scale down new deployment
kubectl scale deployment new-app --replicas=0

# Scale up old deployment
kubectl scale deployment old-app --replicas=3

# Monitor traffic shift

Troubleshooting​

Common Issues​

  1. Resource conflicts: Check for overlapping resource names
  2. Network policies: Verify connectivity between migrated components
  3. Storage permissions: Ensure proper PVC access rights
  4. Service accounts: Update RBAC permissions as needed

Diagnostic Commands​

# Check events for errors
kubectl get events --sort-by='.lastTimestamp'

# Examine pod logs
kubectl logs -f deployment/my-app

# Describe problematic resources
kubectl describe pod failing-pod