Start here · v0.0.1

Create the first cluster

Use a non-production environment to prove the complete provider, node, lifecycle, evidence, and cleanup path.

AudienceCluster operators, platform engineersReading time18 minCommands in context2 guided stepsReviewed sourcefcc5871 · 30 July 2026

Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.

Before you begin

✓
ClusterPilot is healthy, ready, backed up, and running the expected signed build.
✓
A compatible lifecycle agent is active with accepted placement, trust, clock, and contract versions.
✓
The selected provider is approved for your release scope. Hetzner and IONOS are supported but production-gated; AWS and Azure are disabled in v0.0.1.
✓
Network CIDRs, DNS, egress, firewall, SSH, node operating system, capacity, and Kubernetes version are documented.
✓
The environment is disposable and has a tested cleanup owner, budget, and evidence retention decision.

Commands for this step

Confirm the lifecycle identity can establish cluster administration

Run this capability check before the first disposable cluster plan. A denied result is a stop condition.

Run in orderComplete each step successfully before continuing.

01
Read-onlyKubernetes
Check cluster-admin bind capability
Prove whether the current Kubernetes identity can bind cluster-admin before a controlled infrastructure or bootstrap gate.
Before you run it
- Explicit kube context for the intended disposable or controlled target
- Identity review
Kubernetes · cluster-admin-bind-capability
```
kubectl auth can-i bind clusterroles/cluster-admin
```
Expected result
yes or no is recorded as evidence; no permission is changed by the check.
Stop conditions and operator notes
- A yes result is high privilege, not a requirement to use that privilege. Keep routine ClusterPilot operation least-privileged.
Reviewed sourcedocs/testing/release-v0.0.1-release-readiness-traceability.md

Register and validate a provider account

Create the provider account through the UI or API using a secret reference. Never put a cloud token, SSH private key, registry password, or kubeconfig in an operation request. Run provider validation and review identity, permissions, reachability, rate-limit posture, and discovered resources.

Build and review the plan

01
Select location and topology
Choose control-plane and worker counts, private network, ingress endpoint mode, and availability expectations.
02
Select the supported baseline
Choose a ClusterPilot-supported Kubernetes, Helm, Calico, and node operating-system combination from the support matrix.
03
Run preflight and node probes
Resolve duplicate host identity, kernel, CPU, memory, ports, routes, time, SSH, package, and container-runtime failures.
04
Review intended resources
Confirm provider resources, addresses, volumes, firewall effects, node roles, commands, and deletion ownership.
05
Approve the guarded run
Use the required role, confirmation, idempotency key, and change record. Store the OperationRun ID.

Observe the OperationRun

Follow ordered steps, events, logs, commands, artifacts, and correlation IDs. Do not bypass a blocked step with manual cloud or cluster changes; first determine whether the safe next action is retry, corrected input, agent recovery, or cleanup.

State	Operator action
Queued	Verify an active compatible agent and any not-assignable reason.
Running	Observe progress; do not start a conflicting lifecycle operation.
Cancel requested	Wait for owned cleanup and terminal state.
Failed	Inspect the first failed step and its redacted evidence before retrying.
Succeeded	Run cluster health and evidence acceptance checks before handover.

Acceptance and cleanup test

✓
Every expected node is Ready and matches the intended role and version.
✓
The API endpoint mode is reachable only through the approved network path.
✓
Core system pods and Calico are healthy; no hidden manual repair was required.
✓
A quick Sonobuoy run completes and artifacts can be downloaded and verified.
✓
A built-in add-on can pass preflight, install, and its semantic health gate.
✓
A scale or replace operation and a supported one-minor upgrade can be rehearsed in a disposable environment.
✓
Cluster deletion removes owned provider resources or produces an explicit residual-resource report.

Learn how to inspect and recover an OperationRun →

Commands for this step

Collect the first cluster acceptance evidence

Run these read-only checks after the OperationRun succeeds and before the cluster is accepted for further testing.

Run in orderComplete each step successfully before continuing.

01
Read-onlyKubernetes
Collect customer-cluster health evidence
Capture the minimum direct cluster state during an approved break-glass investigation.
Before you run it
- Customer-owned approved kubeconfig
- Read-only investigation approval
Kubernetes · cluster-basic-health
```
kubectl get nodes -o wide
kubectl get pods --all-namespaces
kubectl version
kubectl get --raw=/readyz?verbose
```
Expected result
Nodes, system workloads, version and API readiness align with the ClusterPilot observed-state evidence.
Stop conditions and operator notes
- Prefer ClusterPilot read/evidence paths for routine operations; direct kubectl is an explicit customer-controlled investigation boundary.
Reviewed sourcedocs/operations/cluster-lifecycle-rollout-compatibility-runbook.md

Create the first cluster

Before you begin

Register and validate a provider account

Build and review the plan

Select location and topology

Select the supported baseline

Run preflight and node probes

Review intended resources

Approve the guarded run

Observe the OperationRun

Acceptance and cleanup test