Troubleshoot an RBD client

This runbook covers Troubleshoot an RBD client on a Ceph Tentacle cluster.

When to use

• Active production scenario matching the impact (service-affecting)
• The prerequisites are met

Prerequisites

Before starting this runbook, verify each prerequisite has been met. If a prerequisite is not met, resolve it first or escalate.

• An RBD client cannot map an image
• A VMs RBD image is inaccessible

Pre-checks

Collect evidence before taking action. Evidence is the proof the runbook worked.

# rbd ls `<pool>` shows the image
# rbd info shows the image features
# ceph -s reports HEALTH_OK
# The RBD client kernel module is loaded

Procedure

Step 1

Run rbd map with —debug

Step 2

Inspect dmesg

Step 3

Verify the keyring

Step 4

Verify network connectivity

Step 5

Verify the RBD feature compatibility

Step 6

Try an unmount + remount

Step 7

If kernel client fails: try rbd-nbd

Verification

After completing the procedure, verify the result:

# rbd map succeeds
# The VMs disk is readable
# The client latency is acceptable

Rollback

If the procedure does not produce the expected verification, roll back:

• If the image is corrupt: see ceph-rb-replace-osd
• If the auth fails: see ceph-rb-investigate-mon-quorum
• If the network is congested: see ceph-rb-investigate-network

Escalation

If you cannot roll back or the rollback fails, escalate:

• Storage team
• Hypervisor team if Proxmox / QEMU is failing