Ceph Cluster Health

Detect loss of quorum, missing monitors, an unavailable manager and placement group problems in your Ceph cluster.

The Ceph Cluster Health check detects missing monitors, loss of quorum, an unavailable manager and placement group problems, and also evaluates Ceph health codes. It runs on Linux hosts in the cluster, every 10 minutes by default.

Ceph Cluster Health details in the Check Library showing the Require Ceph on this device and Alert on quorum leader only toggles and the Ignored health codes field.

Prerequisites

The octoja agent runs directly on a Linux host in the cluster (x64 or ARM64).
ceph is executable. The agent can read /etc/pve/ceph.conf or /etc/ceph/ceph.conf and an admin keyring at /etc/pve/priv/ceph.client.admin.keyring or /etc/ceph/ceph.client.admin.keyring.
You can assign checks to the device. Configuration packages require Monitoring Check Management.

Steps

Add Ceph Cluster Health under Checks on the host. Use a configuration package for multiple hosts.
Enable Require Ceph on this device if the host must provide Ceph.
When monitoring multiple nodes, leave Alert on quorum leader only enabled. Assign the check to the leader as well; an OK result on another node does not replace its result.
Under Ignored health codes, enter only deliberately excluded Ceph codes, separated by commas. Spelling is case-sensitive, for example MON_DISK_LOW.
Save and open the result after the first run. Check MON quorum, Manager, Placement groups and the open health checks.

Settings

Field	Type	Required	Default	Description
Require Ceph on this device	Toggle	No	Off	Report missing Ceph as Critical instead of OK
Alert on quorum leader only	Toggle	No	On	Other identified nodes display cluster state with an overall OK result
Ignored health codes	Text	No	Empty	Exclude exact, comma-separated Ceph health codes from evaluation

Ignored health codes suppress those specific Ceph messages. The additional quorum, manager and placement group checks remain active. Use exclusions only when you assess the excluded message separately.

Results

Condition	Result
Non-ignored Ceph code with `HEALTH_ERR`	Critical
Other non-ignored Ceph health code	Warning
No MON majority or no MON present	Critical
Some MONs are missing but a majority remains	Warning
Manager unavailable or inactive placement groups	Critical
Not all placement groups are `active+clean`, but none is inactive	Warning

If Ceph is missing, the default result is OK without evaluating the cluster. If Ceph is configured but a required query fails, the check reports Critical – even with leader selection enabled. Check cluster connectivity and read permissions for the configuration and keyring.

To receive notifications about problems, configure alerting.

Was this helpful?

Still need help? Ask the team