Skip to main content
Version: v4.12 Stable

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.

Platform 4.12 also removes the resources that deployed apps before this release. If you have any apps deployed, see Upgrade to Platform 4.12 after completing the upgrade steps below.

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:

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
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.

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.

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

Upgrade to Platform 4.12​

If you have apps deployed on a cluster, tenant cluster, or space, upgrading to Platform 4.12 doesn't disrupt them. Each app's underlying Helm release keeps running exactly as before. What changes is how the platform manages that release. Platform 4.12 removes the old resources that used to represent a deployed app:

  • The old Task API.
  • The HelmRelease resource, in both its cluster-scoped variant and the legacy virtualcluster.loft.sh/v1 API group variant.
  • The chart-discovery endpoints that backed the old Apps UI.

Once these are gone, the platform can no longer update, upgrade, or delete an app through the old flow. Until you migrate it, an app shows up as a plain Helm release with no platform-side management. Migrate each app to keep managing it through the platform.

Not the vCluster chart's own HelmRelease

This removal doesn't affect the spec.template.helmRelease field on a tenant cluster or tenant cluster template. That field describes the vCluster chart's own Helm release, and is unrelated to the removed app-deployment resources.

Migrate an existing app deployment​

These resources are replaced by AppInstance, which deploys an App into a tenant cluster, space, or connected cluster. Migrating an existing app to AppInstance is a UI action, not a CLI or API migration.

To find the migration action, open the App's cluster or tenant cluster and click the Apps button. This is the same view used to update an installed App.

The Apps table's Type column tells these apart. A Legacy App row shows the Migrate action when its original App still exists, and the App must include the version referenced by the Helm release. A Template App row is declared in the tenant cluster or space configuration itself, continues to use that configuration, and doesn't need this migration.

The Migrate action:

  1. Reads the app name and version from the annotations the old flow set on the existing Helm release.
  2. Opens a prefilled AppInstance form so you can review the release name, namespace, app version, and parameters before saving.
  3. Creates an AppInstance that runs helm upgrade --install against the existing release name and namespace. This adopts the release in place instead of installing a second release.

Because saving the AppInstance performs a Helm upgrade, review the prefilled version and parameters first. Whether the application's workloads restart depends on the chart and resulting manifest changes.

Migrate each Legacy App that you want the platform to continue managing. There's no deadline, but an App remains unmanaged by the platform until you migrate it.

If the action isn't available, confirm that the original App and referenced version still exist. Restore the App definition before migrating, or manage the existing Helm release outside the platform.

Move standalone snapshot credentials​

Platform 4.12 ignores snapshots.auto.storage.<provider>.credential.secretNamespace for standalone tenant clusters, and instead always reads the credential Secret from the Platform project namespace that contains the VirtualClusterInstance.

Before upgrading each affected standalone tenant cluster:

  1. Find the credential secretName and any secretNamespace configured for S3, OCI, or Azure snapshot storage.
  2. Copy or recreate that Secret in the Platform project namespace that contains the VirtualClusterInstance. Skip this step when the Secret is already there.
  3. Remove secretNamespace from the tenant cluster configuration and any template that supplies it.
  4. Confirm that the Secret contains the required keys for the configured storage provider.
Configuration before Platform 4.12
snapshots:
  auto:
    storage:
      type: s3
      s3:
        credential:
          # Platform 4.12 ignores this namespace for standalone tenant clusters.
          secretNamespace: backup-secrets
          secretName: aws-credentials
Configuration for Platform 4.12
snapshots:
  auto:
    storage:
      type: s3
      s3:
        credential:
          # Create this Secret in the VirtualClusterInstance project namespace.
          secretName: aws-credentials

Pod-based tenant clusters continue to resolve secretNamespace in their connected control plane cluster. For standalone requirements and storage limitations, see Auto snapshots on standalone tenant clusters.