Skip to main content

What is vcluster.yaml (w/Pro)?

The vcluster.yaml file contains all configurations when deploying and upgrading virtual clusters. It's optionally passed to the CLI or as the values file for deployments using Helm. It is also possible to create a vCluster without a vcluster.yaml file which will be created with a set of default values.

Example configurations 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.

  • 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:
    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, for example, AWS IRSA.
  3. Deploying an Ingress resource on the host cluster to expose the vCluster control plane's API server at 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​

Creating a New Virtual Cluster​

  • Define your configurations in the vcluster.yaml file.
  • Deploy your virtual cluster.

  1. Install the vCluster CLI.

    brew install loft-sh/tap/vcluster-experimental

    If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

  2. Deploy vCluster.

    vcluster create my-vcluster --namespace team-x --values vcluster.yaml

    When the installation finishes, you are automatically connected to the virtual cluster. You Kubernetes context is updated to point to your new virtual cluster. You can run local kubectl commands for the new virtual cluster.

Updating Existing Virtual Clusters​

  • Simply update your vcluster.yaml file with the new configurations.
  • Apply the updates.
vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

Replace:

  • VCLUSTER_NAME with your vCluster instance name.
  • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

FAQs​

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

If you have existing 0.19.x virtual clusters, you can convert the old configuration values to the new v0.20 format. View the guide for more details.

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

Pro Features​

All the OSS features are applicable in any vcluster.yaml. Below are the Pro features only available on the vCluster Platform.

Config reference​

external required object pro​

External holds external tool configuration

platform required object pro​

Platform holds configuration for vCluster platform

apiKey required object pro​

APIKey defines where to find the platform access key and host. By default, vCluster will search in the following locations in this precedence:

  • platform.api.accessKey
  • environment variable called LICENSE
  • secret specified under external.platform.apiKey.secretName
  • secret called "vcluster-platform-api-key" in the vCluster namespace
secretName required string pro​

SecretName is the name of the secret where the platform access key is stored. This defaults to vcluster-platform-api-key if undefined.

namespace required string pro​

Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace.

createRBAC required boolean false pro​

CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified in the above namespace, if specified. This defaults to true.

autoSleep required object pro​

AutoSleep holds configuration for automatic sleep and wakeup

afterInactivity required integer pro​

AfterInactivity specifies after how many seconds of inactivity the virtual cluster should sleep

schedule required string pro​

Schedule specifies scheduled virtual cluster sleep in Cron format, see https://en.wikipedia.org/wiki/Cron. Note: timezone defined in the schedule string will be ignored. Use ".Timezone" field instead.

timezone required string pro​

Timezone specifies time zone used for scheduled virtual cluster operations. Defaults to UTC. Accepts the same format as time.LoadLocation() in Go (https://pkg.go.dev/time#LoadLocation). The value should be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York".

autoWakeup required object pro​

AutoSleep holds configuration for automatic wakeup

schedule required string pro​

Schedule specifies scheduled wakeup from sleep in Cron format, see https://en.wikipedia.org/wiki/Cron. Note: timezone defined in the schedule string will be ignored. The timezone for the autoSleep schedule will be used

autoDelete required object pro​

AutoDelete holds configuration for automatic delete

afterInactivity required integer pro​

AfterInactivity specifies after how many seconds of inactivity the virtual cluster be deleted