Skip to content

Prerequisites

You need four things before creating a cluster. This page gets each one in place. Budget ~20 minutes the first time.

Checklist

  • Command-line tools: kubectl, clusterctl, and Docker (for a local management cluster)
  • A management cluster to run the controllers
  • A whitesky.cloud credential (a JWT + customer id) your clusters will use
  • Your whitesky.cloud instance URLs (portal + IAM refresh) and a location

1. Command-line tools

Tool What it’s for Install
kubectl Talk to any Kubernetes cluster https://kubernetes.io/docs/tasks/tools/
clusterctl Install/operate Cluster API and render cluster manifests https://cluster-api.sigs.k8s.io/user/quick-start
Docker Only if you’ll run the management cluster locally with kind https://docs.docker.com/get-docker/
kind A throwaway local management cluster (dev/learning) https://kind.sigs.k8s.io/

clusterctl version — use v1.14.x

CAPVCO targets the v1beta2 Cluster API contract, so you need a clusterctl that supports it. Use v1.14.x (matching the CAPI the provider is built and tested on). Two failure modes:

  • a too-old clusterctl (v1.10 or earlier) fails at init/generate with "current version of clusterctl is only compatible with v1beta1 providers, detected v1beta2";
  • a clusterctl older than v1.13.6 cannot bootstrap Kubernetes v1.37 workload clusters at all — and CAPVCO ships node images for it. See the Cluster API support matrix.

Note the management cluster itself must run a Kubernetes version CAPI accepts for management, which is a narrower range than for workload clusters — v1.33 or newer for CAPI v1.14. Upgrade:

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.14.2/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl && sudo mv clusterctl /usr/local/bin/clusterctl
clusterctl version

Verify:

kubectl version --client
clusterctl version

2. A management cluster

The management cluster is where Cluster API and CAPVCO run. It does not need to be on whitesky.cloud and it does not run your apps — it just builds and watches workload clusters.

kind create cluster --name capvco-mgmt
kubectl config use-context kind-capvco-mgmt
kubectl get nodes    # one control-plane node, Ready

A kind cluster is perfect for trying CAPVCO. Note that it lives on your laptop — fine for experiments, not for production (if your laptop is off, reconciliation stops).

Use any conformant, highly-available Kubernetes cluster you operate for the long term (its availability governs whether your workload clusters keep being reconciled). A small 3-node cluster is plenty. You can even bootstrap onto whitesky.cloud itself and pivot.

3. A whitesky.cloud credential

Every cluster is provisioned and run with a whitesky.cloud credential you supply — CAPVCO mints none of its own. It’s a self-refreshing JWT plus your customer id. You’ll put these into a Kubernetes Secret in the first-cluster step; for now, obtain them from your whitesky.cloud portal / IAM and keep them handy.

Scope & privilege

  • The per-cluster credential is used for all backend operations for that cluster (cloudspace, VMs, disks, LB) and is injected into the workload cluster for the CSI driver, so scope it to what one cluster needs.
  • A few platform operations are operator-privileged and use a separate operator credential: publishing VM images and issuing registry TLS certificates. You only need that operator credential for pre-baked images and air-gapped clusters — not for a basic cluster.

4. Instance URLs & a location

CAPVCO is white-label-generic, so it needs to know which whitesky.cloud portal it’s talking to:

Value Example Where it’s set
Portal base URL https://<your-whitesky.cloud-portal> Manager's capvco-credentials Secret, key portalUrl (optionally overridden per cluster)
IAM / JWT-refresh URL https://<your-iam-host>/v1/oauth/jwt/refresh Manager's capvco-credentials Secret, key iamRefreshUrl (optionally overridden per cluster)
Location <your-location> Per cluster, in VCOCluster.spec.location — location code from your portal (location-specific, no default)

Portal and IAM URLs are independent

Do not assume the IAM host is derived from the portal host. They are configured separately on purpose so the provider works across white-label deployments where the two differ.

Find your available locations from the whitesky.cloud portal (or ask your whitesky.cloud operator). A location is a physical datacenter; a basic cluster lives entirely in one.

Everything checked? → Install the provider.