Adding a host to the cluster

Intermediate⏱ ~17 mincephcephadm

What you'll learn

Prepare a host for adoption
Add it to the cluster correctly
Place it in the CRUSH hierarchy
Verify before adding OSDs

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

A host added without correct CRUSH placement produces data distribution that looks right and is not.

Preparing the host

# on the new host
cephadm check-host

podman|docker (/usr/bin/podman) is present
systemctl is present
lvcreate is present
Unit chrony.service is enabled and running
Host looks OK

# from the cluster
ceph cephadm get-pub-key > /tmp/ceph.pub
ssh-copy-id -f -i /tmp/ceph.pub root@ceph-04
ceph cephadm check-host ceph-04 10.0.2.24

Prerequisite	Check
Container runtime	`cephadm check-host`
Time synchronised	`chronyc tracking`
SSH key installed	`ceph cephadm check-host`
Network reachable on both networks	`ping`, `ping -M do`
Firewall permits Ceph ports	connectivity test
Devices available	`ceph orch device ls` after adding

Adding it

ceph orch host add ceph-04 10.0.2.24 --labels osd
ceph orch host ls

# verify it is managed
ceph orch host ls --detail
ceph orch ps --hostname ceph-04

Labels determine which service specifications place daemons on it, so labelling correctly at addition is what makes the deployment automatic.

CRUSH placement

# where did it land?
ceph osd tree | grep -B2 -A2 ceph-04

A newly added host appears under the default root. If the cluster uses a rack or zone hierarchy, it must be moved:

ceph osd crush move ceph-04 rack=rack2
ceph osd tree

Moving the host before adding OSDs means no data movement.
Moving it after means the OSDs' data relocates.

This is the sequencing that matters most: place the host in the hierarchy before its OSDs hold any data.

Verification before adding OSDs

# the host is in the right place
ceph osd tree | grep -A3 rack2

# networks are reachable
ping -M do -s 8972 -c 2 10.0.2.24
ping -M do -s 8972 -c 2 10.0.3.24

# devices are visible and available
ceph orch device ls ceph-04 --wide

# and the cluster is ready
ceph -s

Five checks before any data commits to the host.

Quiz

Knowledge check · 4 questions

Q1. Why must a new host be moved into the CRUSH hierarchy before adding its OSDs?

CRUSH refuses to move a bucket that already holds OSDs, so the host must be placed while it is empty Orchestrator labels are resolved against the CRUSH position, so a host left under the default root is given entirely the wrong labels Device class detection reads the CRUSH position of the host, so devices are misclassified under the default root OSDs added under the default root hold data there; moving the host afterwards relocates all of it in a second full rebalance
Q2. Verifying MTU on the public network is sufficient for a new host.

True False
Q3. Add a host to a rack-aware cluster.

A new host is ready to join a cluster that uses a rack-level failure domain. It has twelve drives to be added as OSDs.
Q4. What does labelling a host at addition time accomplish?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Move a new host into its CRUSH position before adding any OSDs — the move is free beforehand and a full rebalance afterwards. Verify MTU and reachability on both the public and cluster networks separately; an asymmetry produces an OSD that serves clients and cannot backfill.

Cross-course references

Kubernetes: labelling a node before workloads land on it avoids rescheduling
Linux: placing a device in its final configuration before populating it saves the migration