Skip to main content
Version: main 🚧

Manage vCluster Standalone Control Plane Nodes

Supported Configurations
Running the control plane as a binary with vCluster Standalone. When scaling with additional worker nodes, they are joined as private nodes.

Managed by vCluster Platform​

Update configuration​

When a standalone cluster is connected to vCluster Platform, configuration updates and version upgrades can be coordinated from the Platform UI with rolling upgrades:

  1. Go to Virtual Clusters and select the vCluster.

  2. Click Edit.

  3. Change the configuration.

  4. Click Save.

For the full configuration reference, see config.yaml in the standalone configuration reference. Review the standalone limitations before changing settings.

Add and remove nodes​

When a standalone cluster is connected to vCluster Platform, add or remove nodes by updating the quantity in your configuration and saving the changes in the Platform UI. Worker node lifecycle is managed through the Platform UI when Auto Nodes are used, and provisioning is backed by Node Providers.

Example: scale control plane nodes
controlPlane:
  standalone:
    autoNodes:
      quantity: 3

Self-managed​

Connect to vCluster Platform​

Self-managed standalone vCluster can be connected to vCluster Platform. Once connected, configuration updates and version upgrades can be coordinated from the platform, but this does not make the nodes platform-managed.

Use the following command to connect a standalone cluster:

Connect a vCluster Standalone to vCluster Platform
vcluster platform add standalone my-cluster --project my-project --access-key my-access-key --host https://my-vcluster-platform.com

Update configuration​

Changing the vcluster.yaml configuration has to be done on all control plane nodes.

  1. Modify the vcluster.yaml.

    The vcluster.yaml is located at: /etc/vcluster/vcluster.yaml. Edit and save your changes.

  2. Restart vCluster systemD service to deploy your changes.

    Restart vCluster
    systemctl restart vcluster.service

Add nodes​

To add control plane nodes to a self-managed standalone cluster, create a join token on an existing control plane node, then run the join command on each new node:

  1. Create a control plane join token on an existing control plane node.

    Create a token for control plane nodes
    /var/lib/vcluster/bin/vcluster-cli token create --control-plane --expires=1h

  2. Run the returned join command on each new control plane node.

    Join a control plane node
    curl -sfLk https://<vcluster-endpoint>/node/join?token=<token> | sh -

Remove nodes​

If you have not enabled joining the control plane nodes as worker nodes, then removing vCluster requires only stopping the service and removing files from the nodes. For HA clusters, there are additional steps detailed below.

For control plane nodes that are joined in the cluster (controlPlane.standalone.joinNode.enabled: true), please first make sure you follow this processes worker node removal steps and node cleanup



  1. Stop the vCluster service on the control plane node.

    Stop vCluster service
    systemctl stop vcluster.service

  2. Remove vCluster files on the control plane node.

    Clean up vCluster files
    rm -rf /var/lib/vcluster && rm /etc/systemd/system/vcluster.service

Reuse nodes​

If you want to reuse a node that was already running vCluster standalone, you can do so by reseting the node and running install script again.

  1. To reset the node, run install script using --reset-only flag.

    Reset the node
    curl -sfL https://github.com/loft-sh/vcluster/releases/download/${VCLUSTER_VERSION}/install-standalone.sh | sh -s -- --reset-only

    You should see the following output:

    🧹 Resetting vCluster installation...
    ✅ Reset complete.

  2. Run the install script again.

    Run the install script again
    curl -sfL https://github.com/loft-sh/vcluster/releases/download/${VCLUSTER_VERSION}/install-standalone.sh | sh -s -- --vcluster-name my-new-vcluster --config ${PWD}/vcluster.yaml