Core concepts¶

New to Kubernetes, Cluster API, or whitesky.cloud? This page gives you just enough of the mental model to make the rest of the docs click. If you already run clusters, skim the glossary and skip to Prerequisites.

Kubernetes in one minute¶

Kubernetes runs your applications as containers (packaged, isolated processes) spread across a set of machines called nodes, and keeps them running the way you declared — restarting crashed containers, rescheduling them when a node dies, scaling them up and down.

A cluster has two kinds of node:

Control-plane nodes run the "brain": the API server (what kubectl talks to), etcd (the database holding all cluster state), the scheduler and the controllers. Lose etcd and you lose the cluster — which is why backups (later) matter so much.
Worker nodes run your actual workloads.

You never SSH into nodes to deploy things. You send declarations ("I want 3 replicas of this app, exposed on port 80") to the API server, and Kubernetes makes reality match.

The one idea to hold onto

Everything in Kubernetes is declarative and reconciled: you state the desired end state, a controller continuously works to achieve and maintain it. CAPVCO applies that same idea one level down — to the cluster itself.

Cluster API (CAPI), and where CAPVCO fits¶

Normally, creating a cluster (provisioning VMs, networking, load balancers, installing Kubernetes) is a separate, manual, cloud-specific chore. Cluster API makes the cluster itself a Kubernetes object: you kubectl apply a Cluster, and controllers build it for you — declaratively and reconciled, exactly like apps inside a cluster.

Two clusters are involved, and keeping them straight is the single most important thing:

flowchart LR
  subgraph M["Management cluster (small, long-lived)"]
    direction TB
    core["Cluster API core + kubeadm providers"]
    capvco["CAPVCO (infrastructure provider)"]
  end
  subgraph W["Workload cluster (what you actually use)"]
    direction TB
    wcp["control plane"]
    wn["worker nodes + your apps"]
  end
  you["kubectl apply Cluster YAML"] --> M
  M -->|creates & reconciles| W

The management cluster is a small Kubernetes cluster where the Cluster API controllers live. It doesn’t run your apps; it runs the machinery that builds other clusters. (For learning, this is often a throwaway kind cluster on your laptop.)
A workload cluster is a cluster CAPVCO creates on whitesky.cloud. This is the one you hand to your teams.

Cluster API is modular. It always has a core controller and bootstrap/control-plane controllers (kubeadm, which turns VMs into Kubernetes nodes). What it needs from each cloud is an infrastructure provider that knows how to make VMs, networks and load balancers there.

CAPVCO is that infrastructure provider for whitesky.cloud. It translates Cluster API’s generic requests ("give me a control-plane machine", "publish the API endpoint") into whitesky.cloud operations.

whitesky.cloud and the VCO model¶

CAPVCO builds on whitesky.cloud. whitesky.cloud is a Virtual Cloud Operator (VCO) platform — a wholesale cloud model borrowed from telecom’s MVNE/MVNO structure: one operator runs the underlying cloud infrastructure, and partners resell fully white-labeled clouds on top of it, each under its own brand and domain. (Background: the VCO / cloud-enabler model.)

What that means for you in practice:

You connect to a whitesky.cloud portal — a branded instance of the platform (its own portal URL and IAM/JWT endpoint). CAPVCO is portal-agnostic: point it at any portal via configuration.
The letters VCO live on in the product and API names — the provider CAPVCO, and the CRDs VCOCluster / VCOMachine — where they simply mean "the whitesky.cloud (Virtual Cloud Operator) platform". Everywhere else these docs say whitesky.cloud.

The platform pieces that matter here:

whitesky.cloud concept	What it is	CAPVCO uses it for
Cloudspace	An isolated virtual datacenter (private network + gateway) in a location (a physical datacenter).	One cloudspace per cluster → strong isolation. Geo clusters use several.
VM image	A bootable disk image in a location.	Control-plane & worker nodes boot from it — a stock Ubuntu image, or a pre-baked one with Kubernetes already installed.
cloud-init	First-boot configuration a VM reads from the platform.	How each node is told to join the cluster (and its `provider-id`).
Load balancer	An L4 ingress in the cloudspace with a public IP.	Publishing the control-plane API endpoint on `:6443`, and `Service type=LoadBalancer`.
Managed DNS	whitesky.cloud-hosted DNS zones.	Geo control-plane endpoints and ExternalDNS.
Objectspace	S3-compatible object storage.	Encrypted etcd backups.

One instance per portal, no brand hardcoding

CAPVCO is white-label-generic. The whitesky.cloud portal URL, IAM/JWT-refresh URL, customer id and credentials are all configuration — nothing brand-specific is compiled in — so the same build works against any whitesky.cloud portal. You run one provider instance per portal.

How a cluster is described¶

You don’t hand-write all of this from scratch — you render a template — but it helps to recognise the objects. A minimal cluster is a handful of linked resources you apply to the management cluster:

flowchart TD
  Cluster -->|infrastructureRef| VCOCluster
  Cluster -->|controlPlaneRef| KCP["KubeadmControlPlane"]
  KCP -->|machineTemplate| VCOMTcp["VCOMachineTemplate (control plane)"]
  MD["MachineDeployment (workers)"] -->|infra + bootstrap| VCOMTwk["VCOMachineTemplate (workers)"]

Cluster — the top-level CAPI object tying everything together.
VCOCluster — the CAPVCO object: which location(s), how to expose the API server, geo mesh, backups, storage policy, and the credential to use. (This is where most whitesky.cloud-specific config lives.)
KubeadmControlPlane — how many control-plane nodes, which Kubernetes version, and the kubeadm config to bootstrap them.
MachineDeployment — a pool of worker nodes (like a Deployment, but for machines).
VCOMachineTemplate — the VM shape (image, CPU, memory, disks) for control plane and workers.

CAPVCO watches these, provisions the matching whitesky.cloud infrastructure, and reports real status back onto the objects (so clusterctl describe cluster shows the truth).

Glossary¶

Management cluster: The Kubernetes cluster where Cluster API + CAPVCO run and reconcile workload clusters.
Workload cluster: A cluster CAPVCO creates on whitesky.cloud — the one you deploy applications to.
Infrastructure provider: The Cluster API plug-in that knows how to create machines/networks/LBs on a specific cloud. CAPVCO is the one for whitesky.cloud.
Cloudspace: An isolated virtual datacenter on whitesky.cloud. CAPVCO uses one per cluster.
provider-id: A stable id (vco://<cloudspaceId>/<machineUID>) linking a Kubernetes Node to its whitesky.cloud VM.
Add-on / ClusterResourceSet: Extra components (CNI, CSI, ExternalDNS, …) CAPVCO applies into the workload cluster automatically, selected by labels on the Cluster.
Pre-baked image: A VM image with containerd + Kubernetes already installed, so nodes boot fast and offline.

Ready? → Prerequisites — what you need before creating a cluster.