Upgrade in an air-gapped environment
This page covers upgrading vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs. Platform when it was installed in an air-gapped environment (see With Offline License Key or With Offline License Server). Unlike the regular upgrade, an air-gapped upgrade starts by re-populating your private registry with the target version's images and Helm chart. Your control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both. has no route to the public registries vCluster Labs publishes to, so it can only pull what you've mirrored.
Step 1 - Populate the registry with the target version​
On a machine with internet access, repeat the registry-population steps from
the install guide for the version you're upgrading to. This is the same
download-images.sh, push-images.sh, helm pull, and helm push workflow
used during install. See Populate images to private registry
and Populate the Helm charts to a private registry
for the full walkthrough, including multi-platform images and insecure
registries.
Platform images and chart​
export PLATFORM_VERSION=4.11.2
export REGISTRY=ecr.io/myteam
wget -O images.txt https://github.com/loft-sh/loft/releases/download/v${PLATFORM_VERSION}/images.txt
wget -O download-images.sh https://github.com/loft-sh/loft/releases/download/v${PLATFORM_VERSION}/download-images.sh
wget -O push-images.sh https://github.com/loft-sh/loft/releases/download/v${PLATFORM_VERSION}/push-images.sh
chmod +x ./download-images.sh ./push-images.sh
./download-images.sh --image-list images.txt --images loft-images.tar.gz
./push-images.sh --registry ${REGISTRY} --images loft-images.tar.gz --image-list images.txt
helm pull vcluster-platform --repo https://charts.loft.sh --version ${PLATFORM_VERSION}
helm push vcluster-platform-${PLATFORM_VERSION}.tgz oci://${REGISTRY}/charts
vCluster images and chart​
Do this only if you're also moving tenant clustersTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster. to a new vCluster
version. Both projects publish a release file named images.txt, so these
commands save the vCluster list as vcluster-images.txt and pass it to both
scripts explicitly. The scripts default to images.txt, which at this point
still holds the platform list from the previous step.
export VCLUSTER_VERSION=0.36.2
export REGISTRY=ecr.io/myteam
wget -O vcluster-images.txt https://github.com/loft-sh/vcluster/releases/download/v${VCLUSTER_VERSION}/images.txt
./download-images.sh --image-list vcluster-images.txt --images vcluster-images.tar.gz
./push-images.sh --registry ${REGISTRY} --images vcluster-images.tar.gz --image-list vcluster-images.txt
helm pull vcluster --repo https://charts.loft.sh --version ${VCLUSTER_VERSION}
helm push vcluster-${VCLUSTER_VERSION}.tgz oci://${REGISTRY}/charts
After mirroring, update the chart version on any tenant cluster templates that pin a vCluster version. For the optional image sets covering other Kubernetes distributions and versions, see Pull and push images for vCluster.
Step 2 - Upgrade the platform deployment​
Run helm upgrade against the chart version you just pushed, reusing your
existing vcluster-platform.yaml values file. That file already points the
platform and its agents at your private registry, so those settings carry
over automatically. The relevant keys are imageRef,
env.DEFAULT_IMAGE_REGISTRY, env.DEFAULT_VCLUSTER_CHART_REPO, and
agentValues.env, as set up under Configure and install vCluster Platform and agent.
One value doesn't carry over. imageRef.tag pins the image to the version you
installed, and it overrides the chart version. The command below sets it for
this upgrade. Update it in vcluster-platform.yaml as well, so later upgrades
don't revert to the old image.
export PLATFORM_VERSION=4.11.2
export REGISTRY=ecr.io/myteam
export PLATFORM_NAMESPACE=vcluster-platform
helm upgrade vcluster-platform oci://${REGISTRY}/charts/vcluster-platform:${PLATFORM_VERSION} \
--version ${PLATFORM_VERSION} \
--namespace ${PLATFORM_NAMESPACE} \
--values vcluster-platform.yaml \
--set imageRef.tag=${PLATFORM_VERSION}
If you use Helm 4 with --server-side=true, see the note on server-side apply
conflicts in Upgrade vCluster Platform.
vCluster Platform exclusively supports the default secret backend for
storing Helm releases. Alternative HELM_DRIVER configurations (such as
configmap or sql) are not supported.
Step 3 - Verify the deployment​
Confirm the platform and agent deployments are running the target image from your private registry:
kubectl get deployment -n ${PLATFORM_NAMESPACE} loft \
-o jsonpath='{.spec.template.spec.containers[0].image}'
The platform automatically upgrades connected agents to the same version once the platform upgrade completes, pulling from the same private registry.