Skip to main content
Version: main 🚧

Restore vCluster Platform

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

As a system admin, restore vCluster Platform management resources and identity after an outage or during migration to another control plane cluster. Use an existing management backup for installations that store management resources in the control plane cluster's Kubernetes API. For an external database, follow Restore an external database. The platform stores its identity Secrets in that database, so restoring the database restores them too.

For administrator lockout on an existing installation, use Reset the admin password. Account recovery doesn't require restoring the management plane.

Before you begin​

  • Use the vCluster v0.38 backup format for these Platform v5.0 procedures.
  • Install kubectl, Helm, and Mike Farah's yq v4 for the commands below.
  • Use credentials that can manage the destination Helm release, Deployment, namespaces, and backed-up resources and Secrets.
  • Check the backup contents and limits before choosing a restore path.
  • Keep the original Helm values, chart version, domain, and environment-specific credentials available.
  • Schedule a maintenance window. Restoration overwrites resources and can require a platform restart.
  • Before changing versions, review platform upgrades and the CLI upgrade guidance.
UI restore doesn't restore platform identity

UI restore ignores loft-cert, loft-network-control-key, and loft-license-cache, even in an uploaded CLI backup. UI backups omit these Secrets. Preserve and restore them separately through Kubernetes. A CLI backup omits Tenant resources and their configuration Secrets. For installations using Tenants, review the recovery plan with support before migration.

The backup contains credentials and private keys. Handle it in encrypted storage with controlled access, and don't print Secret data into shared logs.

For GitOps-managed installations, make replica and configuration changes through the owning GitOps manifests. The Helm commands below assume Helm manages the release directly.

Choose the sequence for your target. Keep the source platform stopped during a migration cutover, and verify the target Kubernetes context before applying anything. Don't run two active installations with the same identity against the same connected clusters.

Restore onto a fresh cluster​

This procedure uses the same platform namespace and compatible chart version as the source. It applies to management resources stored in Kubernetes, without Tenants or other required resources omitted from the CLI backup. Use a rehearsed recovery plan for other configurations.

  1. Prepare the destination namespace and restore environment-specific TLS and other prerequisites separately. Keep the intended domain and DNS cutover plan consistent with the connected clusters' platform endpoint.

  2. Install the chart with zero replicas, using the complete source values file:

    helm upgrade --install vcluster-platform vcluster-platform --repo https://charts.loft.sh --namespace vcluster-platform --create-namespace --version 5.0.0 --values values.yaml --set replicaCount=0

    Zero replicas prevent the platform from generating a new identity before restoration.

  3. Extract only the three identity Secrets, then apply them before starting the platform:

    umask 077
    yq eval 'select(.kind == "Secret" and (.metadata.name == "loft-cert" or .metadata.name == "loft-network-control-key" or .metadata.name == "loft-license-cache"))' backup.yaml > platform-identity.yaml
    kubectl apply -f platform-identity.yaml

    Confirm the expected Secrets exist in the destination namespace. Don't apply the full backup yet. The backup contains custom resource instances, not the Custom Resource Definitions (CRDs) that define them. The platform process creates those CRDs at startup.

  4. Start the platform with the intended replica count from the complete values file:

    helm upgrade vcluster-platform vcluster-platform --repo https://charts.loft.sh --namespace vcluster-platform --version 5.0.0 --values values.yaml
    kubectl --namespace vcluster-platform rollout status deployment/loft

    Ensure values.yaml sets your intended nonzero replicaCount.

  5. Review the backup's namespaces and local-cluster registration. If the backup includes the source's loft-cluster Cluster and the destination is a different Kubernetes cluster, remove that document. Its loft.sh/cluster-uid annotation doesn't match the destination, and applying it would overwrite the destination's own loft-cluster. The destination platform creates that local registration whenever none exists, even with DISABLE_DEFAULTS set. It has no configuration Secret to remove. See Exclude resources for the reason and for remote registrations:

    umask 077
    yq eval 'select(.kind != "Cluster" or .metadata.name != "loft-cluster")' backup.yaml > restore.yaml

    Apply the management resources. If you kept the loft-cluster document, set the file to the original backup instead:

    Modify the following with your specific values to generate a copyable command:
    kubectl apply -f restore.yaml

    The platform creates each Project's namespace after the Project is applied, so resources in that namespace can fail in the same apply. If they do, wait for the Project namespaces to appear and apply the file again. Resolve every apply error before continuing. Move DNS to the destination when it's ready, then complete the verification steps below.

Restore onto an existing installation​

Review which existing resources the backup overwrites before applying it. Use a backup from the same installation for same-cluster recovery. Restart the platform Deployment after applying. The restart loads restored identity Secrets and re-owns restored Tenant configuration Secrets:

kubectl apply -f backup.yaml
kubectl --namespace vcluster-platform rollout restart deployment/loft
kubectl --namespace vcluster-platform rollout status deployment/loft

Restore through the UI​

Navigate to Platform > Platform Config > Backup and Restore, click Restore under Restore Configuration, and select the backup file.

  • UI restore skips identity Secrets. Restore those separately through Kubernetes, then restart if their values changed.
  • UI restore records each object that fails to apply in the platform logs and continues with the rest. The success message doesn't confirm that every object applied. Check the platform logs for apply backup errors, then complete the verification steps below.
  • Restore a UI backup that contains Tenants through the UI. UI restore re-establishes each Tenant configuration Secret's owner reference, and returns an error if that step fails. If you apply the same file with kubectl, those Secrets stay unowned until the platform restarts. Until then, the platform doesn't read the Tenants' configuration, including hostnames. Restart the loft Deployment after a kubectl apply, as shown in Restore onto an existing installation.

Restore with Velero or an etcd snapshot​

Restoring a management backup doesn't affect node provider state, because the backup doesn't include NodeClaim objects or provider objects.

A Velero or etcd snapshot restore of the control plane cluster is different. It rolls back NodeClaim objects, but not the external state behind them. That external state includes Metal3 and Ironic, NICo, and cloud provider resources. After the restore, you must find and clean up the orphaned provider resources. See Clean up node provider resources after an etcd restore.

Verify the restore​

Before declaring recovery complete:

  1. Confirm the Deployment is ready, the platform endpoint is reachable, and administrator login works.
  2. Compare the license instance ID with the source and check license validity. See Restore license.
  3. Confirm the expected Projects, users, instances, and remote registrations exist.
  4. Confirm connected clusters reconnect after DNS cutover without restarting their control planes to repair tunnel identity.
  5. During a planned test, restart a connected cluster's control plane. Confirm it adopts the existing instance without creating a suffixed duplicate.
  6. Check the local control plane cluster registration for ClusterUID failures. Verify Argo CD cluster Secrets when you use that integration.
  7. Test workload access and separately restored storage using your workload recovery plan.

Record the platform and CLI versions, backup contents, and test results with your recovery plan. Retire the source only after verification, and remove temporary backup copies according to your retention policy.

Troubleshoot a restore​

SymptomCheck
Apply reports an unknown resource kindConfirm platform startup created the required CRDs. Check whether the installation uses an external database.
Apply reports resource name may not be empty for a SecretA User or Cluster referenced a Secret that was missing at backup time. Remove the empty Secret document, apply again, then recreate that credential. For the admin account, use Helm recovery.
License identity changesRestore the original loft-cert and restart the platform. See license recovery.
Connected clusters don't reconnectConfirm DNS, ingress TLS, and the restored loft-network-control-key. Restart the platform after replacing identity Secrets.
A duplicate instance appears after restartCheck that the original backup retained status.serviceUID. Contact support before deleting either instance.
Local registration reports ClusterUIDCheck whether a source loft-cluster registration was restored onto a different Kubernetes cluster.

If identity, database, or registration recovery remains uncertain, contact support before replacing more resources. Share versions and redacted errors, never the raw backup file.

Next steps​