CLI tools

CAPVCO ships two operator-facing command-line tools as release binaries (cross-compiled for linux/darwin × amd64/arm64):

• capvco-imagepublish — publish a VM image into your whitesky.cloud location(s).
• capvco-backup — the etcd snapshot/restore helper (normally run as a CronJob, but usable directly for restores).

The other binaries (manager, vcolb, vco-ccm, vco-externaldns-webhook) run in-cluster, shipped inside the manager container image and deployed by add-ons — you don't invoke them by hand. They're documented at the end for completeness.

Common environment

The whitesky.cloud-facing tools read the same four settings from the environment (portal URL and IAM refresh URL are independent — don't derive one from the other):

Var	Meaning
VCO_PORTAL_URL	Portal base URL, e.g. https://<your-whitesky.cloud-portal>
VCO_IAM_REFRESH_URL	IAM JWT-refresh endpoint, e.g. https://<your-iam-host>/v1/oauth/jwt/refresh
VCO_JWT	The self-refreshing JWT
VCO_CUSTOMER_ID	Your customer id

capvco-imagepublish

Publishes a VM image to one or more locations via the platform's import-from-download-URL API. Idempotent per location (an already-ready image of the same name is adopted, not re-imported), and publishes into every -locations entry from a single source. See Pre-baked images for the workflow.

Operator-privileged

Creating a vm-image requires an operator credential — a per-cluster customer credential gets a 403. Set VCO_JWT to an operator token.

Exactly one of -url / -file is required.

Flag	Default	Meaning
-name	— (required)	vm-image name.
-url	—	Download URL the platform fetches server-side (e.g. a GitLab release/artifact URL). No S3 needed.
-file	—	Local image file; uploaded to S3, presigned, then imported.
-locations	$VCO_LOCATION	Comma-separated locations to publish into.
-boot-disk-gib	40	Image minimum boot-disk size.
-memory-mib	4096	Image minimum memory.
-boot-type	bios	bios | uefi.
-os-name	Linux - other	Platform OS-name enum (a bare ubuntu is rejected).
-os-type	Linux	OS family.
-poll-timeout	30m	Per-location readiness wait.

-file (S3) mode also accepts: -s3-key (default images/<name>.qcow2), -presign-ttl (24h), -force-upload (false), -keep-object (false — the object is deleted after a successful import unless set).

S3 env for -file mode: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY (required); S3_REGION, S3_FORCE_PATH_STYLE (optional).

# From a URL (no S3):
capvco-imagepublish -url "https://gitlab.whitesky.cloud/api/v4/projects/730/packages/generic/capvco-images/node-images/capvco-ubuntu-2404-cloudimg-v1.36.4.qcow2" \
  -name k8s-v1.36.4 -locations loc-a,loc-b

# From a local file (via S3):
capvco-imagepublish -file ./dist/node-v1.36.4.qcow2 -name k8s-v1.36.4 -locations loc-a

capvco-backup

A self-contained etcd backup tool. In normal operation it runs as an in-cluster CronJob the backup feature injects, configured entirely by environment (via envFrom on the injected Secret) — no flags. You run it directly only for restores.

Subcommands:

Subcommand	Purpose
snapshot	Snapshot local etcd → age-encrypt → upload to S3 with GFS retention + optional Object-Lock retain-until → prune expired. (The CronJob entrypoint.)
fetch	Download + age-decrypt a chosen snapshot (the restore helper).
keygen	Print a fresh age identity + recipient.

Key environment:

• snapshot requires CLUSTER_NAME. Retention: RETENTION_HOURLY (24), RETENTION_DAILY (7), RETENTION_WEEKLY (4), RETENTION_MONTHLY (6). Object Lock: OBJECT_LOCK_ENABLED, OBJECT_LOCK_MODE. etcd: ETCD_ENDPOINTS (CSV), ETCD_CACERT, ETCD_CERT, ETCD_KEY. Encryption: AGE_RECIPIENT.
• fetch requires SNAPSHOT_KEY, OUT, and one of AGE_IDENTITY / AGE_IDENTITY_FILE.
• S3 (all): S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_FORCE_PATH_STYLE, optional S3_PREFIX.

# Fetch + decrypt a snapshot during a restore (see the restore runbook):
export S3_ENDPOINT=… S3_BUCKET=… S3_ACCESS_KEY_ID=… S3_SECRET_ACCESS_KEY=…
export AGE_IDENTITY_FILE=./backup-identity.txt
capvco-backup fetch   # with SNAPSHOT_KEY=… OUT=./snapshot.db

The complete restore procedure is the etcd restore runbook.

In-cluster binaries (for reference)

You don't run these directly — add-ons deploy them.

Binary	Deployed by	Role
manager	clusterctl init	The CAPVCO controllers (the release container image).
vcolb	service-lb add-on	Reconciles Service type=LoadBalancer → whitesky.cloud LBs.
vco-ccm	ccm add-on	Cloud-controller-manager: node init + Service-LB.
vco-externaldns-webhook	external-dns add-on	ExternalDNS webhook provider backed by whitesky.cloud DNS.

There are also several throwaway diagnostic/spike commands in cmd/ (geospike, ingressdiag, m0spike, samintdiag, openbao-deploy) used during development and validation — not part of the operator workflow.