Skip to main content
Version: main 🚧

Platform-Managed vs. Externally Deployed Tenant Clusters

Tenant clusters in vCluster Platform are either platform-managed or externally deployed, depending on how they are created and who manages their lifecycle.

externally deployed

Platform-managed tenant clusters​

Platform deploys and fully manages platform-managed tenant clusters. It handles provisioning, upgrades, configuration changes, and deletion. All platform features are available.

Deployment methods:

  • Platform UI
  • vcluster platform create vcluster <name> CLI command

Externally deployed tenant clusters​

Externally deployed tenant clusters are created outside Platform using tools like Helm, Argo CD, Terraform, or ClusterAPI. You can connect them to Platform to gain visibility and access to certain features without changing how their lifecycle is managed.

Perform lifecycle changes (upgrades, configuration updates, deletion) through the original deployment tool, not the Platform UI. Platform does not reconcile externally deployed clusters.

Available Platform features when connected​

When you add an externally deployed tenant cluster to Platform and connect it with the vCluster Platform agent, the following features become available:

  • Auto sleep (requires agent and vcluster.yaml configuration)
  • Pro features of vCluster (license key distribution)
  • Administrative overview of the tenant cluster fleet
  • UI inspection of cluster versions, enabled features, and resources
  • Issue detection (outdated Kubernetes versions, vCluster errors)
  • Health status monitoring and enhanced debugging
  • User access management through Platform (useful with SSO)
  • Platform integrations (Argo CD, Vault secrets, and others)
note

Features in the platform: section of vcluster.yaml are only available if the agent is installed.

Choose a deployment model​

You can choose per-project or per-tenant-cluster, mixing both models in the same environment.

Use platform-managed when:

  • You want the simplest operational model with full feature access
  • Tenant clusters are created on demand with no need for external provisioning tooling

Use externally deployed when:

  • You already manage tenant cluster lifecycle with Argo CD, ClusterAPI, or Terraform and want to keep that workflow
  • You need GitOps-driven provisioning with Platform visibility and access control

Connect an externally deployed tenant cluster​

To add an existing tenant cluster to Platform without transferring lifecycle management:

  1. Ensure the tenant cluster is running vCluster v0.20 or later.
  2. Run: 
    vcluster platform add vcluster [name]

This is non-invasive and reversible. Your existing deployment workflow remains unchanged.

Next steps​