Skip to main content
Version: v0.26 Stable

What is vcluster.yaml?

Every virtual cluster requires configuration settings that define how it operates within your host Kubernetes cluster. The vcluster.yaml file is the central configuration source for these settings. It controls everything from the control plane architecture to resource sync behavior between the virtual and host clusters.

When you deploy a virtual cluster, the vCluster CLI uses this configuration file and applies your specified settings. The file is optional - if you don't provide one, vCluster applies defaults that work for most use cases. However, most production deployments benefit from custom configuration to match specific requirements.

Configuration structure for vcluster.yaml​

The vcluster.yaml file organizes configuration into logical sections. Each section controls a specific aspect of virtual cluster behavior.

Control plane settings​

The control plane section defines how vCluster runs its Kubernetes API server, controller manager, and data storage. Key configuration areas include:

  • Backing store selection: Choose between different storage backends for the vCluster control plane's backing store. Options include embedded databases, managed etcd or external databases.

  • Deployment settings: Configure how the control plane pods deploy, including resource limits, node selectors, and affinity rules.

  • Networking options: Define how external traffic reaches the virtual cluster's API server, including ingress configuration and service exposure methods.

Resource sync rules​

Virtual clusters need to share certain resources with their host cluster to function properly. The sync configuration controls this sharing in both directions:

  • From host to virtual: Configure which host cluster resources appear inside the virtual cluster through host-to-virtual synchronization. Common examples include nodes, storage classes, and priority classes.

  • From virtual to host: Define which virtual cluster resources sync to the host cluster through virtual-to-host synchronization. This typically includes pods, services, and persistent volume claims that need to run on the host.

Access configuration​

You can configure access settings to control how users and applications connect to the virtual cluster:

  • The kubeconfig file: Configure how vCluster generates and stores the kubeconfig file that clients use to connect. This file contains API server endpoints, authentication credentials, and cluster context. You specify the Kubernetes secret name for storage, the context name for identification, and the server URL for connection.

  • Authentication methods: vCluster supports certificate-based and service account token authentication for secure access to the virtual cluster. When exposing vCluster through an ingress or load balancer, you can use service account tokens if client certificate validation is not supported. Authentication methods can be customized to fit your access requirements.

Example vcluster.yaml configuration​

The following example demonstrates a common configuration and explains each section's purpose:

vcluster.yaml
# Control plane configuration
controlPlane:
  # Configure the backing store for vCluster's data
  backingStore: # Enterprise feature - requires license
    etcd:
      embedded: 
        enabled: true  # Run etcd inside the vCluster pod
  
  # Expose the API server via ingress
  ingress:
    enabled: true
    host: vcluster-k8s-api.example.com  # Your API server hostname

# Resource synchronization settings
sync:
  # Resources that sync from virtual cluster to host
  toHost:
    serviceAccounts:
      enabled: true  # Sync ServiceAccounts for operators/controllers
  
  # Resources that sync from host to virtual cluster  
  fromHost:
    nodes:
      enabled: true  # Sync real nodes instead of fake nodes
      clearImageStatus: true  # Remove image data to save resources

# Kubeconfig export configuration
exportKubeConfig:
  context: my-vcluster-context  # Name in the kubeconfig file
  server: https://vcluster-k8s-api.example.com  # API server URL
  secret:
    name: my-vcluster-kubeconfig  # Secret name for storing kubeconfig

Each configuration section has a specific purpose in the virtual cluster setup:

  • Control plane with embedded storage: The configuration uses embedded etcd as the data store for the virtual cluster's control plane. This approach reduces operational complexity because etcd runs inside the vCluster pod rather than requiring a separate database.

  • API server exposure: An Ingress resource exposes the virtual cluster's API server through a hostname. This allows external tools and users to access the virtual cluster without port-forwarding or NodePort services.

  • ServiceAccount synchronization: The configuration enables ServiceAccount syncing from the virtual cluster to the host. This synchronization supports workloads that need specific permissions on the host cluster, such as operators or controllers that manage host resources.

  • Real node synchronization: Instead of using vCluster's default "pseudo" nodes, this configuration syncs real node information from the host cluster. The clearImageStatus option removes image information from synced nodes to reduce data transfer and storage requirements.

  • Kubeconfig access: The configuration defines how vCluster exports the kubeconfig for accessing the virtual cluster. The exported kubeconfig gets stored in a Kubernetes secret, making it available for CI/CD pipelines, ArgoCD apps, or Terraform configurations.

Use vcluster.yaml​

The configuration file is used with various vCluster operations throughout the virtual cluster lifecycle.

Create a new virtual cluster​

When you create a virtual cluster, vCluster uses the settings specified in your configuration file. To create a virtual cluster with custom configuration:

  1. Save your configuration options in a file named vcluster.yaml.

  2. Run the deployment command with your configuration file:

    vcluster create my-vcluster -f vcluster.yaml

  3. vCluster validates the configuration and creates the virtual cluster with your specified settings.

For detailed deployment instructions, see the deployment documentation.

Update an existing virtual cluster​

Configuration changes often become necessary as requirements evolve. You can update existing virtual clusters with new configurations. To update an existing virtual cluster:

  1. Edit your vcluster.yaml file with changes. For example, enable a new sync feature or adjust resource limits.

  2. Apply the updated configuration to your existing virtual cluster:

    vcluster create my-vcluster --upgrade -f vcluster.yaml

  3. vCluster reconciles the differences and updates the deployment. It compares the new configuration with the existing deployment and applies only the changes. The update preserves your workloads and data while updating the virtual cluster components.

For configuration change examples and update strategies, see the deploy changes documentation.

Frequently asked questions​

How to migrate from vCluster 0.19.x?

vCluster v0.20 introduced a new unified configuration format in vcluster.yaml. It replaces the older setup, which relied on:

  • CLI flags passed during creation
  • Helm values across multiple values.yaml files
  • Resource annotations
  • Distribution-specific formats
warning

Pre-v0.20 values.yaml files are not compatible with v0.20. Convert to vcluster.yaml before using the new CLI or upgrading clusters.

You must migrate to the new vcluster.yaml format before upgrading to vCluster v0.20 or later. Older configuration methods—like Helm values.yaml files and CLI flags—no longer work with the new version.

Use the migration guide to walk through:

  • Mapping your old CLI flags and Helm values to the new format.
  • Adjusting any distribution-specific settings.
  • Validating the new configuration to ensure it’s correct.
Is a vcluster.yaml file required?

The vcluster.yaml file is optional. If not provided, vCluster applies default settings that:

  • Use an embedded database (SQLite).
  • Sync essential resources such as pods and services.
  • Configure networking with basic ClusterIP services.
  • Enable default authentication and access controls.
note

The vcluster.yaml configuration defaults are for development and simple test scenarios. For production use, defining a vcluster.yaml file is strongly recommended to meet specific security, performance, and integration needs.

Can an existing virtual cluster be updated using vcluster.yaml?

Yes. You can update an existing virtual cluster by applying a modified vcluster.yaml file. This allows you to change the configuration without deleting or recreating the cluster.

To apply changes, use the --upgrade flag with the vcluster create command:

vcluster create VCLUSTER_NAME --upgrade -f vcluster.yaml

The command performs the following actions:

  1. Reads the updated vcluster.yaml file.
  2. Compares it to the current configuration of the virtual cluster.
  3. Applies only the differences between the new and existing configuration.
  4. Triggers a rolling update if required to apply the changes.

Some configuration changes, such as updates to sync settings, take effect immediately. Others, such as control plane modifications, may require pod restarts. The vCluster CLI handles these updates automatically and ensures minimal disruption to workloads.

For more details on updating virtual clusters, see the deployment changes documentation.