How handover works
Handover is how a cluster moves between kubehz’s hosted control plane and infrastructure you own — the mechanism behind the no-lock-in promise. This page explains the idea; the step-by-step guide is Migration — moving in and out.
A cluster is its identity, not its servers
Strip a Kubernetes cluster down and what makes it that cluster is surprisingly small:
- the certificate authority every node and kubeconfig trusts,
- the service-account signing keys every workload token is signed with,
- the encryption key protecting secrets at rest,
- and the data — every API object, in etcd.
The servers running the control plane are replaceable; the identity is not. Move the identity and the data, and the cluster is the same cluster — wherever its control plane happens to run. That is the whole trick: handover moves the identity, not the machines.
Restore-based, on boring foundations
Handover deliberately uses mechanisms that are battle-tested rather than clever:
- The platform assembles an export bundle — the identity above — and takes a fresh etcd snapshot.
- On your target machine, the bundle is seeded before the new control plane initializes, and the snapshot is restored.
- The standard Kubernetes bootstrap then reuses the seeded identity instead of minting a fresh one.
The result comes up as your cluster — same CA, same keys, same objects. Your workers already trust it; they reconnect and carry on. No live wire-transfer between control planes, no bespoke replication protocol — a snapshot and a restore, auditable at every step.
You are the gate
Handover is deliberately not fully automatic. Two moments belong to you:
- Cutover — repointing the cluster’s endpoint DNS at the new control plane is your action, and the platform waits for your explicit confirmation. Until then, nothing destructive has happened.
- Decommission — the old control plane is removed only after the platform has seen the new one alive (heartbeating) and you have confirmed a second time. Until both, the old side stays intact as your fallback.
A handover that stops midway simply halts and keeps all state on both sides — there is no step where you are left without a working control plane.
Look before anything moves
Before a handover can even start, the platform’s assessment — a read-only probe of your cluster — reports a feasibility path and a translation report: the honest list of things that do not follow a control plane across providers (provider-coupled storage classes, cloud load balancers, Cluster-API management). You see the full picture first, from lo kubehz assess or the dashboard.
The honest boundary today
- Eject (hosted → your infrastructure) preserves identity — live today, exactly as described above.
- Adopt (your cluster → hosted) runs as recreation today: the hosted control plane is created fresh, with a new identity, and workloads move by re-applying them. Identity-preserving adopt is planned; until it ships, the docs say “new identity” rather than implying otherwise.
Next steps
- Migration — moving in and out — the step-by-step guide for both directions
- How it works — the hosting × access model handover plugs into
- Hosted control plane — the hosted path itself
Doc status
| Aspect | Detail |
|---|---|
| State | Active — describes the live handover mechanism |
| Last reviewed | 29 July 2026 |