vCluster Standalone

Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a binary for vCluster Standalone, which uses private nodes.

vCluster Standalone is a different architecture model for vCluster for the control plane and node as there is no requirement of a host cluster. vCluster is deployed directly onto nodes like other Kubernetes distribution. vCluster Standalone can run on any type of node, whether that is a bare-metal node or VM. It provides the strictest isolation for workloads as there is no shared host cluster for the control plane or worker nodes.

When enabling vCluster Standalone, the control plane is now no longer on a shared host cluster, but on its own independent node. Worker nodes must be private nodes.

Installation Overview

vCluster Standalone requires having dedicated nodes to build your control plane nodes and optionally add additional worker nodes.

The steps are to bring up a vCluster Standalone cluster are:

1. Install an initial control plane node.
2. (Optional) Join additional control plane nodes.
3. (Optional) Join worker nodes.

vcluster.yaml configuration

To create a vCluster Standalone with one node that is the control plane and worker node. Read more about high availability.

Enable standalone

controlPlane:
  # Enable standalone
  standalone:
    enabled: true
    joinNode:
      enabled: true  # Optional: Control Plane node will also be considered a worker node 
  distro:
    k8s:
      image:
        tag: v1.31.2 # Kubernetes version you want to use
  service:
    spec:
      type: LoadBalancer # If you want to expose vCluster using LoadBalancer (Recommended option)

# Required for adding additional worker nodes
privateNodes: 
  enabled: true
  
# Networking configuration
networking:
  # Specify the pod CIDR
  podCIDR: 10.64.0.0/16
  # Specify the service CIDR
  serviceCIDR: 10.128.0.0/16

Other vCluster feature limitations

Certain vCluster features are automatically disabled or unavailable. If you include these options in your vcluster.yaml, they are ignored or might cause configuration errors.

The following features are not available:

• sync.* - No resource syncing between virtual and host clusters
• integrations.* - Integrations depend on syncing functionality
• networking.replicateServices - Services are not replicated to host
• controlPlane.distro.k3s - Only standard Kubernetes (k8s) is supported
• controlPlane.coredns.embedded: true - Embedded CoreDNS conflicts with custom CNI
• controlPlane.advanced.virtualScheduler.enabled: false - Virtual scheduler cannot be disabled
• sleepMode.* - No ability to sleep workloads or control plane

Unsupported vcluster.yaml options with private nodes

# These configurations are NOT supported with private nodes

# Resource syncing between virtual and host clusters is disabled
sync:
  services:
    enabled: false  # Services cannot be synced to host cluster
  secrets:
    enabled: false  # Secrets cannot be synced to host cluster
                    # All other sync options (pods, configmaps, etc.) are also disabled

# Platform integrations require syncing functionality
integrations:
  metricsServer:
    enabled: false  # Metrics server integration not supported
                    # All other integrations are disabled due to sync dependency

# Service replication to host cluster is not available
networking:
  replicateServices:
    enabled: false  # Services run entirely within virtual cluster

# Distribution restrictions
controlPlane:
  distro:
    k3s:
      enabled: false  # k3s distribution not supported
    k8s:
      enabled: true   # Only standard Kubernetes works

  # DNS configuration limitations
  coredns:
    embedded: false   # Embedded CoreDNS conflicts with custom CNI options
  advanced:
    # Virtual scheduler is required for workload placement
    virtualScheduler:
      enabled: true   # Always enabled (cannot be disabled)
  # Host Path Mapper is not supported
  hostPathMapper:
    enabled: false

# Sleep mode is not available
sleepMode:
  enabled: false