Skip to main content
Version: main 🚧

What is vcluster.yaml?

The vcluster.yaml file contains all configuration options when deploying, making changes or upgrading a virtual cluster. It's an optional file passed to any deployment method, and without this file, a virtual cluster is created with a set of default values.

Example configuration options include the vCluster control plane's backing store, resource syncing behavior from and to the host cluster, and exporting the virtual cluster's kubeconfig file. Benefits of this file include:

  • Unified Configuration: All settings for vCluster in one place, simplifying management.
  • Schema Validation: Automatically validate the configuration when using the vCluster CLI.
  • IDE Support: Integrated schema with popular IDEs for autocompletion and validation.

Example vcluster.yaml file​

controlPlane:
  backingStore: # This backing store option is a Pro feature and requires a license. Remove it if you don't have a license.
    etcd:
      embedded: 
        enabled: true
  ingress:
    enabled: true
    host: vcluster-k8s-api.example.com
sync:
  toHost:
    serviceAccounts:
      enabled: true
  fromHost:
    nodes:
      enabled: true
      clearImageStatus: true
exportKubeConfig:
  context: my-vcluster-context
  server: https://vcluster-k8s-api.example.com
  secret:
    name: my-vcluster-kubeconfig

This example configuration defines:

  1. Embedded etcd as the vCluster control plane's backing store to reduce management overhead (Pro feature).
  2. Syncing ServiceAccount resources from the virtual to the host cluster, to support.
  3. Deploying an Ingress resource on the host cluster to expose the vCluster control plane's API server as a hostname.
  4. Syncing real node data, rather than the default "pseudo" nodes, but clears the ImageStatuses field within the NodeStatus of the synced nodes.
  5. How to export the kubeconfig file to a secret, so you can use it, for example, in your ArgoCD or Terraform pipelines.

How to Use vcluster.yaml​

Create a New Virtual Cluster​

After defining your configuration options in your vcluster.yaml, you can deploy a new virtual cluster.

Apply Changes to an existing Virtual Cluster​

If you've already deployed a virtual cluster and discover new configuration options that you want to apply, you can update your vcluster.yaml and then deploy those new changes.

FAQs​

How do I upgrade my 0.19.x and earlier virtual cluster configurations?​

Since the deployment of vCluster has significantly changed from a combination of CLI flags, annotations and various values.yaml files based on distro, any old values.yaml will not be usable with v0.20. If you have existing 0.19.x virtual clusters, you must convert the old configuration values.yaml to the new v0.20 format before attempting to upgrade.

View the conversion guide for more details.

warning

Pre-v0.20.0 values.yaml files are not compatible with v0.20.0. You need to convert to the new format in order to use the new vCluster CLI and upgrade existing vCluster instances.

Is it required to provide a vcluster.yaml file?​

No, if a vcluster.yaml file isn't provided, the vCluster will be created using a set of default values.

Can I change the configuration for existing virtual clusters?​

Yes, you can run vcluster create VCLUSTER_NAME --upgrade -f vcluster.yaml