Upgrade vCluster Platform

Upgrade vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster Platform using the vCluster CLI, Helm, or GitOps, matching however you originally installed it. If you installed in an air-gapped environment, see Upgrade in an air-gapped environment instead of the steps below.

warning

If you are using a vCluster Platform version earlier than v4.0, upgrade to v4.0 first by following the v3 to v4 upgrade instructions.

Upgrade the platform

Upgrade considerations

• Review the release notes for the target version to understand any breaking changes or new features.
• Test the upgrade in a non-production environment before applying it to your production setup.

Upgrade the platform using:

CLI

To upgrade the platform using the vcluster CLI, update $PLATFORM_VERSION with a valid platform version and run:

Upgrade the platform using vCluster CLI

RELEASE_NAMESPACE=vcluster-platform # Replace with the namespace of the platform deployment if different
PLATFORM_VERSION='' # Set this to a specific version or leave empty for latest

vcluster platform start --upgrade --version=$PLATFORM_VERSION --namespace=$RELEASE_NAMESPACE --values=vcluster-platform.yaml

Helm

To upgrade the platform using helm, update $PLATFORM_VERSION with a valid platform version and run:

Upgrade the platform using helm

RELEASE_NAME=vcluster-platform # Replace with the release name if different
RELEASE_NAMESPACE=vcluster-platform # Replace with the namespace of the platform deployment if different
PLATFORM_VERSION='' # Set this to a specific version or leave empty for latest

helm upgrade $RELEASE_NAME vcluster-platform -n $RELEASE_NAMESPACE --repository-config '' --repo https://charts.loft.sh \
  --version $PLATFORM_VERSION \
  --reuse-values \
  -f vcluster-platform.yaml

Server-side apply with Helm 4

Helm 4 keeps the apply method a release was created with, so upgrades need no extra flags. If you switch a release to server-side apply with --server-side=true, the upgrade fails with a conflict on any field the platform has written itself. The most common one is data.config in the loft-manager-config secret after you edit the config in the UI. Add --force-conflicts to let Helm take ownership of those fields. Either way, keep the config section of your values file in sync with changes made in the UI. The upgrade replaces the secret with the values from the file.

Versions and Values

The $PLATFORM_VERSION environment variable specifies the vCluster Platform version to deploy.
The vcluster-platform.yaml file is optional and defines Helm values to use when upgrading the vCluster Platform deployment.

Upgrade a GitOps-managed deployment

If you installed the platform using GitOps (see Install with ArgoCD), upgrade by updating the chart version in your GitOps manifests and letting

your GitOps tool apply it, rather than running vcluster platform start or helm upgrade directly against the cluster.

ArgoCD

Update spec.source.targetRevision on the platform Application to the target version, then sync.

Update the platform Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: vcluster-platform
  namespace: argocd
spec:
  source:
    targetRevision: "4.12.0" # Replace with the target version
    chart: vcluster-platform
    repoURL: "https://charts.loft.sh"

Commit the change to the repository ArgoCD watches. With automated sync enabled, ArgoCD applies the new chart version on its next sync. To apply it right away instead of waiting, trigger a sync:

Trigger a sync

argocd app sync vcluster-platform

The platform creates and updates its own CRDs when it starts, so the Application needs no CRD-specific sync options.

Flux

Update spec.chart.spec.version on the platform HelmRelease to the target version, then reconcile.

Update the platform HelmRelease

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: vcluster-platform
  namespace: vcluster-platform
spec:
  chart:
    spec:
      version: "4.12.0" # Replace with the target version
      chart: vcluster-platform
      sourceRef:
        kind: HelmRepository
        name: vcluster-platform

Commit the change to the repository Flux watches. Flux applies the new chart version on its next reconciliation. To apply it right away instead of waiting, trigger a reconciliation:

Trigger a reconciliation

flux reconcile helmrelease vcluster-platform -n vcluster-platform

The platform creates and updates its own CRDs when it starts, so the HelmRelease needs no CRD policy settings.

Verify the upgrade

These checks apply to every upgrade method. Replace vcluster-platform with your platform namespace if you installed it elsewhere.

Wait for the rollout to finish.

Wait for the rollout

kubectl rollout status deployment/loft -n vcluster-platform

Confirm the deployment runs the version you upgraded to.

Check the running image

kubectl get deployment -n vcluster-platform loft \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

The platform upgrades connected agents automatically once its own upgrade completes, so you don't upgrade them separately. To check one, run the same command against the connected cluster's context, using the namespace the agent is installed in.

If the rollout doesn't finish, inspect the pod and its logs.

Inspect the platform pod

kubectl get pods -n vcluster-platform -l app=loft
kubectl logs -n vcluster-platform -l app=loft --tail=50