Self-hosted
DERequest a demo →
Skip to documentation content
ClusterPilot Docs
Product tour Self-hosted
Start with:EvaluateInstallCreate a clusterOperateRecoverAutomate
Documentation/Start here
Start here

Create the first cluster

Follow the complete provider, node, lifecycle, result and cleanup workflow.

AudienceCluster operators, platform engineersReading time18 minCommands in context1 guided stepsReviewed source9552586 · 1 August 2026

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.
  • ✓
    A Hetzner or IONOS provider account is connected and validated.
  • ✓
    Network CIDRs, DNS, egress, firewall, SSH, node operating system, capacity, and Kubernetes version are documented.
  • ✓
    The environment has a clear owner, budget and result-retention decision.

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

  1. 01

    Select location and topology

    Choose control-plane and worker counts, private network, ingress endpoint mode, and availability expectations.

  2. 02

    Select the supported baseline

    Choose a ClusterPilot-supported Kubernetes, Helm, Calico, and node operating-system combination from the support matrix.

  3. 03

    Run preflight and node probes

    Resolve duplicate host identity, kernel, CPU, memory, ports, routes, time, SSH, package, and container-runtime failures.

  4. 04

    Review intended resources

    Confirm provider resources, addresses, volumes, firewall effects, node roles, commands, and deletion ownership.

  5. 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.

StateOperator action
QueuedVerify an active compatible agent and any not-assignable reason.
RunningObserve progress; do not start a conflicting lifecycle operation.
Cancel requestedWait for owned cleanup and terminal state.
FailedInspect the first failed step and its redacted evidence before retrying.
SucceededRun 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 →