Skip to content

API Reference

Packages

infrastructure.cluster.x-k8s.io/v1alpha1

Package v1alpha1 contains the API types for the CAPVCO infrastructure provider (VCOCluster / VCOMachine and their templates).

Resource Types

Architecture

Underlying type: string

Architecture is the CPU architecture a node built from this template runs.

Validation: - Enum: [amd64 arm64]

Appears in: - NodeInfo

Field Description
amd64 ArchitectureAmd64 is the only architecture whitesky.cloud currently offers.
arm64 ArchitectureArm64 exists so the field can express arm64 if the platform
ever offers it; nothing sets it today.

BackupEncryptionMode

Underlying type: string

BackupEncryptionMode selects the client-side encryption scheme.

Validation: - Enum: [age]

Appears in: - BackupEncryptionSpec

Field Description
age

BackupEncryptionSpec

BackupEncryptionSpec configures client-side encryption. Default: age, with a provider-generated keypair whose identity is stored (and must be escrowed) in the management cluster. Set Recipient to bring your own key — then CAPVCO never holds a private key at all (the recommended posture).

Appears in: - BackupSpec

Field Description Default Validation
mode BackupEncryptionMode Mode is the encryption scheme. age Enum: [age]
Optional: {}
recipient string Recipient is a BYO age public recipient (age1...). When set, CAPVCO
encrypts to it and never generates or stores a private key; the operator
owns the identity. When empty, CAPVCO generates + escrows the keypair.		 Optional: {}

BackupSpec

BackupSpec configures scheduled etcd snapshot backups (§27.1). The bucket is BYO — the operator pre-creates it with Object Lock + versioning enabled; CAPVCO only writes/lists/deletes and validates the lock configuration.

Appears in: - VCOClusterSpec

Field Description Default Validation
s3 S3StorageSpec S3 is the target bucket + credentials.
schedule string Schedule is the cron schedule at the finest (hourly) tier cadence. The GFS
tier a given snapshot is promoted to is decided at upload time.		 0 * * * * Optional: {}
retention RetentionSpec Retention is the grandfather-father-son keep-count per tier. A zero count
disables that tier.		 Optional: {}
objectLock ObjectLockSpec ObjectLock configures S3 Object-Lock WORM protection for uploaded
snapshots. When enabled the bucket MUST have Object Lock enabled (checked
at reconcile); each snapshot is written with a retain-until equal to the
longest retention tier it qualifies for.		 Optional: {}
encryption BackupEncryptionSpec Encryption configures client-side snapshot encryption (etcd holds every
cluster Secret, so plaintext must never reach S3).		 Optional: {}

BackupStatus

BackupStatus reports observed etcd-backup state.

Appears in: - VCOClusterStatus

Field Description Default Validation
lastSnapshotTime Time LastSnapshotTime is when the most recent snapshot was observed uploaded. Optional: {}
lastSnapshotKey string LastSnapshotKey is the S3 key of the most recent snapshot. Optional: {}
ageRecipient string AgeRecipient is the age public recipient snapshots are encrypted to
(mirrors spec, or the provider-generated recipient when BYO is not used).		 Optional: {}

CertSource

Underlying type: string

CertSource selects how the registry TLS certificate is sourced from whitesky.cloud (§26).

Validation: - Enum: [CERTIFICATE_STORE LETS_ENCRYPT]

Appears in: - RegistrySpec

Field Description
CERTIFICATE_STORE CertSourceStore = operator-uploaded cert in whitesky.cloud's store (air-gap friendly).
LETS_ENCRYPT CertSourceLetsEncrypt = whitesky.cloud-managed Let's Encrypt (needs public reachability).

CloudspaceQuotas

CloudspaceQuotas caps the cloudspace's resource usage. Zero means unset (the backend default applies).

Appears in: - CloudspaceSpec

Field Description Default Validation
vcpu integer VCPU caps total virtual CPUs. Optional: {}
memoryMiB integer MemoryMiB caps total memory in MiB. Optional: {}
diskGiB integer DiskGiB caps total disk in GiB. Optional: {}
publicIp integer PublicIP caps the number of public IPs. Optional: {}

CloudspaceSpec

CloudspaceSpec configures the backing cloudspace (one per cluster).

Appears in: - VCOClusterSpec

Field Description Default Validation
privateNetwork string PrivateNetwork is an optional CIDR for the cloudspace private network. It
MUST NOT overlap the workload cluster's pod/service CIDRs (plan §4).		 Optional: {}
quotas CloudspaceQuotas Quotas optionally caps cloudspace resource usage. Optional: {}
private boolean Private, when true, creates the cloudspace with no external network. This
removes node internet egress and a public control-plane endpoint; requires
pre-baked images and an in-cloudspace registry/NAT (plan §4).		 Optional: {}
externalNetworkId integer ExternalNetworkID optionally selects a specific external network; when
unset the default external network is used.		 Optional: {}

CloudspaceStatus

CloudspaceStatus records one backing cloudspace of a (possibly geo) cluster.

Appears in: - VCOClusterStatus

Field Description Default Validation
name string Name is the site's unique key — its CAPI failure-domain name and the
suffix of its cloudspace name. Positional and 1-based: "site-1", "site-2", …
matching the per-site DNS names (-site-N.), independent of how
cloudspaces map to locations. Empty for a non-geo cluster.		 Optional: {}
location string Location is the backend location code this cloudspace sits in.
cloudspaceId string CloudspaceID is the backend cloudspace id.
privateNetwork string PrivateNetwork is the cloudspace's private CIDR (must be unique across the
cluster's cloudspaces and disjoint from the pod/service CIDRs).		 Optional: {}
publicIp string PublicIP is this cloudspace's external-network IP (mesh endpoint +, for the
primary, the control-plane endpoint).		 Optional: {}
primary boolean Primary marks the cloudspace that hosts the control-plane endpoint. Optional: {}

ControlPlaneExposure

Underlying type: string

ControlPlaneExposure selects how the control-plane endpoint is published.

Validation: - Enum: [loadbalancer portforward]

Appears in: - VCOClusterSpec

Field Description
loadbalancer ExposureLoadBalancer publishes :6443 via an L4 load balancer whose public
frontend IP comes from the cloudspace external network. HA-capable; the
default.
portforward ExposurePortforward publishes :6443 via a portforward to the sole
control-plane VM. Documented fallback for single-CP minimal setups.

CredentialScope

Underlying type: string

CredentialScope selects how the per-cluster CSI service account is scoped. The location grant is broad (spans every cloudspace in the location) but is the only scope under which the bundled CSI driver's location-scoped disk-create currently succeeds; cloudspace/perDisk depend on a platform-side capability that is still being decided (plan §12.1). Kept pluggable so the chosen direction drops in without controller rework.

Validation: - Enum: [location perDisk cloudspace]

Appears in: - StorageSpec

Field Description
location CredentialScopeLocation grants the CSI SA at the location level.
perDisk CredentialScopePerDisk grants the CSI SA per-disk (requires platform support).
cloudspace CredentialScopeCloudspace grants the CSI SA at the cloudspace level
(requires a platform-side cloudspace-scoped disk-create capability).

DiskGrowthPolicySpec

DiskGrowthPolicySpec configures automatic node disk expansion (§23, M9). When a monitored filesystem's usage crosses ThresholdPercent (or the node reports DiskPressure), the controller grows the backing vDisk by IncrementGiB up to the per-disk cap, and the in-node growfs unit extends the partition + fs.

Appears in: - VCOMachineSpec

Field Description Default Validation
enabled boolean Enabled turns on automatic disk expansion for this machine.
thresholdPercent integer ThresholdPercent is the filesystem-usage percentage at or above which the
controller grows the disk (DiskPressure is always a hard backstop).		 80 Maximum: 99
Minimum: 1
Optional: {}
incrementGiB integer IncrementGiB is how much to grow a disk by, per expansion step. 10 Minimum: 1
Optional: {}
maxBootDiskGiB integer MaxBootDiskGiB caps the boot disk size; 0 disables boot-disk growth. Optional: {}
maxEtcdDiskGiB integer MaxEtcdDiskGiB caps the M7 etcd disk size; 0 disables etcd-disk growth. Optional: {}

DriftMode

Underlying type: string

DriftMode selects how aggressively drift is acted on (§27.5). Default-safe.

Validation: - Enum: [Report Reconcile GC]

Appears in: - DriftPolicy

Field Description
Report DriftReport only detects + surfaces drift/orphans (condition + metric +
events); it never changes the backend. The safe default.
Reconcile DriftReconcile additionally re-creates/repairs drifted resources the cluster
still needs. (Detection + reporting today; repair is incremental.)
GC DriftGC additionally DELETES detected orphans (resources whose owning object
is gone), subject to Resources opt-in and DryRun.

DriftPolicy

DriftPolicy configures drift detection + orphan GC.

Appears in: - VCOClusterSpec

Field Description Default Validation
mode DriftMode Mode selects the action level. Report Enum: [Report Reconcile GC]
Optional: {}
dryRun boolean DryRun logs what GC/Reconcile WOULD do without touching the backend. A
safety net for first enabling a destructive mode.		 Optional: {}
resources string array Resources opt-in per resource type for destructive GC (e.g. "vms",
"portforwards"). Empty = GC nothing (report only), so destructive action is
always narrow and deliberate even in GC mode.		 Optional: {}

EncryptionSpec

EncryptionSpec configures disk-encryption key material.

Appears in: - StorageSpec

Field Description Default Validation
vault VaultMode Vault selects the key vault mode. none Enum: [none external managed]
Optional: {}
external ExternalVaultSpec External configures the external Vault when Vault=external. Optional: {}

EtcdDiskSpec

EtcdDiskSpec requests a dedicated disk for etcd data (plan §21).

Appears in: - VCOMachineSpec

Field Description Default Validation
sizeGiB integer SizeGiB is the disk size in GiB. Minimum: 1
type EtcdDiskType Type selects the backend disk class. Defaults to physical. physical Enum: [physical data]
Optional: {}

EtcdDiskType

Underlying type: string

EtcdDiskType selects the backend disk class for the dedicated etcd disk.

Validation: - Enum: [physical data]

Appears in: - EtcdDiskSpec

Field Description
physical EtcdDiskPhysical uses a location-scoped PHYSICAL ("P") disk backed by
low-latency local storage — the point of the feature (plan §21).
data EtcdDiskData uses a software-defined DATA disk. Fallback for locations
without spare PHYSICAL capacity (keeps etcd on a dedicated volume even if
not on local storage).

EtcdPlacement

Underlying type: string

EtcdPlacement selects how etcd is distributed across a geo cluster's cloudspaces (plan §22). distributed = stacked etcd on every site (survives a location outage, default); concentrated = etcd only in the primary location.

Validation: - Enum: [distributed concentrated]

Appears in: - GeoSpec

Field Description
distributed
concentrated

ExternalVaultSpec

ExternalVaultSpec configures an external HashiCorp Vault transit engine for disk encryption keys.

Appears in: - EncryptionSpec

Field Description Default Validation
address string
transitMount string
k8sAuthPath string
role string
caRef LocalObjectReference CARef references a ConfigMap/Secret holding the Vault CA bundle. Optional: {}

GPUSpec

GPUSpec requests GPU(s) for a machine by type (#34).

The backend reserves NAMED vGPU instances out of a GPU profile, and a reservation is billed whether or not it is attached — so the controller owns the whole lifecycle (resolve -> reserve -> attach at VM create -> release on delete) and nothing instance-shaped appears here.

Appears in: - VCOMachineSpec

Field Description Default Validation
type string Type names the GPU to attach as " " (e.g. "NVIDIA A100"),
matched case- and space-insensitively against what the machine's location
offers. A type that is absent, exhausted, or ambiguous fails loudly and
lists the available types — it never silently falls back.
Exactly one of Type or ProfileID must be set, and the controller REJECTS a
spec that sets both (GPUSpecAmbiguous) rather than picking one: they answer
different questions, so with both set it would not be visible which decided
the GPU.		 Optional: {}
profileId string ProfileID pins the backend GPU profile id directly, for the case where two
profiles share a vendor+model and Type would be ambiguous.		 Optional: {}
count integer Count is how many GPUs of this type to attach to each machine. 1 Minimum: 1
Optional: {}
driverVersion string DriverVersion installs the NVIDIA guest driver on first boot, together with
the container toolkit and the containerd nvidia runtime — the GPU
equivalent of the stock-image kubelet install. The value is the Ubuntu
driver-branch number, e.g. "550" or "570"; which branch is correct depends
on the vGPU profile the platform hands out, so it is configuration rather
than something the provider can infer.
It is a branch REQUEST, not a pin. Ubuntu keeps a retired branch's
metapackage as a TRANSITIONAL package depending on the supported one, so
asking for a retired branch silently installs a newer one. On Ubuntu 24.04
(checked 2026-09) every branch but the newest forwards:
nvidia-driver-535-server -> 580
nvidia-driver-550-server -> 570 -> 580
nvidia-driver-570-server -> 580
nvidia-driver-580-server -> the actual driver
so any value currently resolves to 580 there. The boot logs the branch that
actually loaded whenever it differs from the request. To hold a specific
branch, bake it into an image instead.
Leave EMPTY for a pre-baked GPU image (the recommended path, and the only
one that works air-gapped — the install pulls from Ubuntu's archive and
NVIDIA's apt repo). A GPU attached to a node with neither a baked driver
nor this field set will not be usable by pods.
Digits only, and validated: this value is interpolated into a shell script
that cloud-init runs as ROOT on first boot, so anything else would be
command injection through a cluster manifest. The manager re-checks it
(see controllers) because a cluster may still carry an older CRD.
The pattern also accepts the EMPTY string, because that is how a template
expresses "no driver install" — cluster-template-gpu.yaml renders
driverVersion: "" by default, and a digits-only pattern made the API
server reject every GPU cluster that did not want a driver.		 Pattern: ^([0-9]\{2,4\})?$
Optional: {}

GPUStatus

GPUStatus records one reserved vGPU instance backing a machine.

Appears in: - VCOMachineStatus

Field Description Default Validation
vgpuId string VGPUID is the backend reservation id — the handle needed to release it.
name string Name is the deterministic reservation name the controller minted
(capvco---gpu-), so a reservation can be traced to its
owner and re-found after a lost response instead of leaking.		 Optional: {}
profileId string ProfileID and Model record which GPU type this instance came from, so the
resolved type is visible without re-querying the backend.		 Optional: {}
model string Optional: {}
attached boolean Attached reports whether the reservation currently sits on the VM. Optional: {}

GeoSpec

GeoSpec makes a cluster geo-redundant: the controller creates one cloudspace per location, meshes them into one routed L3 network via connected-cloudspaces (S2S VPN), and exposes one CAPI failure domain per location so machines spread across sites (plan §22, M8). When nil the cluster is single-cloudspace (the spec.location behaviour of M1–M7).

Appears in: - VCOClusterSpec

Field Description Default Validation
locations string array Locations lists the backend locations, one cloudspace each (>=2 for geo).
spec.location is treated as the primary location and must appear here.		 MinItems: 2
privateNetworks string array PrivateNetworks optionally sets each cloudspace's private CIDR, positional
with Locations. They MUST be mutually non-overlapping and disjoint from the
pod/service CIDRs (§17, now across all sites). If unset, the controller
auto-assigns disjoint /24s.		 Optional: {}
etcdPlacement EtcdPlacement EtcdPlacement selects distributed (default) vs concentrated etcd. Wired in
M8b; recorded here so the geo spec is stable.		 distributed Enum: [distributed concentrated]
Optional: {}
locationImages LocationImage array LocationImages maps a location code to the vm-image id to use there. VM
images are location-scoped and NOT portable across locations, so a geo
cluster whose sites span distinct locations needs a per-location image id —
a single VCOMachineTemplate.imageId cannot be valid in every location. When
a machine's location has an entry here, the machine controller uses this
image id instead of the VCOMachine's spec.imageId; the spec.imageId remains
the fallback for locations not listed (and when every site shares one
location, where a single id is valid everywhere). Ignored for non-geo
clusters. (§22 M8.)		 Optional: {}
locationExternalNetworks LocationExternalNetwork array LocationExternalNetworks optionally pins each location's cloudspaces to a
specific external network (they are location-scoped; see
LocationExternalNetwork). Unlisted locations fall back to
spec.cloudspace.externalNetworkId, else the backend default.		 Optional: {}
images VersionImage array Images resolves vm-image ids per Kubernetes version (§27.2, M11). VM
images are version-pinned AND location-scoped, so an upgrade means "new
image + rolling replace". For the cluster's current version, the machine
controller resolves each location's image id from the matching entry here
(preferred over the version-agnostic LocationImages): either a pinned
per-location override, or — if a Source is given — the controller publishes
the image to that location on demand (presign the S3 object → whitesky.cloud
import-from-URL → poll → record the id in status.images). Idempotent.		 Optional: {}
imagePublishCredentialSecretRef string ImagePublishCredentialSecretRef optionally names a Secret (same shape as
spec.credentialSecretRef: jwt, customer_id, optional portal_url/
iam_refresh_url) holding an OPERATOR credential with vm-image-create
rights, used only for publishing image Sources (§27.2). Publishing images
is a platform-operator privilege the per-cluster customer credential
generally lacks, so it is supplied separately here. When unset, the
cluster credential is used (fine for the LocationImageIds override path,
which needs no image-create rights).		 Optional: {}

ImageSource

ImageSource describes a vm-image artifact in S3 plus the metadata the whitesky.cloud import-from-URL API requires.

Appears in: - VersionImage

Field Description Default Validation
s3 S3ObjectRef S3 addresses the image object (the controller presigns a read URL for the
whitesky.cloud import call). CredentialsSecretRef keys: accessKeyID, secretAccessKey.
bootType string BootType is the image boot type (e.g. "bios" or "uefi"). MinLength: 1
osName string OSName is the specific OS name the backend expects (e.g. "ubuntu"). MinLength: 1
osType string OSType is the OS family (e.g. "Linux"). MinLength: 1
memoryMiB integer MemoryMiB is the image's minimum required memory. Minimum: 1
bootDiskGiB integer BootDiskGiB is the image's minimum boot-disk size. Minimum: 1
md5 string MD5 optionally verifies the downloaded artifact. Optional: {}

LocationExternalNetwork

LocationExternalNetworks maps a location to the external-network id its cloudspaces should attach to. External networks are location-scoped, and a location may expose several (only some routable), so a multi-location geo cluster needs a per-location choice — a single spec.cloudspace.externalNetworkId cannot be valid across locations. When a site's location has an entry here, its cloudspace is created on that external network; otherwise the backend picks one (fine when a location has a single external network). The PRIMARY site's external network hosts the control-plane endpoint, so it must be reachable from the management cluster. (§22 M8.)

Appears in: - GeoSpec

Field Description Default Validation
location string Location is the backend location code (must be one of GeoSpec.Locations). MinLength: 1
externalNetworkId integer ExternalNetworkID is the external-network id valid in that location. Minimum: 1

LocationImage

LocationImage pins the vm-image id to use in a given location (see GeoSpec.LocationImages).

Appears in: - GeoSpec - RegistrySpec - VersionImage - VersionImageStatus

Field Description Default Validation
location string Location is the backend location code (must be one of GeoSpec.Locations). MinLength: 1
imageId integer ImageID is the vm-image id valid in that location. Minimum: 1

NodeInfo

NodeInfo describes the node a machine from this template becomes, for the cluster autoscaler's scale-from-zero simulation (CAPI InfraMachineTemplate contract). Without it the autoscaler falls back to its own defaults.

Validation: - MinProperties: 1

Appears in: - VCOMachineTemplateStatus

Field Description Default Validation
architecture Architecture Architecture is the node's CPU architecture. Enum: [amd64 arm64]
Optional: {}
operatingSystem string OperatingSystem is the node's OS ("linux"). Optional: {}

ObjectLockMode

Underlying type: string

ObjectLockMode selects the S3 Object-Lock retention mode.

Validation: - Enum: [compliance governance]

Appears in: - ObjectLockSpec

Field Description
compliance ObjectLockCompliance cannot be shortened or bypassed by anyone, including
the account root — WORM/ransomware-grade.
governance ObjectLockGovernance allows privileged bypass — the weaker alternative.

ObjectLockSpec

ObjectLockSpec configures WORM protection.

Appears in: - BackupSpec

Field Description Default Validation
enabled boolean Enabled turns on per-object retain-until on uploaded snapshots. Optional: {}
mode ObjectLockMode Mode is the Object-Lock retention mode. compliance Enum: [compliance governance]
Optional: {}

RegistrySpec

RegistrySpec configures the per-cloudspace image registry that serves every container image locally for air-gapped clusters (§26, M12).

Appears in: - VCOClusterSpec

Field Description Default Validation
locationImages LocationImage array LocationImages pins the pre-baked registry vm-image id per location (images
are location-scoped; same shape as GeoSpec.LocationImages). For a single
location, ImageID is the simpler alternative.		 Optional: {}
imageId integer ImageID is the registry vm-image id when all cloudspaces share a location
(or a stock image + cloud-init for dev). Overridden per-location by
LocationImages.		 Optional: {}
seeded boolean Seeded declares that the registry vm-image is a PRE-SEEDED zero-egress
image (§26): it already carries the registry binary, a systemd unit, and
a /var/lib/capvco-registry store pre-populated with every image the cluster
needs. The provider then only writes the TLS cert and (re)starts the baked
service — it does NOT install docker or configure a pull-through upstream,
so the registry serves purely from its local store with no internet egress.
When false (default), the registry runs as a docker registry:2
pull-through cache seeded on demand from the upstreams (needs egress).		 Optional: {}
domain string Domain is the registry's DNS name — used for its TLS certificate (fetched
from whitesky.cloud's SSL-certificate API) and the node containerd mirror config.		 MinLength: 1
certSource CertSource CertSource selects how the registry's TLS cert is obtained from whitesky.cloud. CERTIFICATE_STORE Enum: [CERTIFICATE_STORE LETS_ENCRYPT]
Optional: {}
certCredentialSecretRef string CertCredentialSecretRef optionally names an OPERATOR credential (same shape
as spec.credentialSecretRef) with access to whitesky.cloud's SSL-certificate store —
which the per-cluster customer credential lacks (403, like vm-image create,
§22/§27.2). Used only for the registry cert fetch/renew. When unset, the
cluster credential is used (works only if it happens to be privileged).		 Optional: {}
port integer Port is the registry's HTTPS port. 5000 Optional: {}
mirrorRegistries string array MirrorRegistries are the upstream registries redirected to the local
registry via containerd hosts.toml. Defaults to the set kubeadm/CNI/CSI use
(registry.k8s.io, docker.io, quay.io, ghcr.io) when empty.		 Optional: {}
vcpus integer VM sizing for the registry (sensible defaults applied when zero). Optional: {}
memoryMiB integer Optional: {}
bootDiskGiB integer Optional: {}

RegistryStatus

RegistryStatus reports one cloudspace's provisioned registry (§26).

Appears in: - VCOClusterStatus

Field Description Default Validation
location string
cloudspaceId string
vmId integer
address string Address is the in-cloudspace address (host:port) nodes pull from.
caBundle string CABundle is the registry's TLS cert/CA (PEM) nodes trust for the mirror.
Public (no private key); empty when the cert chains to a public CA.		 Optional: {}

RetentionSpec

RetentionSpec is the GFS keep-count per tier (defaults 24/7/4/6).

Appears in: - BackupSpec

Field Description Default Validation
hourly integer 24 Optional: {}
daily integer 7 Optional: {}
weekly integer 4 Optional: {}
monthly integer 6 Optional: {}

S3ObjectRef

S3ObjectRef addresses a single object in an S3(-compatible) bucket.

Appears in: - ImageSource

Field Description Default Validation
endpoint string Optional: {}
region string Optional: {}
bucket string MinLength: 1
key string MinLength: 1
forcePathStyle boolean Optional: {}
credentialsSecretRef string MinLength: 1

S3StorageSpec

S3StorageSpec addresses an S3(-compatible) bucket. Reused for image publishing (§27.2). Credentials come from a referenced Secret, never inline.

Appears in: - BackupSpec

Field Description Default Validation
endpoint string Endpoint is the S3 endpoint (host or URL). Empty means AWS S3. Optional: {}
region string Region is the bucket region. Optional: {}
bucket string Bucket is the target bucket name. MinLength: 1
prefix string Prefix is an optional key prefix under which objects are written. Optional: {}
forcePathStyle boolean ForcePathStyle uses path-style addressing (required by most non-AWS S3). Optional: {}
credentialsSecretRef string CredentialsSecretRef names a Secret in the VCOCluster's namespace holding
the S3 credentials (keys: "accessKeyID", "secretAccessKey").		 MinLength: 1

SRIOVSpec

SRIOVSpec configures the SR-IOV CNI add-on (#27).

Appears in: - VCOClusterSpec

Field Description Default Validation
credentialSecretRef string CredentialSecretRef names a Secret (same shape as spec.credentialSecretRef)
that the in-cluster SR-IOV agent uses to attach NICs to worker VMs.
REQUIRED when the add-on is enabled, and deliberately NOT defaulted to the
cluster credential: the agent runs on every worker, where a mounted Secret
is readable by anything with node-level access, so defaulting would place
customer-wide access on every node. Scope this credential to the cluster's
cloudspaces. The provider cannot verify how narrow it is — see
docs/known-limitations.md.		 Optional: {}

StorageSpec

StorageSpec configures storage / the bundled CSI driver's credential scope.

Appears in: - VCOClusterSpec

Field Description Default Validation
credentialScope CredentialScope CredentialScope selects how the per-cluster CSI service account is scoped
(plan §12.1). Pluggable pending the platform disk-scope decision.		 location Enum: [location perDisk cloudspace]
Optional: {}
encryption EncryptionSpec Encryption configures the disk-encryption key vault. Optional: {}

VCOCluster

VCOCluster is the Schema for the vcoclusters API. It is the CAPI InfraCluster: one cloudspace + control-plane LB + public IP.

Appears in: - VCOClusterList

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOCluster
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VCOClusterSpec
status VCOClusterStatus

VCOClusterInitializationStatus

VCOClusterInitializationStatus surfaces the initialization state consumed by the Cluster API v1beta2 infrastructure contract (status.initialization.provisioned).

Appears in: - VCOClusterStatus

Field Description Default Validation
provisioned boolean Provisioned is true when the cluster infrastructure is fully provisioned.
The core Cluster controller reads this path to set InfrastructureReady.		 Optional: {}

VCOClusterList

VCOClusterList contains a list of VCOCluster.

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOClusterList
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items VCOCluster array

VCOClusterSpec

VCOClusterSpec defines the desired state of VCOCluster.

Appears in: - VCOCluster - VCOClusterTemplateResource

Field Description Default Validation
location string Location is the backend datacenter/location code (the PRIMARY location,
which hosts the control-plane endpoint). Required.		 MinLength: 1
geo GeoSpec Geo optionally makes this a geo-redundant, multi-cloudspace cluster (§22). Optional: {}
credentialSecretRef string CredentialSecretRef references a Secret in the VCOCluster's namespace that
holds the whitesky.cloud credential used to provision AND run this cluster. The
CAPVCO controller never mints credentials — the credential is supplied per
cluster by the client (CAPI cluster-identity pattern). The controller uses
it for all backend operations (cloudspace/VM/disk/LB) and injects it into
the workload cluster for the CSI driver.
Expected Secret keys: "jwt" (required; a self-refreshing whitesky.cloud JWT),
"customer_id" (required), and optional "portal_url" / "iam_refresh_url"
overrides (otherwise the manager's instance-level defaults apply).		 MinLength: 1
controlPlaneExposure ControlPlaneExposure ControlPlaneExposure selects how the control-plane endpoint is published. loadbalancer Enum: [loadbalancer portforward]
Optional: {}
controlPlaneEndpoint APIEndpoint ControlPlaneEndpoint is the endpoint used to communicate with the control
plane. Populated by the controller once the LB (or portforward) is up.		 Optional: {}
cloudspace CloudspaceSpec Cloudspace configures the backing cloudspace. Optional: {}
storage StorageSpec Storage configures storage / CSI credential scoping. Optional: {}
backup BackupSpec Backup optionally enables scheduled etcd snapshot backups to S3 (§27.1,
M11). Opt-in: nil means no backups. Snapshots are taken on a control-plane
node, client-side encrypted (age), and uploaded to a BYO S3 bucket under a
tiered-GFS retention pattern, optionally WORM-protected with Object Lock.		 Optional: {}
driftPolicy DriftPolicy DriftPolicy optionally enables drift detection + orphan GC (§27.5, M11).
nil = disabled. When set, the controller periodically compares actual whitesky.cloud
resources against desired and acts per Mode (default Report = detect only).		 Optional: {}
airGapped boolean AirGapped marks the cluster as having no public-internet egress (§26, M12):
every container image is served by an in-cloudspace registry and node
binaries are pre-baked. Implies Registry — the provider provisions a
registry VM per cloudspace before the control plane and wires nodes to pull
through it.		 Optional: {}
sriov SRIOVSpec SRIOV optionally configures the SR-IOV CNI add-on (#27). Enabling the
add-on is a Cluster label; this is where its operator-supplied credential
is named.		 Optional: {}
registry RegistrySpec Registry configures the in-cloudspace image registry (§26, M12). Set it (or
AirGapped) to enable the registry. nil = disabled (nodes pull upstream).		 Optional: {}

VCOClusterStatus

VCOClusterStatus defines the observed state of VCOCluster.

Appears in: - VCOCluster

Field Description Default Validation
initialization VCOClusterInitializationStatus Initialization reports the initialization state consumed by the Cluster
API v1beta2 infrastructure contract. The core Cluster controller gates
InfrastructureReady on status.initialization.provisioned (NOT status.ready).		 Optional: {}
ready boolean Ready denotes that the cluster infrastructure (cloudspace + endpoint) is
provisioned and the control-plane endpoint is published. Retained for
human-facing print columns; the contract-relevant signal is
Initialization.Provisioned.		 Optional: {}
cloudspaceId string CloudspaceID is the backend id of the PRIMARY cloudspace (the one hosting
the control-plane endpoint). For a non-geo cluster it is the only one.		 Optional: {}
cloudspaces CloudspaceStatus array Cloudspaces lists every backing cloudspace, one per location (§22). A
non-geo cluster has a single entry mirroring CloudspaceID/PublicIP. The
controller keys idempotency + teardown (unmesh, per-site delete) off this.		 Optional: {}
failureDomains FailureDomain array FailureDomains reports one failure domain per cloudspace/location so the
core CAPI contract spreads machines across sites. For M8a the primary is
the only ControlPlane=true domain (single CP in the primary cloudspace).		 Optional: {}
loadBalancerId string LoadBalancerID is the backend id of the control-plane load balancer. Optional: {}
serverPoolId string ServerPoolID is the backend id of the LB's ingress server pool. Optional: {}
publicIp string PublicIP is the control-plane endpoint's public IP. Optional: {}
dnsZone string DNSZone is the customer's managed DNS zone this cluster's endpoint names
live under (geo clusters, §22 M8). Cached from the backend so it is fetched
once. Empty for clusters not using the DNS endpoint.		 Optional: {}
controlPlaneDnsTarget string ControlPlaneDNSTarget is the external IP the endpoint DNS name
(.) currently resolves to — the site the controller has
pointed the endpoint at (health-aware, §22 M8). Tracked so the controller
only rewrites the record on an actual change.		 Optional: {}
failureReason string FailureReason is a terminal, machine-readable error indicator. Optional: {}
failureMessage string FailureMessage is a terminal, human-readable error description. Optional: {}
conditions Condition array Conditions defines current service state of the VCOCluster. Optional: {}
backup BackupStatus Backup reports etcd-backup state when spec.backup is set (§27.1). Optional: {}
images VersionImageStatus array Images reports the resolved/published vm-image ids per Kubernetes version
and location (§27.2). Populated by the controller as it resolves overrides
and publishes S3 sources; the machine controller reads it (with the spec as
the source of truth) to pick a machine's image.		 Optional: {}
registries RegistryStatus array Registries reports the per-cloudspace image registries provisioned for an
air-gapped cluster (§26, M12).		 Optional: {}

VCOClusterTemplate

VCOClusterTemplate is the Schema for the vcoclustertemplates API.

Appears in: - VCOClusterTemplateList

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOClusterTemplate
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VCOClusterTemplateSpec

VCOClusterTemplateList

VCOClusterTemplateList contains a list of VCOClusterTemplate.

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOClusterTemplateList
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items VCOClusterTemplate array

VCOClusterTemplateResource

VCOClusterTemplateResource holds the template body for a VCOCluster.

Appears in: - VCOClusterTemplateSpec

Field Description Default Validation
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec VCOClusterSpec

VCOClusterTemplateSpec

VCOClusterTemplateSpec defines the desired state of VCOClusterTemplate.

Appears in: - VCOClusterTemplate

Field Description Default Validation
template VCOClusterTemplateResource

VCOMachine

VCOMachine is the Schema for the vcomachines API. It is the CAPI InfraMachine: one backend VM (+ boot/data disks).

Appears in: - VCOMachineList

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOMachine
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VCOMachineSpec
status VCOMachineStatus

VCOMachineInitializationStatus

VCOMachineInitializationStatus surfaces the initialization state consumed by the Cluster API v1beta2 infrastructure contract (status.initialization.provisioned).

Appears in: - VCOMachineStatus

Field Description Default Validation
provisioned boolean Provisioned is true when the VM is fully provisioned. The core Machine
controller reads this path to advance the Machine past Provisioning.		 Optional: {}

VCOMachineList

VCOMachineList contains a list of VCOMachine.

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOMachineList
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items VCOMachine array

VCOMachineSpec

VCOMachineSpec defines the desired state of VCOMachine.

Appears in: - VCOMachine - VCOMachineTemplateResource

Field Description Default Validation
providerID string ProviderID is the identifier shared by VCOMachine.spec.providerID and the
node's kubelet provider-id — format vco:///. It
is chosen by the controller (from the owning Machine) before VM create.		 Optional: {}
imageId integer ImageID is the backend image the VM boots from (§6). Required. Minimum: 1
vcpus integer VCPUs is the number of virtual CPUs. Minimum: 1
memoryMiB integer MemoryMiB is the memory in MiB. Minimum: 1
bootDiskGiB integer BootDiskGiB is the boot disk size in GiB. Minimum: 1
dataDisks integer array DataDisks lists optional extra data-disk sizes in GiB. Optional: {}
etcdDisk EtcdDiskSpec EtcdDisk optionally attaches a dedicated disk mounted at /var/lib/etcd so
etcd's write-ahead log lives on low-latency storage (plan §21). Set on the
control-plane VCOMachineTemplate only; it is IGNORED on worker machines.
When present the disk is created + attached before the VM's first boot,
formatted+mounted by filesystem LABEL (reboot-safe), and deleted on
machine teardown.		 Optional: {}
diskGrowthPolicy DiskGrowthPolicySpec DiskGrowthPolicy optionally enables automatic node disk expansion (§23,
M9): the controller grows the whitesky.cloud vDisk before the node hits DiskPressure,
and an injected growfs systemd timer grows the in-node partition +
filesystem online. Applies to the boot disk and, when present, the M7 etcd
disk. Disabled when nil.		 Optional: {}
gpu GPUSpec GPU optionally attaches GPU(s) to this machine (#34). A GPU is requested by
TYPE ("NVIDIA A100") or profile id, never by instance: the controller
resolves the type against the machine's location, reserves that many named
vGPU instances, and releases them on teardown. Set on a worker
VCOMachineTemplate to build a GPU node pool.		 Optional: {}
osType string OSType/OSName/BootType are optional VM-create hints for the stock-image
path (§6 B). Left empty for pre-baked images.		 Optional: {}
osName string Optional: {}
bootType string Enum: [bios uefi]
Optional: {}

VCOMachineStatus

VCOMachineStatus defines the observed state of VCOMachine.

Appears in: - VCOMachine

Field Description Default Validation
initialization VCOMachineInitializationStatus Initialization reports the initialization state consumed by the Cluster
API v1beta2 infrastructure contract. The core Machine controller reads
status.initialization.provisioned (NOT status.ready).		 Optional: {}
ready boolean Ready denotes the VM is running with an assigned address (and, for
control-plane machines, registered in the LB pool). Retained for
human-facing print columns; the contract-relevant signal is
Initialization.Provisioned.		 Optional: {}
vmId integer VMID is the backend id of the VM, discovered from the create response. Optional: {}
addresses MachineAddress array Addresses holds the node's discovered addresses. Optional: {}
etcdDiskId string EtcdDiskID is the backend id of the dedicated etcd disk (§21), recorded
for idempotent attach and for detach+delete on teardown. Empty when no
etcd disk was requested.		 Optional: {}
etcdDiskAttached boolean EtcdDiskAttached is set once the etcd disk has been attached to the VM, so
the attach is performed exactly once (the VM is created stopped, the disk
attached, then the VM started — §21).		 Optional: {}
gpus GPUStatus array GPUs records the vGPU instances reserved for this machine (#34). Recorded
BEFORE anything else so teardown can always release them: a reservation is
billed whether attached or not, so a forgotten id is a silent recurring
cost, not just untidiness.		 Optional: {}
loadBalancerHostId string LoadBalancerHostID is the id of this machine's host entry in the
control-plane LB server pool (control-plane machines only). Recorded so
registration is idempotent and the host can be removed on delete.		 Optional: {}
portforwardId string PortforwardID is the id of this control-plane machine's :6443 portforward
on its cloudspace's external IP (geo DNS endpoint, §22 M8). Recorded so the
portforward is created once and removed on delete.		 Optional: {}
cloudspaceId string CloudspaceID is the backend id of the cloudspace this machine's VM lives in
(its failure domain's cloudspace for geo, else the primary). Recorded so
teardown can address the machine's own cloudspace (e.g. its portforward).		 Optional: {}
bootDiskGiB integer BootDiskGiB is the last-observed boot disk size in GiB (§23, M9). Tracks
the current backend size so growth is computed from it and the per-disk cap
is enforced.		 Optional: {}
etcdDiskGiB integer EtcdDiskGiB is the last-observed etcd disk size in GiB (§23, M9). Optional: {}
lastDiskGrowthTime Time LastDiskGrowthTime is when the controller last grew a disk (§23, M9), used
to enforce a cooldown between expansions (avoids runaway growth while the
in-node filesystem catches up).		 Optional: {}
failureReason string FailureReason is a terminal, machine-readable error indicator. Optional: {}
failureMessage string FailureMessage is a terminal, human-readable error description. Optional: {}
conditions Condition array Conditions defines current service state of the VCOMachine. Optional: {}

VCOMachineTemplate

VCOMachineTemplate is the Schema for the vcomachinetemplates API (used by KubeadmControlPlane and MachineDeployment).

Appears in: - VCOMachineTemplateList

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOMachineTemplate
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VCOMachineTemplateSpec
status VCOMachineTemplateStatus Optional: {}

VCOMachineTemplateList

VCOMachineTemplateList contains a list of VCOMachineTemplate.

Field Description Default Validation
apiVersion string infrastructure.cluster.x-k8s.io/v1alpha1
kind string VCOMachineTemplateList
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items VCOMachineTemplate array

VCOMachineTemplateResource

VCOMachineTemplateResource holds the template body for a VCOMachine.

Appears in: - VCOMachineTemplateSpec

Field Description Default Validation
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional: {}
spec VCOMachineSpec

VCOMachineTemplateSpec

VCOMachineTemplateSpec defines the desired state of VCOMachineTemplate.

Appears in: - VCOMachineTemplate

Field Description Default Validation
template VCOMachineTemplateResource

VCOMachineTemplateStatus

VCOMachineTemplateStatus is the observed state of a VCOMachineTemplate.

It exists for ONE reason: the cluster autoscaler cannot scale a worker pool up from zero replicas unless it can learn the SHAPE of a node it has never seen. With replicas > 0 it reads a live Node; at zero there is nothing to read, so the CAPI contract asks the infrastructure provider to publish the capacity here. See the "support cluster autoscaling from zero" section of the CAPI InfraMachineTemplate contract, and docs/guides/autoscaling.md.

Appears in: - VCOMachineTemplate

Field Description Default Validation
capacity ResourceList Capacity is the resource capacity of a node built from this template,
derived from the template's own spec (vcpus, memoryMiB, bootDiskGiB).
This is the VM's capacity, NOT the node's allocatable: a real node reports
less, because the kernel, the kubelet and system reservations take their
cut first. The autoscaler therefore models a slightly roomier node than it
gets, which can cost one wasted scale-up for a pod that only just fits.
Every Cluster API provider has this wart; understating it instead would
refuse scale-ups that would have worked, which is worse.		 Optional: {}
nodeInfo NodeInfo NodeInfo is the architecture and OS of a node from this template. MinProperties: 1
Optional: {}

VaultMode

Underlying type: string

VaultMode selects the disk-encryption key vault backing StorageClasses that request encryption.

Validation: - Enum: [none external managed]

Appears in: - EncryptionSpec

Field Description
none
external
managed

VersionImage

VersionImage maps a Kubernetes version to the vm-image to use (§27.2). It carries an optional S3 Source artifact the controller publishes to each location on demand, plus optional per-location id overrides for images that are already present (preserving the BYO-imageId path).

Appears in: - GeoSpec

Field Description Default Validation
kubernetesVersion string KubernetesVersion is the exact version this image serves (e.g. v1.35.8). MinLength: 1
source ImageSource Source is the image artifact in S3 to publish to each location that lacks
an override. Optional when every used location has a LocationImageIds entry.		 Optional: {}
locationImageIds LocationImage array LocationImageIds pins already-published vm-image ids per location. A
location listed here is used verbatim and never (re-)published.		 Optional: {}

VersionImageStatus

VersionImageStatus reports resolved image ids for one Kubernetes version.

Appears in: - VCOClusterStatus

Field Description Default Validation
kubernetesVersion string
locationImageIds LocationImage array