What is ceph-volume?

ceph-volume is the modern command‑line tool used by Ceph to discover, create and manage Object Storage Daemons (OSDs). It replaces the older ceph-disk utility and provides a more consistent interface for preparing block devices, formatting them with the chosen filesystem, and registering them as OSDs within a Ceph cluster.

When should you use it?

• When you are initially provisioning OSDs on new hardware.
• When you need to re‑prepare an existing device (e.g., after a filesystem corruption or a change of journal/SSD type).
• When you want to inspect the current OSD layout or gather detailed information about a device’s configuration.

Prerequisites

1. Ceph cluster already deployed (monitor nodes, manager, etc.).
2. Root privileges on the host where you intend to run the command.
3. A block device that is either empty or can be safely wiped (all data will be destroyed).
4. The device must be visible to the OS (e.g., /dev/sdb, /dev/nvme0n1p1).

NOTE: Always double‑check the device name. Selecting the wrong disk will result in data loss.

Basic workflow

1. List available devices

ceph-volume lvm list

or, for raw block devices:

ceph-volume lvm list --block

The output shows each candidate device together with its current state (e.g., available, in use, failed).

2. Prepare the device

a) Using LVM (default)

ceph-volume lvm prepare /dev/sdb

This command will:

• Wipe the device (if needed).
• Create a physical volume (PV).
• Create a volume group (VG) named ceph-.
• Create a logical volume (LV) for the OSD data, journal (if using bluestore), and any required metadata.

b) Using bluestore (default for Ceph ≥ 12.2)

ceph-volume lvm create --bluestore /dev/sdb

The command automatically partitions the disk (GPT) and creates the required sub‑volumes.

c) Using filestore (legacy)

ceph-volume lvm create --filestore /dev/sdb

NOTE: Filestore is still supported but is being phased out in favour of bluestore.

3. Format the OSD

After preparation, the OSD must be formatted:

ceph-volume lvm format /dev/ceph--

The command detects the filesystem type (bluestore or filestore) automatically.

4. Activate the OSD

ceph-volume lvm activate /dev/ceph--

Alternatively, you can let ceph-volume handle activation automatically by omitting this step; the prepare command already registers the OSD with the cluster.

5. Add the OSD to the cluster

ceph osd pool create   
ceph osd set-device-class 
ceph osd tree

Or simply let Ceph discover the new OSD:

ceph osd reweight  1.0

6. Verify the OSD

ceph osd stat
ceph osd tree
ceph osd df

These commands confirm that the OSD is up, in, and reporting the correct capacity.

Advanced options

Common pitfalls and how to avoid them

• Wrong device selected – Always run ceph-volume lvm list first and verify the output.
• Insufficient permissions – Run all ceph-volume commands with sudo or as root.
• Existing data on the disk – Use --destroy (if available) or manually wipefs before preparation.
• Incompatible block size – Ensure the device uses a 4 KiB sector size for optimal performance with bluestore.
• Failure to update ceph.conf – If you change the OSD device class, update the [osd] section accordingly.

Checking the status of an existing OSD

ceph-volume lvm list --show-device-ids

or, for a specific OSD:

ceph-volume lvm get 

These commands display the underlying block device, LV path, and any custom naming you applied.

Removing an OSD

When an OSD must be retired:

ceph osd out 
ceph osd purge  --yes-i-really-mean-it

Then, on the host:

ceph-volume lvm deactivate /dev/ceph--
lvremove /dev/ceph--

Finally, wipe the underlying block device if you plan to reuse it.

Summary checklist

1. Identify the target block device (ceph-volume lvm list).
2. Prepare it (ceph-volume lvm prepare or create).
3. Format the OSD (ceph-volume lvm format).
4. Activate it (ceph-volume lvm activate – optional).
5. Register with Ceph (ceph osd … or let Ceph auto‑discover).
6. Verify (ceph osd stat, ceph osd df).
7. Monitor for any errors in the Ceph logs (/var/log/ceph/ceph-osd..log).

By following these steps you can reliably add new storage capacity to a Ceph cluster using the modern ceph-volume tool, ensuring consistency, safety, and ease of management.