How to add a Ceph monitor with cephadm

Monitor quorum is the control plane that lets a Ceph cluster agree on maps, authentication, and daemon membership. Adding another monitor with cephadm improves tolerance for host maintenance or failure when the new daemon is placed on a managed host in the monitor network.

Cephadm manages monitors through the mon service specification. A monitor placement update must describe the full intended monitor set, because each ceph orch apply mon request replaces the previous placement request instead of appending one host to it.

Start from an administration host that already has Ceph admin credentials and an enrolled host such as ceph-node2 ready for monitor placement. Keep monitor daemons on the public monitor network, preview the placement before applying it, and verify both the cephadm daemon table and monitor quorum before treating the cluster as ready for maintenance.

1. Check cluster health before changing monitor placement.

   $ ceph -s
     cluster:
       id:     11111111-2222-3333-4444-555555555555
       health: HEALTH_OK
   
     services:
       mon: 2 daemons, quorum ceph-admin,ceph-node1 (age 2h)
       mgr: ceph-admin.abc123(active, since 2h)
       osd: 6 osds: 6 up, 6 in
   
     data:
       pools:   4 pools, 256 pgs
       objects: 3.42M objects, 8.1 TiB
       usage:   24 TiB used, 76 TiB / 100 TiB avail
       pgs:     256 active+clean

   Start from a named health state so the monitor change is not hiding an unrelated OSD, placement group, or manager issue.
   Related: How to check Ceph cluster health

2. Confirm that the target host is already enrolled in cephadm.

   $ ceph orch host ls
   HOST        ADDR          LABELS  STATUS
   ceph-admin  192.0.2.10    _admin
   ceph-node1  192.0.2.11
   ceph-node2  192.0.2.12

   Add the host first when the target hostname is missing. Cephadm monitor placement can only use hosts already known to the orchestrator.
   Related: How to add a host to a Ceph cluster with cephadm

3. Check the monitor public network.

   $ ceph config get mon public_network
   192.0.2.0/24

   Cephadm deploys new monitor daemons only on hosts with addresses in the monitor public network. The sample host ceph-node2 uses 192.0.2.12, so it matches 192.0.2.0/24.

4. Set the monitor public network only when the current value does not include the target host.

   $ ceph config set mon public_network 192.0.2.0/24

   Changing public_network affects where future monitors may run. Use the real storage public network, not the documentation placeholder range shown here.

5. Export the current mon service spec before changing placement.

   $ ceph orch ls --service_type mon --export > mon-placement-before.yaml

   The exported YAML gives a review and rollback reference if the new placement needs to be adjusted.
   Related: How to manage Ceph services with cephadm

6. Preview the complete monitor placement.

   $ ceph orch apply mon --placement="ceph-admin,ceph-node1,ceph-node2" --dry-run

   The placement string includes the existing monitor hosts and the new monitor host. Do not preview only ceph-node2 unless the intended final state is a single monitor.

7. Apply the monitor placement without the dry-run flag.

   $ ceph orch apply mon --placement="ceph-admin,ceph-node1,ceph-node2"
   Scheduled mon update...

   A ceph orch apply mon command supersedes the previous mon placement. Include every monitor host that should remain in service.

8. Wait for the new monitor daemon to report running.

   $ ceph orch ps --daemon_type mon --refresh
   NAME              HOST        PORTS        STATUS   REFRESHED  AGE   VERSION
   mon.ceph-admin    ceph-admin  *:6789,3300  running  4s ago     14d   20.2.2
   mon.ceph-node1    ceph-node1  *:6789,3300  running  4s ago     14d   20.2.2
   mon.ceph-node2    ceph-node2  *:6789,3300  running  4s ago     1m    20.2.2

   --refresh asks cephadm to update cached daemon state before printing the table. Wait until the new mon.ceph-node2 row shows running before checking quorum.

9. Verify that the new monitor joined quorum.

   $ ceph quorum_status --format json-pretty
   {
       "election_epoch": 42,
       "quorum": [
           0,
           1,
           2
       ],
       "quorum_names": [
           "ceph-admin",
           "ceph-node1",
           "ceph-node2"
       ],
       "quorum_leader_name": "ceph-admin",
       "monmap": {
           "epoch": 18,
           "mons": [
   ##### snipped #####
           ]
       }
   }

   The quorum_names list should include the new monitor hostname. If it does not, inspect the cephadm event stream and the monitor container on that host before changing placement again.

10. Confirm final cluster health after quorum settles.

    $ ceph -s
      cluster:
        id:     11111111-2222-3333-4444-555555555555
        health: HEALTH_OK
    
      services:
        mon: 3 daemons, quorum ceph-admin,ceph-node1,ceph-node2 (age 1m)
        mgr: ceph-admin.abc123(active, since 2h)
        osd: 6 osds: 6 up, 6 in
    
      data:
        pools:   4 pools, 256 pgs
        objects: 3.42M objects, 8.1 TiB
        usage:   24 TiB used, 76 TiB / 100 TiB avail
        pgs:     256 active+clean

    If health changes to HEALTH_WARN or HEALTH_ERR, keep the monitor placement open until the named health checks explain the change.