Templates & variables¶
CAPVCO ships eight clusterctl templates. You render one with
clusterctl generate cluster <name> --kubernetes-version <ver> --infrastructure vco --flavor <flavor>
— clusterctl fetches the template from the installed provider's release, so no
clone is needed. Set the other variables as environment variables. The default (no --flavor) is
the base cluster-template.yaml; contributors working from a checkout can instead use
--from ./templates/<file>.
This page is the exhaustive variable reference. For the objects each template contains, see the per-template catalog at the end.
Substitution syntax¶
Templates use clusterctl's substitution: ${VAR} (must be supplied) and ${VAR:=default} (uses
the default if unset). Every defaultable variable below uses :=.
Variables you must always supply¶
| Variable | In | Meaning |
|---|---|---|
CLUSTER_NAME |
all | Name of every object; base for derived Secret names and SANs. |
KUBERNETES_VERSION |
all | Control-plane + worker Kubernetes version. |
VCO_LOCATION |
base, prebaked, ccm, backup, airgapped | Backend datacenter/location code. Location code — no default. |
VCO_IMAGE_ID |
base, prebaked, ccm, backup, airgapped | vm-image id to boot. Location-specific — no default, so a wrong id can't silently boot the wrong image. |
GEO_SITE1_LOCATION / GEO_SITE2_LOCATION / GEO_SITE3_LOCATION |
geo | Each site's location. Same location on all three = one-location geo; distinct = stretched across datacenters. Location codes — no default. |
GEO_SITE1_IMAGE_ID / GEO_SITE2_IMAGE_ID / GEO_SITE3_IMAGE_ID |
geo | Pre-baked image id in each site's location. Location-specific — no default. Sites sharing a location share an id. |
GEO_SITE1_EXTNET_ID / GEO_SITE2_EXTNET_ID / GEO_SITE3_EXTNET_ID |
geo | Routable external-network id in each site's location. Instance-specific — no default. |
VCO_REGISTRY_IMAGE_ID |
airgapped | Stock image id for the in-cloudspace registry VM. Location-specific — no default. |
GEO_DNS_ZONE |
geo | Managed DNS zone for the control-plane endpoint SANs. |
VCO_BACKUP_S3_BUCKET |
backup | Target S3 bucket (must be pre-created with Object Lock + versioning). |
VCO_REGISTRY_DOMAIN |
airgapped | The in-cloudspace registry's DNS name. |
vm-image ids and location codes are not portable
Image ids and location codes are specific to one whitesky.cloud instance/location — an id or
code from our examples won't exist on your instance. Every image-id and location variable above is
required with no default, so rendering fails loudly (value for variables [VCO_IMAGE_ID] is not
set) instead of pointing at a foreign image. Find the right ids in your whitesky.cloud portal (or
the VCO API) per location; see pre-baked images.
Worker count is a clusterctl flag, not a template default
clusterctl generate cluster injects WORKER_MACHINE_COUNT from its --worker-machine-count
flag, which defaults to 0 — so omitting the flag yields zero workers, regardless of the
template's :=1. Pass --worker-machine-count <n> explicitly. (Setting WORKER_MACHINE_COUNT as
an env var has no effect — clusterctl's flag value overrides it.)
Also required out-of-band (not template variables): the credential Secret (jwt +
customer_id) that credentialSecretRef points at; for backup, the S3 credentials Secret; for
airgapped, the operator credential Secret and a pre-registered TLS cert.
Common variables (most templates)¶
| Variable | Default | Configures |
|---|---|---|
NAMESPACE |
default |
Namespace of every object. |
POD_CIDR |
10.244.0.0/16 |
Cluster.spec.clusterNetwork.pods. Must not overlap the cloudspace LAN. |
SERVICE_CIDR |
10.96.0.0/12 |
Cluster.spec.clusterNetwork.services. |
VCO_CREDENTIAL_SECRET |
${CLUSTER_NAME}-vco-credential |
VCOCluster.spec.credentialSecretRef. |
CONTROL_PLANE_MACHINE_COUNT |
1 (geo: 3) |
Control-plane replicas. Use ≥ 3 for HA. |
WORKER_MACHINE_COUNT |
--worker-machine-count flag (default 0) |
Worker replicas. clusterctl's flag overrides the template's :=1, so pass --worker-machine-count <n> explicitly or get zero workers. base/prebaked/ccm/backup; geo pins 1/site; airgapped has none. |
WORKER_MIN_COUNT / WORKER_MAX_COUNT |
1 / 3 |
autoscaling only. The cluster-autoscaler floor and ceiling for the worker pool, stamped as node-group annotations on the MachineDeployment. WORKER_MAX_COUNT is the cost cap. WORKER_MACHINE_COUNT (and --worker-machine-count) do nothing on that flavour — it declares no replicas, because the autoscaler owns that field. See Autoscaling. |
VCO_CP_VCPUS / VCO_CP_MEMORY_MIB |
2 / 4096 |
Control-plane VM size. |
VCO_CP_BOOT_DISK_GIB |
40 |
Control-plane boot disk (keep ≥ 40 for pre-baked images). |
VCO_MD_VCPUS / VCO_MD_MEMORY_MIB |
2 / 4096 |
Worker VM size. |
VCO_MD_BOOT_DISK_GIB |
40 |
Worker boot disk. |
CP_CERT_ROLLOUT_DAYS |
90 |
Auto-rotate control-plane PKI this many days before expiry (all except airgapped). |
POD_CIDR is coupled to the CNI add-on
The CNI is delivered by a ClusterResourceSet
whose Calico pool is pinned to the default POD_CIDR (10.244.0.0/16). If you override POD_CIDR,
the CNI bundle's pool must match — otherwise pods get addresses from the wrong range. Change both
together, or leave POD_CIDR at its default.
MachineHealthCheck variables (base, prebaked)¶
| Variable | Default | Configures |
|---|---|---|
MHC_WORKER_STARTUP_SECONDS |
900 |
Worker node-startup timeout. |
MHC_WORKER_MAX_UNHEALTHY |
40% |
Worker remediation circuit-breaker. |
MHC_CP_STARTUP_SECONDS |
1200 |
Control-plane node-startup timeout. |
MHC_CP_MAX_UNHEALTHY |
40% |
Control-plane remediation circuit-breaker. |
Physical etcd disk (base — commented block)¶
| Variable | Default | Configures |
|---|---|---|
VCO_CP_ETCD_DISK_GIB |
20 |
Size of the dedicated /var/lib/etcd disk. Uncomment the block to enable. See Node disks. |
Geo variables (geo)¶
The template declares three sites (site-1/site-2/site-3, positional). Each site takes three
location-scoped values with no default; same location on every site = an all-in-one-location geo
cluster, distinct locations = stretched across datacenters. Adding a 4th+ site is documented in the
template header.
| Variable | Default | Configures |
|---|---|---|
GEO_SITE1_LOCATION / GEO_SITE2_LOCATION / GEO_SITE3_LOCATION |
— (required) | Each site's location; GEO_SITE1_LOCATION is also the primary/endpoint seed (spec.location). |
GEO_SITE1_IMAGE_ID / GEO_SITE2_IMAGE_ID / GEO_SITE3_IMAGE_ID |
— (required) | Pre-baked image id in each site's location (spec.geo.locationImages). |
GEO_SITE1_EXTNET_ID / GEO_SITE2_EXTNET_ID / GEO_SITE3_EXTNET_ID |
— (required) | Routable external network in each site's location (spec.geo.locationExternalNetworks). |
GEO_DNS_ZONE |
— (required) | Managed zone for the endpoint + per-site SANs. |
ETCD_PLACEMENT |
distributed |
distributed (CP-per-site) or concentrated (CP-in-primary). |
ETCD_HEARTBEAT_MS |
250 |
etcd --heartbeat-interval (WAN-tuned). |
ETCD_ELECTION_MS |
2500 |
etcd --election-timeout. |
Backup variables (backup)¶
| Variable | Default | Configures |
|---|---|---|
VCO_BACKUP_S3_ENDPOINT |
"" (AWS) |
backup.s3.endpoint. |
VCO_BACKUP_S3_REGION |
us-east-1 |
backup.s3.region. |
VCO_BACKUP_S3_BUCKET |
— | backup.s3.bucket. |
VCO_BACKUP_S3_PREFIX |
clusters |
backup.s3.prefix. |
VCO_BACKUP_S3_PATH_STYLE |
true |
backup.s3.forcePathStyle. |
VCO_BACKUP_S3_SECRET |
${CLUSTER_NAME}-backup-s3 |
backup.s3.credentialsSecretRef. |
VCO_BACKUP_SCHEDULE |
0 * * * * |
backup.schedule. |
VCO_BACKUP_KEEP_HOURLY |
24 |
backup.retention.hourly. |
VCO_BACKUP_KEEP_DAILY |
7 |
backup.retention.daily. |
VCO_BACKUP_KEEP_WEEKLY |
4 |
backup.retention.weekly. |
VCO_BACKUP_KEEP_MONTHLY |
6 |
backup.retention.monthly. |
VCO_BACKUP_LOCK |
true |
backup.objectLock.enabled. |
VCO_BACKUP_LOCK_MODE |
compliance |
backup.objectLock.mode. |
VCO_BACKUP_AGE_RECIPIENT |
"" |
backup.encryption.recipient (empty → controller generates + escrows). |
Registry / air-gapped variables (airgapped)¶
| Variable | Default | Configures |
|---|---|---|
VCO_REGISTRY_DOMAIN |
— | registry.domain. |
VCO_REGISTRY_CERT_SOURCE |
CERTIFICATE_STORE |
registry.certSource. |
VCO_REGISTRY_CERT_SECRET |
${CLUSTER_NAME}-operator |
registry.certCredentialSecretRef (operator credential). |
VCO_REGISTRY_IMAGE_ID |
— (required) | registry.imageId (stock image id, location-specific). |
VCO_REGISTRY_SEEDED |
false |
registry.seeded. |
VCO_REGISTRY_PORT |
5000 |
registry.port. |
VCO_CNI |
calico |
Value of the …/cni label (airgapped parameterizes it). |
VCO_CSI |
vco |
Value of the …/csi label. |
External-network variables¶
| Variable | Default | Template | Configures |
|---|---|---|---|
VCO_EXTNET_ID |
1 |
ccm, backup, airgapped | VCOCluster.spec.cloudspace.externalNetworkId. |
Template catalog¶
What each template produces and adds. All set controlPlaneExposure: loadbalancer.
cluster-template.yaml — base¶
The canonical stock-image cluster: Cluster, VCOCluster, control-plane + worker
VCOMachineTemplate, KubeadmControlPlane, worker KubeadmConfigTemplate + MachineDeployment,
and two MachineHealthChecks (worker + control plane). Installs containerd + Kubernetes on first
boot. Labels: cni: calico, csi: vco (and a commented service-lb: vco).
cluster-template-prebaked.yaml¶
Same topology as base but boots a pre-baked image (no on-boot install) and includes the
local-apiserver postKubeadmCommands fix for the control-plane upgrade skew deadlock. VCO_IMAGE_ID
has no default. Labels: cni: calico, csi: vco.
cluster-template-ccm.yaml¶
Single control plane + one worker, pre-baked, for the cloud-controller-manager path. Kubelets get
--cloud-provider=external; nodes come up tainted and the CCM clears them. No MHCs. Labels:
cni: calico, ccm: enabled (no csi, no service-lb).
cluster-template-backup.yaml¶
Single control plane + one worker, pre-baked, plus the full spec.backup subtree (S3, schedule, GFS
retention, Object Lock, age encryption). No MHCs. Label: cni: calico.
cluster-template-airgapped.yaml¶
The thinnest template: control-plane only (no workers/MHCs/cert-rollout), plus the
spec.registry subtree for the in-cloudspace registry. Only template that parameterizes the CNI/CSI
label values. Labels: cni: ${VCO_CNI}, csi: ${VCO_CSI}.
cluster-template-geo.yaml¶
Geo-redundant: three sites (site-1/site-2/site-3), one cloudspace each, meshed over S2S VPN,
one control plane per site over a single stretched etcd. Pre-baked. Each site takes its own
GEO_SITEn_LOCATION / _IMAGE_ID / _EXTNET_ID — same location on every site for an
all-in-one-location cluster, distinct locations to stretch across datacenters (same shape either way).
Three per-site worker pools pinned by failure domain. Adds spec.geo (locations,
locationImages, locationExternalNetworks) + WAN-tuned etcd args, apiserver certSANs, and the
apiserver-proxy setup. CP replicas default 3 (one per site). Labels: cni: calico,
csi: vco, apiserver-proxy: enabled.
cluster-template-gpu.yaml¶
Base topology plus spec.gpu on the worker VCOMachineTemplate (GPUs requested by type, not by
instance id) and bootType on both machine templates. Boots the stock-image path and installs the
NVIDIA driver on first boot via VCO_GPU_DRIVER_VERSION. Needs a GPU-ready image — see
GPUs. Labels: cni: calico, csi: vco, gpu: nvidia.
cluster-template-autoscaling.yaml¶
The base template with an autoscalable worker pool: the MachineDeployment carries the
cluster-autoscaler node-group-min-size / node-group-max-size annotations and declares no
replicas, so the autoscaler owns the pool size and a re-apply cannot fight it. Inert on its own —
it needs a cluster-autoscaler deployed against the management cluster
(CLUSTER_NAME=<c> make autoscaler). Labels as base. See Autoscaling.
The field-by-field CRD truth is the CRD API reference; the manager/credential/label model is in Configuration.