How handover works
Handover moves a cluster between kubehz’s hosted control plane and infrastructure that you own. It is the mechanism behind the no-lock-in promise. This page explains the idea. For the step-by-step guide, see Migration: moving in and out.
A cluster is its identity, not its servers
Take a Kubernetes cluster apart, and only a few things make it that cluster:
- the certificate authority that every node and kubeconfig trusts,
- the service-account signing keys that sign every workload token,
- the encryption key that protects Secrets at rest,
- and the data: every API object, in etcd.
You can replace the servers that run the control plane. You cannot replace the identity. Move the identity and the data, and the cluster stays the same cluster, wherever its control plane runs. That is the whole trick: handover moves the identity, not the machines.
Restore-based, on boring foundations
Handover uses proven mechanisms on purpose, not clever ones:
- The platform assembles an export bundle (the identity above) and takes a fresh etcd snapshot.
- On your target machine, the bundle seeds the identity before the new control plane initializes, and a restore loads the snapshot.
- The standard Kubernetes bootstrap then reuses the seeded identity instead of minting a new one.
The result comes up as your cluster: same CA, same keys, same objects. Your workers already trust it, so they reconnect and carry on. There is no live wire transfer between control planes and no custom replication protocol: only a snapshot and a restore, and you can audit every step.
You are the gate
Handover is not fully automatic, on purpose. Two moments belong to you:
- Cutover: you point the cluster’s endpoint DNS at the new control plane, and the platform waits for your explicit confirmation. Until then, nothing destructive happens.
- Decommission: the platform removes the old control plane only after the platform sees the new one alive (heartbeating) and you confirm a second time. Until both happen, the old side stays intact as your fallback.
If a handover stops midway, it halts and keeps all state on both sides. No step leaves you without a working control plane.
Look before anything moves
Before a handover can start, the platform’s assessment (a read-only probe of your cluster) reports a feasibility path and a translation report. That report is 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 the identity. It is live today and works exactly as described above.
- Adopt (your cluster → hosted) runs as a recreation today: kubehz creates the hosted control plane fresh, with a new identity, and you move the workloads by applying them again. Identity-preserving adopt is on the roadmap. Until it ships, the docs say “new identity” and imply nothing else.
Next steps
- Migration: moving in and out: the step-by-step guide for both directions
- How it works: the hosting × access model that handover plugs into
- Hosted control plane: the hosted path itself
Doc status
| Aspect | Detail |
|---|---|
| State | Active: describes the live handover mechanism |
| Last reviewed | 30 October 2026 |