Linked clusters

Link your Homestead clusters - your main site, a branch office, a disaster-recovery site - and manage all of them from any one. Only one needs to be reachable from outside: it relays everything, consoles included, to the others.

Two machines at home

For a home lab with only two machines, prefer one single-node k3s cluster on each, with Homestead installed in both, then link them below. Each cluster can operate independently when the other is down. Two embedded-etcd servers in one cluster require both votes and lose quorum when either machine fails.

Linking is shared management, not an HA cluster: it adds no etcd votes, shared storage replicas or automatic workload failover. Back up each cluster to storage that survives its host. Keep both Homestead addresses available; if the one you usually open is down, open the surviving cluster directly. Planned workload moves and copies are separate workflows, not automatic disaster recovery.

For a single cluster that tolerates one control-plane failure, add a third voting server. A suitable ARM64 Pi with SSD storage is an option on k3s; see two-machine layouts and the small third server.

What you get

• A cluster switch at the start of the top bar. Pick a cluster and the whole app is that cluster's, as if you had opened it directly - your sign-in and your role come with you.
• All clusters in the same switch: Containers, Virtual Machines, Nodes and Volumes from every cluster on one page, each tagged with its cluster. Containers are grouped by cluster, with a chip to show one alone. Anything you do to a row - start, stop, edit, logs, a console - happens on its cluster.
• Move to cluster in a container's or VM's … menu. It opens the other cluster at its review of the move; nothing stops until you start it there.
• Copy to cluster keeps the source and creates a stopped copy on the destination. The source pauses for its backups, then resumes its previous running state while those backups are restored. Review the copied VM's guest network settings before starting it.
• Moving workloads under Settings → Linked clusters: moves under way, and each cluster a move can come from with Browse workloads. See Moving between clusters.

Link a cluster

You need an admin account on the other Homestead, and both should run the same release (or one close to it).

1. Settings → Linked clusters → Link a cluster (or Link a cluster in the switch, once one is linked).
2. Enter the other Homestead's address - what you open it at on your LAN, with the port, e.g. http://192.0.2.250:8088 - and the admin username and password there.
3. Check This Homestead's address: how the other one reaches this one. It starts as this cluster's VIP on port 8088. Until Homestead is on a VIP it is the node's own address; when Homestead moves onto a VIP, or its VIP changes, the linked clusters are told the new one. An address you typed yourself is left as it is.
4. Link.

The password is used once, to sign in and exchange a shared key, and is not kept. From then on the clusters sign every request to each other with that key.

Link a third cluster from either of the first two: it is linked to all of them. A Homestead already linked to others cannot be pulled into a second group - unlink it there first, or link from within its group.

Switching, or all together

Once a cluster is linked, its name appears at the start of the top bar (on a phone, above the page title). Click it for:

• All clusters - every cluster's containers, VMs, nodes and volumes together;
• each cluster by name - that cluster on its own.

Settings → Linked clusters → How they show picks the same thing: One cluster at a time or All clusters together. The dots in the switch say:

• a green dot: the cluster answers;
• red: it does not answer from here - it is off, or its address has changed;
• amber: it runs a release too far from this one to relay; update one of them.

Picking a cluster keeps you on the same page there. To come back, open the switch again - it is on every cluster - and pick the one you signed in to.

If a cluster stops answering while you are on it, Homestead says so and offers a way back.

Updating them together

The Homestead updates dialog (the top bar's Homestead button, or Settings → Updates) lists every linked cluster with its version and any waiting update. Tick Include on each one to update with this one; see Settings. Clusters a release or more apart can still move workloads between them, as long as their link protocol matches.

Roles

You keep the role you have on the cluster you signed in to. Each cluster applies its own rules to that role, so a viewer can look but not change, anywhere. The other cluster records what you do as name@cluster.

Linking itself is an admin decision: every linked Homestead can act as admin on the others, to relay for people and to move workloads.

Migration

Each cluster in Settings → Linked clusters has a Migration button that says whether workloads can move from that cluster to another. It opens Migration from that cluster:

• Enable migration runs that cluster's backup storage - an S3 store (RustFS) on a Longhorn volume - which a move backs volumes up to and the cluster they go to restores them from. The first time, choose its size; it goes on that cluster's shared address at port 9000 unless you choose another port - when an app there already uses 9000 - or give it an address of its own.
• While it is on, the dialog shows the store's address, whether this cluster can reach it, its size, and a fix for anything wrong - an address no other cluster can reach, say.
• Disable migration stops the store and keeps its volume and the backups on it; enabling it again starts it as it was. If that cluster's Longhorn backs up there too, those backups pause while it is off - the dialog says so.

You can manage migration from any linked cluster, for any of them. Below, Moving workloads lists moves under way and each cluster a move can come from, with whether it is ready and Browse workloads.

The move review includes a Destination storage class picker. It offers regular Longhorn classes on the destination and uses the selected class's replica count, disk and node tags, filesystem and mount settings when restoring the volumes. The restored PVC names that configured class directly. Homestead imports the backup as a CSI snapshot, with Retain policy, and removes its import metadata after the PVC binds. The backup itself is kept.

Migrations require an Immediate binding class so disks can restore before the workload starts. Filesystem volumes need a class with migratable disabled; block VM disks may use a migratable class. The review checks these settings. Homestead checks the snapshot controller, snapshot APIs and Longhorn CSI snapshotter before stopping the source. On k3s/RKE2 with a Helm controller, missing snapshot support is installed automatically on Kubernetes 1.25 or newer. Existing platform controllers are used without replacement; Harvester manages its own snapshot support. Installation waits and failures remain in the move log. The chosen class and snapshot request identity survive Homestead restarts.

If a backup fails, use Retry failed backups on the failed move. Homestead requests a fresh snapshot and backup for failed or missing recorded backups, while keeping completed backups and waiting for backups still in progress. It waits for each new snapshot to be ready before requesting its backup. Old backups are retained. Stable request names survive a lost reply or reboot.

The same recovery runs when starting a new attempt after dismissing the old Activity job, including when an older destination's migration record was cleared. Source workload annotations are checked even without that old record. Update Homestead on both clusters for this recovery behavior. If destination objects from a later phase already exist, review the old move and use Put back before starting another; a new move does not overwrite those objects.

Unlink

Settings → Linked clusters (or Manage clusters in the switch) lists every linked cluster:

• Unlink removes one. It keeps running as it is. The rest get a new key, so the one unlinked can no longer act for them.
• Leave unlinks this Homestead from the others, which stay linked to each other.
• Where the others reach this Homestead changes this one's address - after a new VIP, say. The others hear straight away.

Clusters added before linking

Clusters added on Import for moves in earlier releases - with an account and password kept here - are listed under Settings → Linked clusters → Added before linking. Link links each with that account, then deletes the password; moves that named it keep working. Forget deletes the account and leaves the cluster alone. One already linked under another name offers Use the link instead.

Security

• Every request between clusters is signed, carries the time, and is used once: it cannot be altered or replayed.
• The shared key lives in a Kubernetes Secret, homestead-fleet-key, in Homestead's namespace on each cluster.
• Requests between clusters travel over the address you give. On a LAN you do not trust, give each cluster an https:// address.

Troubleshooting

"not answering" - open the cluster's own address from a browser on the LAN. If it works there, its address in Manage clusters may be out of date: set it on that cluster, under Where the others reach this Homestead.

"the clocks differ by more than five minutes" - signed requests carry the time. Set NTP on the hosts.

A cluster that was unlinked while off still lists the others. Unlink it there too (Leave), then link it again if you want it back.