Deployment models — cephadm and what it replaced

Intermediate⏱ ~15 mincephadmceph

What you'll learn

Explain what cephadm manages and how it manages it
Contrast cephadm with ceph-deploy, ceph-ansible, and manual deployment
Read and write a cephadm service specification
Decide between cephadm and Rook for a given environment

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

Ceph has had several deployment tools and the older ones still appear in blog posts and tutorials. Using them on a current release produces a cluster that the supported tooling cannot manage, which is a problem discovered late and expensive to unwind.

What cephadm is

cephadm deploys and manages Ceph daemons as containers, orchestrated through the MGR orchestrator module. It:

connects to hosts over SSH using a key it manages,
pulls container images and runs daemons under systemd,
maintains the desired state described by service specifications,
handles upgrades by rolling daemons one at a time in a safe order.

The last two points are the substantive difference. cephadm is declarative: you describe what should exist and it reconciles.

cephadm bootstrap --mon-ip 10.0.1.10
ceph orch host add ceph-02 10.0.1.11
ceph orch apply mon --placement="3 ceph-01 ceph-02 ceph-03"
ceph orch apply osd --all-available-devices
ceph orch ls
ceph orch ps

Service specifications

The declarative interface is a YAML spec:

service_type: osd
service_id: nvme-osds
placement:
  host_pattern: 'ceph-*'
spec:
  data_devices:
    rotational: false
  db_devices:
    rotational: true
  osds_per_device: 2

ceph orch apply -i osd-spec.yaml

Applying it means any host matching the pattern with unused non-rotational devices gets OSDs created automatically, including hosts added later. That is the property worth understanding: specs are standing instructions, not one-time commands.

An OSD spec keeps creating OSDs after you stop watching

Because ceph orch apply records intent, a spec matching all-available-devices will claim any new device that appears — including a replacement disk inserted for a different purpose, and including devices on hosts added months later.

This is usually what you want during a build and rarely what you want afterwards. Either write specific specs with explicit device filters, or pause the orchestrator’s OSD creation:

ceph orch apply osd --all-available-devices --unmanaged=true

Check ceph orch ls for what is currently managed before adding hardware to an existing cluster.

What it replaced

Tool	Status	Why not to use it
`ceph-deploy`	removed	unmaintained; removed from recent releases
`ceph-ansible`	superseded	still exists but cephadm is the supported path
manual / packages	possible	no orchestration, no upgrade automation, error-prone
Rook	current	for Kubernetes-native deployments

ceph-deploy in particular appears in a great deal of older documentation. It was deprecated in Reef and is gone; instructions using it will not work and should not be adapted.

Why containers, and what that changes operationally

Running daemons as containers pins each one to a specific Ceph version independently of what is installed on the host. That is what makes rolling upgrades safe: cephadm can run an OSD on the new version while its neighbours are still on the old one, verify health, and continue.

The operational consequences are worth knowing. Logs go to the container’s journal, reached with cephadm logs --name osd.12 rather than a file in /var/log/ceph. Debugging tools must be run inside the container with cephadm shell or cephadm enter. And the host needs a container runtime — podman or docker — which becomes a dependency of the storage system.

The trade is generally favourable: version isolation and automated upgrades are worth more than direct log-file access, and cephadm logs is a thin wrapper over journalctl rather than a real obstacle.

cephadm or Rook

Use cephadm for clusters on bare metal or VMs, where Ceph is the primary purpose of the hosts. It is the reference deployment method and the one the documentation assumes.

Use Rook when Ceph runs inside Kubernetes and should be managed by Kubernetes primitives — operators, CRDs, and the same control plane as the workloads. It is a genuine alternative rather than a lesser one, but it makes Kubernetes a dependency of the storage layer, which is a consideration when the storage also serves that Kubernetes cluster.

Quiz

Knowledge check · 4 questions

Q1. What does ceph orch apply osd --all-available-devices do that a one-time command would not?

It creates the OSDs in parallel across every host rather than serially, so a build finishes sooner It validates that each device has power-loss protection before accepting it as an OSD It creates the OSDs with BlueStore, where a one-time command would still use FileStore It records standing intent, so future devices and future hosts also get OSDs automatically
Q2. Because cephadm pins each daemon to a container image, a cluster mid-upgrade runs some daemons on the new version and their neighbours on the old one at the same time.

True False
Q3. A team adds three new hosts to a cephadm cluster intending to use their NVMe devices for a separate fast pool. Within minutes OSDs appear on all devices including SATA disks meant for something else. Explain.

Existing cluster deployed with ceph orch apply osd --all-available-devices during the initial build eighteen months ago. Three new hosts were added with ceph orch host add. Each has 2 NVMe and 10 SATA SSDs. The plan was to create NVMe OSDs manually and leave the SATA devices for a later decision. All 36 devices now have OSDs and data is rebalancing onto them.
Q4. Explain why cephadm runs daemons as containers and what that changes for day-to-day operations.

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

Production discipline

Treat ceph orch apply as recording standing intent rather than performing a one-time action, and check ceph orch ls before adding hosts or devices to an existing cluster — a broad OSD spec turns a host addition into an act of provisioning. Prefer explicit specs with device filters over --all-available-devices once the build is done. And ignore documentation that uses ceph-deploy: it has been removed, and instructions written around it lead to clusters the supported tooling cannot manage.

Cross-course references

Ceph: Part XLIX (cephadm) for the full command surface.
Ceph: Part L (Cluster Deployment) for a build from scratch.
Ceph: Part LXXXIX (Rook Concepts) for the Kubernetes-native alternative.