Contributing¶

Repository layout¶

Path	What
`api/v1alpha1/`	CRD Go types (source of the API reference).
`controllers/`	The `VCOCluster` / `VCOMachine` reconcilers + feature reconciles.
`pkg/vco/`	The VCO REST client (`/api/1` + `/alpha`).
`pkg/*`	Feature packages: `cloudinit`, `servicelb`, `ccm`, `objectspace`, `etcdbackup`, `externaldns`.
`cmd/`	Binaries: `manager`, `vcolb`, `vco-ccm`, `capvco-backup`, `vco-externaldns-webhook`.
`config/`	Kustomize: CRDs, RBAC, add-on `ClusterResourceSet`s, observability.
`templates/`	`clusterctl generate cluster` templates.
`image-builder/`	Pre-baked node/registry image pipeline.

Dev loop¶

make generate manifests   # regenerate DeepCopy + CRDs/RBAC after api changes
make docs-api             # regenerate the CRD API reference
make build                # compile
make test                 # unit tests
make vet

Common iteration uses a kind management cluster with clusterctl init, then running the manager out-of-cluster with go run ./cmd/manager (instance env + a kubeconfig to kind). The workload-side controllers (vcolb, vco-ccm, vco-externaldns-webhook) can likewise be run out-of-cluster for validation when their image isn't published to a registry the VCO nodes can pull.

Conventions¶

Every backend operation goes through pkg/vco; delete/attach helpers tolerate 404 (idempotent teardown).
Feature APIs are opt-in (a nil spec block or an absent Cluster label = disabled).
New CRD fields: add to api/v1alpha1, then make generate manifests docs-api.

Validation discipline¶

Changes are live-validated against the real VCO API before a milestone is considered done; destructive/DR paths are exercised (delete a VM and watch remediation, restore etcd from a snapshot), not just compiled. See cluster-api-plan.md for the per-milestone validation record.

Release process: Releasing.