Skip to main content
Version: v4.9 Stable

Upgrade a Multi-Region Platform Deployment

info
This feature is available from the Platform version v4.8.0

This runbook describes how to upgrade vCluster Platform across regions with minimal downtime. The process upgrades one region at a time while the other continues serving traffic through Route 53 failover.

Prerequisites​

  • Updated values files for each region (for example, platform-us-east-1-values.yaml and platform-eu-west-1-values.yaml)
  • kubectl contexts configured for both clusters
  • The target chart version available in the Helm repository

Configure your values​

The commands in this runbook reference your cluster context ARNs. Set them below once and all commands update automatically.

Expand to set page variables
Modify the following with your specific values to replace on the whole page and generate copyable commands:

Step 1 - Scale down the first region​

Pick the region to upgrade first and scale its platform deployment to zero. Scaling down before upgrading prevents leader election from switching between different platform versions during the upgrade, which could cause unexpected behavior. Route 53 routes all traffic to the other region while this one is offline.

Optionally, identify which region currently holds the leader lease so you can choose to upgrade the non-leader region first, minimizing leader re-elections:

for CTX in arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 arn:aws:eks:eu-west-1:123456789012:cluster/platform-multi-region-eu-west-1; do
echo "=== $CTX ==="
kubectl --context "$CTX" get lease -n vcluster-platform -o wide
echo
done
kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
scale deployment -n vcluster-platform loft --replicas=0

Wait for all pods to stop before proceeding.

kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
get pods -n vcluster-platform -l app=loft --watch

Step 2 - Upgrade the first region​

Upgrade the first region with the updated values file. The deployment stays at zero replicas after the upgrade because the tool doesn't override the manual scale-down.

Modify the following with your specific values to generate a copyable command:
vcluster platform start \
--namespace vcluster-platform \
--kube-context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
--values platform-us-east-1-values.yaml \
--upgrade \
--no-tunnel

Step 3 - Upgrade the second region (rolling)​

Upgrade the second region without scaling down. This performs a rolling update so the region continues serving traffic during the upgrade.

Modify the following with your specific values to generate a copyable command:
vcluster platform start \
--namespace vcluster-platform \
--kube-context arn:aws:eks:eu-west-1:123456789012:cluster/platform-multi-region-eu-west-1 \
--values platform-eu-west-1-values.yaml \
--upgrade \
--no-tunnel

Wait for the rollout to complete.

kubectl --context arn:aws:eks:eu-west-1:123456789012:cluster/platform-multi-region-eu-west-1 \
rollout status deployment/loft -n vcluster-platform

Step 4 - Scale up the first region​

Bring the first region back online.

Replace the replica count with the replicaCount value from the region's values file.

Modify the following with your specific values to generate a copyable command:
kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
scale deployment -n vcluster-platform loft --replicas=3

Wait for all pods to become ready.

kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
rollout status deployment/loft -n vcluster-platform

Step 5 - Verify all deployments​

Confirm that both platform and agent deployments are running the expected image.

for CTX in arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 arn:aws:eks:eu-west-1:123456789012:cluster/platform-multi-region-eu-west-1; do
echo "=== $CTX ==="
echo -n "Platform: " && kubectl --context "$CTX" get deployment -n vcluster-platform loft \
  -o jsonpath='{.spec.template.spec.containers[0].image}' && echo
echo -n "Agent:    " && kubectl --context "$CTX" get deployment -n vcluster-agent loft \
  -o jsonpath='{.spec.template.spec.containers[0].image}' && echo
echo
done

The platform automatically upgrades connected agents after the platform upgrade completes.