Skip to main content
Version: v4.11

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, overriding replicaCount to 0. Helm reapplies replicaCount from your values on every upgrade. Without the override, this region would come back up on the new version while the other region still runs the old one. The override keeps it scaled down until Step 4.

The CLI takes a single values file and has no --set flag. Copy the region's values file, set replicaCount: 0 in the copy, and pass the copy:

Modify the following with your specific values to generate a copyable command:
vcluster platform start \
--namespace vcluster-platform \
--context arn:aws:eks:us-east-1:123456789012:cluster/platform-multi-region-us-east-1 \
--values platform-us-east-1-values-scaled-down.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 \
--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 by running the upgrade again with its normal values file. This restores replicaCount in both the Helm release values and the deployment. You can use kubectl scale instead, but the Helm release values then still record replicaCount: 0 until the next upgrade.

Modify the following with your specific values to generate a copyable command:
vcluster platform start \
--namespace vcluster-platform \
--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

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.