Skip to main content
RunBook Academy

← All break/fix scenarios in Ceph

intermediateceph-rbd~18 min

RBD image unavailable - features mismatch or client cannot connect

Reported symptoms

  • ●rbd map fails with image uses unsupported features
  • ●rbd ls fails with permission denied
  • ●A VM RBD image does not map

Evidence

  • · rbd info <image> shows the image features
  • · ceph -s reports HEALTH_OK
  • · journalctl -u ceph-osd@X shows auth / version mismatch
Diagnosis and resolutionclick to reveal

Root cause

An RBD image uses features the client kernel does not support, or the client cannot authenticate.

Remediation

If features mismatch: rbd feature disable <image> <feature> or upgrade the client. If auth: check the keyring and the cephx caps.

Verification

rbd map succeeds; the VM reads and writes the image; the cluster is HEALTH_OK.

Prevention

Standardise RBD features across the cluster; maintain a single client version baseline; test new features in staging first.

Architecture

The student examines the broken architecture diagram and identifies the responsible component. The cluster is running Ceph Tentacle (20.2.x); the incident is one a production operator must diagnose from the evidence presented.

Symptoms

  • rbd map fails with image uses unsupported features
  • rbd ls fails with permission denied
  • A VM RBD image does not map

Evidence

  • rbd info <image> shows the image features
  • ceph -s reports HEALTH_OK
  • journalctl -u ceph-osd@X shows auth / version mismatch

Student investigation

The student follows the methodology: define the symptom, determine the impact, gather evidence, identify the component, form a hypothesis, test safely, restore, validate.

Progressive hints

  • Hint 1: check the cluster state with ceph -s first.
  • Hint 2: read ceph health detail and identify the affected PGs / OSDs / daemons.
  • Hint 3: use ceph osd tree, ceph pg dump, or ceph mds stat as the next-level diagnostic.
  • Hint 4: the root cause is documented in the frontmatter root_cause field.

Validation

The student runs the verification steps and confirms the symptom cleared.

Root cause

See the frontmatter root_cause field.

Remediation

Apply the fix from the frontmatter remediation field.

Prevention

Apply the prevention measures from the frontmatter prevention field.