Skip to main content
Version: v0.38 Stable

Configure

This section covers vcluster.yaml, the file that configures a cluster. It decides how the control plane runs, where workloads run, which resources sync with the control plane cluster, and how users and tools connect. You pass the file when you deploy a cluster, and you deploy config changes to update a running one.

The file is optional. Without one, a cluster runs on shared nodes from the control plane cluster's node pool, with its resources syncing to a single namespace there. To give the cluster dedicated worker nodes instead, configure private nodes.

Shared nodes are for trusted tenants

Shared nodes are a supported, common model for trusted tenants. They give each tenant control-plane, API, and namespace isolation, but tenant workloads share the same kernel and physical nodes. They aren't a security boundary for untrusted tenants with Kubernetes access or arbitrary workload execution. Good fits are development, testing, CI/CD, and internal engineering teams.

Use private nodes for external, resale, regulated, or otherwise untrusted tenant offerings, optionally with vNode for runtime isolation.

NetworkPolicy is an added isolation layer worth enabling even for trusted tenants. vCluster can create the policies for you through policies.networkPolicy, and your control plane cluster's CNI enforces them. Confirm your CNI supports enforcement, since some accept NetworkPolicy resources without acting on them. See the security baseline.

If you accept shared nodes for a trusted-tenant use case, follow the shared-node hardening guide as the required next step.

How the file is organized​

The file is grouped by top-level key, and each Configure category covers one area of it. controlPlane decides how the API server, backing store, and CoreDNS run and how the control plane is exposed. privateNodes turns on dedicated worker nodes. sync chooses which resources move between the cluster and the control plane cluster, in both directions. networking and policies govern traffic, quotas, and admission. Other keys cover access, lifecycle, add-ons, logging, and experimental features.

For how the sections fit together, with example files for shared nodes, private nodes, and vCluster Standalone, see What is vcluster.yaml?. To look up one field, its type, and its default, use the generated vcluster.yaml reference.

Settings you choose at creation​

Most settings can change on a running cluster. Some can't, so decide them in the first vcluster.yaml you deploy with. The two that matter for most clusters are the worker node model and the backing store.

A cluster that starts on shared nodes can't move to private nodes later. For the backing store, changing its type by editing the configuration in place isn't supported, apart from a few documented migrations. To weigh these choices for production, start with Plan your cluster.

Work in this section​

Each category below holds the pages for one area of the file. Every page shows how to set up one capability and links to the fields it uses.

The Access, Lifecycle, Add-ons and plugins, and Logging and telemetry cards open the first page in their category. Their other pages are Export kubeconfig, Configure deletion, Configure auto snapshots, Plugins, and Telemetry.

To connect a cluster to external tools such as cert-manager or External Secrets, see Integrate and automate.