Cluster lifecycle
Plan and operate node preparation, kubeadm bootstrap, scale, upgrade, replacement, and deletion.
Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.
Supported v0.0.1 baseline
| Kubernetes | Helm | Calico |
|---|---|---|
| 1.32.13 | v3.20.2 | v3.31.5 |
| 1.33.13 | v3.21.1 | v3.31.5 |
| 1.34.9 | v3.21.1 | v3.32.0 |
| 1.35.6 | v3.21.1 | v3.32.0 |
| 1.36.2 | v3.21.1 | v3.32.0 |
ClusterPilot permits a one-minor upgrade step. Use the exact compatibility manifest shipped with your signed release; do not substitute a newer upstream patch, CNI, or Helm binary without a new approved compatibility record.
Node operating systems and prerequisites
Node preparation supports Ubuntu 22.04/24.04, Debian 11/12, RHEL 8/9, Rocky Linux 8/9, AlmaLinux 8/9, and CentOS Stream 9 with kernel 5.4 or newer. Provider images and repositories can impose stricter constraints.
- ✓Unique hostname, MAC address, and product UUID for every node.
- ✓At least 2 CPUs and 2 GiB RAM for a control-plane node; production sizing must be higher and workload driven.
- ✓Full required network connectivity, routes, ports, DNS, and time synchronization.
- ✓Supported container runtime and cgroup configuration.
- ✓No conflicting kubeadm/kubelet state unless an approved redeploy or cleanup plan owns it.
Lifecycle operations
| Operation | Key guardrails | Acceptance evidence |
|---|---|---|
| Create | Provider validation, probes, topology, compatibility, artifact locks. | Nodes Ready, API endpoint, CNI/core pods, inventory and run artifacts. |
| Scale | No conflicting active run, capacity/quota, role and version compatibility. | Intended node count, joined role, scheduling and network health. |
| Upgrade | Exactly one minor, healthy baseline, backup/rollback posture, approved target lock. | Control plane then nodes converge; workload and add-on health retained. |
| Replace node | Role/quorum safety, drain posture, provider ownership. | Old identity retired, replacement healthy, residual resources accounted for. |
| Delete | Explicit destructive confirmation, retention decision, ownership inventory. | Owned resources removed or listed with actionable residuals. |
Upgrade order and skew
Kubernetes component skew constrains safe order. ClusterPilot narrows the general upstream policy to a tested one-minor lifecycle contract. Update the control plane and components according to the generated plan; do not jump minors or upgrade workers beyond the active API server.
Kubernetes version skew policyStuck or failed lifecycle work
Capture the run, cluster, step, command, agent, lease, checkpoint, and correlation IDs. Verify agent heartbeat and compatibility, then inspect the first failed step. A stale step can require recovery-worker ownership; do not start a second conflicting lifecycle operation or mutate the node manually.
Use the symptom-first troubleshooting guide →