Skip to main content
RunBook Academy

CephXLIX · cephadmcephadm

Bootstrapping a cluster with cephadm

Intermediate⏱ ~17 mincephadmceph

What you'll learn

  • Run cephadm bootstrap with appropriate options
  • Explain what bootstrap creates
  • Verify a successful bootstrap
  • Recover from a failed bootstrap

Prerequisites

  • A
  • h
  • o
  • s
  • t
  • w
  • i
  • t
  • h
  • a
  • s
  • u
  • p
  • p
  • o
  • r
  • t
  • e
  • d
  • c
  • o
  • n
  • t
  • a
  • i
  • n
  • e
  • r
  • r
  • u
  • n
  • t
  • i
  • m
  • e
  • ,
  • P
  • y
  • t
  • h
  • o
  • n
  • 3
  • ,
  • c
  • h
  • r
  • o
  • n
  • y
  • s
  • y
  • n
  • c
  • h
  • r
  • o
  • n
  • i
  • s
  • e
  • d
  • ,
  • a
  • n
  • d
  • a
  • s
  • t
  • a
  • t
  • i
  • c
  • I
  • P
  • o
  • n
  • t
  • h
  • e
  • i
  • n
  • t
  • e
  • n
  • d
  • e
  • d
  • p
  • u
  • b
  • l
  • i
  • c
  • n
  • e
  • t
  • w
  • o
  • r
  • k
  • .

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

Not yet marked complete on this device.

Why this matters in production

Bootstrap creates the cluster identity, the first monitor, and the SSH trust the orchestrator uses for everything afterwards. Several of its choices — the cluster network, the initial dashboard credentials, the SSH key — are awkward to change later, so the flags are worth reading before running it.

The command

cephadm bootstrap \
    --mon-ip 10.20.0.10 \
    --cluster-network 10.30.0.0/24 \
    --initial-dashboard-user admin \
    --initial-dashboard-password "$(cat /root/dash.pw)" \
    --dashboard-password-noupdate \
    --ssh-user cephadm \
    --allow-fqdn-hostname \
    --log-to-file
FlagWhy
--mon-iprequired; the public network is inferred from it
--cluster-networkset here or you will configure it afterwards
--initial-dashboard-*avoids a generated password printed to the terminal
--ssh-useruse a dedicated account rather than root
--allow-fqdn-hostnameif hosts use FQDNs, which is common
--log-to-filedaemon logs to files as well as journald

What it creates

  1. A cluster FSID and /etc/ceph/ceph.conf
  2. The first monitor and manager, as containers
  3. client.admin and its keyring at /etc/ceph/ceph.client.admin.keyring
  4. An SSH keypair, with the public key added to the bootstrap host
  5. The _admin label on the bootstrap host
  6. Monitoring services — Prometheus, Grafana, alertmanager, node-exporter
ceph -s
ceph orch ls
ceph orch ps
cephadm ls

Verifying

ceph status
# should show 1 mon, 1 mgr, HEALTH_WARN (no OSDs yet)

ceph orch status
# Backend: cephadm
# Available: Yes

ceph cephadm get-pub-key
ceph config get mon public_network
ceph config get mon cluster_network

HEALTH_WARN immediately after bootstrap is expected — there are no OSDs and no pools.

If bootstrap fails

FSID=3e0b2c14-9f3a-4d21-8a77-1c9f0e2b5d64
cephadm rm-cluster --force --zap-osds --fsid ${FSID}

This removes everything bootstrap created on the host. Take the FSID from the failed run’s output or from /etc/ceph/ceph.conf before removing it.

Common causes: the container runtime not working, time not synchronised, --mon-ip not present on the host, or a hostname that does not resolve.

Quiz

Knowledge check · 4 questions

  1. Q1. Why should `--cluster-network` be set at bootstrap rather than afterwards?

  2. Q2. HEALTH_WARN immediately after a successful bootstrap indicates a problem.

  3. Q3. Prepare a bootstrap for a production cluster.

    A new production cluster will use a separate cluster network, hosts identified by FQDN, and a dedicated non-root account for orchestration. A colleague is about to run `cephadm bootstrap --mon-ip 10.20.0.10` with no other flags.

  4. Q4. Why does an SSH problem present as an orchestrator problem in cephadm?

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

Production discipline

Set the cluster network, SSH user, and dashboard credentials at bootstrap rather than afterwards; each is a decision the bootstrap host makes for free and every other host inherits. Verify time synchronisation and the container runtime before running bootstrap — both produce failures that are confusing to diagnose after the fact.

Cross-course references

  • Kubernetes: kubeadm init makes similarly durable choices in one command
  • Linux: initial system provisioning decisions that outlive the install are a recurring pattern