Removing a Cluster and Loft Agent from Loft Platform

Overview

When a cluster is disconnected via the Loft UI, the Loft agent and its associated resources are not automatically removed from the cluster. This is by design, as the platform stores persistent metadata (e.g., external database connectors for vClusters) in custom resources that reside in the cluster. To fully remove all Loft-related components and ensure a clean state for reconnection, follow the process below.

Why the Loft Agent remains

When you disconnect a cluster from the Loft UI, only its visibility is removed from the UI. The Loft agent and other resources (e.g., CRDs, webhooks, namespaces) remain in the cluster:

  • This protects running vClusters and avoids accidental deletion of essential resources.
  • Manual removal is required if you intend to decommission the cluster or prepare it for reattachment.

Risks of partial uninstall

Running helm delete without following the full uninstall procedure may leave behind:

  • Custom Resource Definitions (CRDs)
  • Namespaces
  • Webhooks
  • API services
  • Finalizers that block namespace deletion

These remnants can cause issues when reconnecting the cluster to Loft or deploying new Loft agents.

Full uninstall procedure

To fully remove the Loft platform agent and related components from a cluster:

Step 1: Delete the platform Helm release 

helm delete -n vcluster-platform loft

helm delete -n loft loft

helm delete -n vcluster-platform opencost prometheus

Step 3: Delete associated API service and webhook 

kubectl delete apiservice v1.cluster.loft.sh

kubectl delete validatingwebhookconfiguration loft-agent

Step 4: Delete Loft platform CRDs 

kubectl api-resources --api-group='storage.loft.sh' -o name | xargs kubectl delete crd

Step 5: Delete the vcluster-platform namespace 

kubectl delete namespace vcluster-platform

Notes

  • Some resources may be blocked from deletion by Kubernetes finalizers. You may need to manually remove these finalizers before the namespace can be deleted.
  • Leftover ApiService or ValidatingWebhookConfiguration resources can prevent reinstallation or reconnection of the Loft agent.
  • Refer to the official Loft uninstall documentation for more detailed guidance.

Reconnecting a clean cluster

After performing a complete uninstall:

  • You can reinstall the Loft agent using the vcluster platform connect command copied from the Loft UI.
  • Ensure all previous resources are fully removed before attempting reconnection to avoid configuration conflicts.

Known issues

  • The vcluster platform destroy command may fail in some environments due to CLI bugs. A bug report has been submitted to the Loft engineering team.
  • If this command fails, follow the manual uninstall steps outlined above.

Edit this page on GitHub