Learn MicroCloud - Joining: microcloud join

#Introduction

Your cloud already has a foundation: microcloud init in episode 4 formed the cluster from the first node. But a real cloud needs more than one node — it needs other members so HA, replication, and scheduling actually work. In episode 5 we add nodes with microcloud join, understand the trust mechanism between members, and verify the entire cluster.

Think of init as founding a company: one director (the first node) forms its legal entity. Join is like bringing in partners — each brings capital (OSD disks) and assets (compute/network), and everyone follows the same rules. Without enough members (at least 3 nodes), joint decisions — quorum — can't be reached.

#Running microcloud join

#From the Second and Third Nodes

On node-b and node-c, run the same command:

sudo microcloud join

Join must run at the same time as the init session waiting on the first node (remember the "Waiting for other nodes to join" prompt from episode 4). The MicroCloud on the joining node will scan the network, find the node that's initializing, and offer itself as a member.

> Scanning for servers on the network...
  Found: node-a (192.168.1.10) initializing a cluster
  Join this cluster? (yes/no) [default=yes]

After agreeing, the MicroCloud on the new node will ask the same storage and network questions as during init — select the empty disk dedicated to that node, and the correct underlay interface. Finally, on the first node, you'll see the list of peers requesting to join and be asked to approve them (or they're already trusted automatically via proactive trust on version 2.1+).

#The Correct Sequence

The ideal multi-node process:

1. microcloud init on node-a — choose storage/network, wait for peers.
2. microcloud join on node-b — choose storage/network, agree to join.
3. microcloud join on node-c — the same.
4. On node-a, confirm all peers — the cluster is complete.

node-a  [initializer] ──┐
node-b  [join] ─────────┼──► LXD cluster (3 member)
node-c  [join] ─────────┘    + Ceph OSD 3x + OVN

#Trust Mechanism and Join Tokens

#How Members Are Trusted

Every LXD node has its own certificate. When joining, the new node sends its certificate to the cluster; the cluster only "trusts" that node after:

• Manual confirmation: the node running init shows the peers and you approve them, or
• Proactive trust: since MicroCloud 2.1, you can mark trusted nodes before the join, so no approval prompt appears (we cover this in episode 15).

Behind the scenes, this process generates a join token — a one-time token linking the new node's certificate to the LXD cluster. This is similar to an SSH handshake: the new node must prove its identity, and the cluster ensures only invited nodes join.

#Local Peer vs Remote

By default, MicroCloud discovers nodes via mDNS on the local network. For nodes on a different network (e.g., a separate edge site), MicroCloud supports remote peers — you can add a peer address manually so nodes don't need to be on the same subnet. This matters for cross-site cluster design (episode 14).

#Cluster Verification

#LXD Members

lxc cluster list

The output shows each member, its address, role, and status. In a 3-node cluster, one member becomes the leader (the database-leader role) holding the cluster's consistent database.

#Ceph Status

microceph status

Make sure all OSDs show HEALTH_OK or at least no OSD down. If an OSD from a newly joined node hasn't appeared, check that the empty disk was selected during the join.

#OVN Status

microovn status

The output shows the OVN cluster, its members, and the underlay interface in use. All nodes must be registered here.

#One-Command Summary

microcloud status

This command combines the LXD, Ceph, and OVN views into a single display — from now on this is your first "dashboard" (we level it up with Cluster Manager and Grafana in episodes 12 and 20).

#Advanced Multi-node Scenarios

#Adding Nodes Later

Join doesn't have to happen at the same time as init. A running cluster can accept new nodes at any time:

sudo microcloud join

The new node will find the existing cluster and join as an additional member. This is the foundation of scaling, which we cover fully in episode 11.

#One Node Fails to Join

If a node fails to join (e.g., its disk isn't empty or the network is wrong), the cluster still forms from the nodes that succeeded. You can try joining that node again, or remove it from the peer list on the first node.

#Common Pitfalls

• "No peer found" when joining: make sure init is still running on the first node and the firewall isn't blocking mDNS (UDP 5353).
• Node doesn't appear in lxc cluster list: check the logs with snap logs microcloud on the joining node (episode 16).
• Certificate rejected: re-confirm the peers on the first node, or use proactive trust.
• Duplicate hostname: MicroCloud rejects a member with the same hostname as another member — verify in episode 3.

#Closing

Key takeaways:

• microcloud join on other nodes merges them into the initialized cluster.
• Join requires consistent per-node storage/network choices and peer approval (manual or proactive trust).
• A join token securely links a new node's certificate to the LXD cluster.
• Full verification: lxc cluster list, microceph status, microovn status, and microcloud status.
• Join can happen during init or later to add nodes (scaling).

In the next episode, we'll dissect storage: MicroCeph — how OSDs form from empty disks, the RBD pool for instance block devices, CephFS for files, and RGW for S3 objects, replication for HA, microceph disk add, placement groups, and optional disk encryption. This is the heart of your cloud's data.