Skip to content

Ceph

The Ceph extension connects your Ceph clusters to Kunobi through the Ceph Manager Dashboard REST API. Register a cluster with its dashboard URL and a dashboard username and password, and you can browse its health and capacity, hosts, OSDs, pools, RBD block images with their snapshots, trash and namespaces, the cluster/audit/dashboard log, and - when the dashboard proxies Prometheus and AlertManager - its alerts, alerting rules and silences.

It is mostly a read view, refreshed on a background poll. On top of that it ships a focused set of writes: pool create, edit and delete; RBD image create, edit, resize, trash and permanent delete; snapshot create, protect, clone, rollback and delete; trash restore and purge; and RBD namespace create and delete.

Everything talks to the Manager Dashboard API only. There is no SSH, no ceph CLI, and no direct MON/OSD access - if a capability is missing from your dashboard (or your dashboard user lacks the permission for it), it is missing here too.

Ceph is a Pro feature - without a Pro license the Sources workspace is replaced by a "Cluster sources" upgrade notice reading "Upgrade to Kunobi Pro to connect and manage cluster sources.", and the data views show "Ceph requires a Pro license". See Plans & Pro.

Keyboard shortcuts are macOS-first on this page; on Windows/Linux replace with Ctrl and with Alt. is Backspace.

Setup

  1. Install the Ceph extension from Settings → Extensions (see Extensions). It starts automatically. If you open a Ceph view while the extension isn't running, Kunobi shows a "Ceph extension required" notice with "Enable the Ceph extension to manage clusters."
  2. Make sure the Ceph Manager Dashboard is enabled on the cluster (ceph mgr module enable dashboard) and reachable from the machine running Kunobi over HTTP or HTTPS.
  3. Have a dashboard user ready. A read-only user is enough for browsing; the write actions need the matching dashboard permissions (pools, block images, and so on). Everything Kunobi does is done as that user.
  4. Optional: the observability views ride the dashboard's passthroughs, and each is gated on its own. Alert Rules needs ceph dashboard set-prometheus-api-host; Alerts and Alert Silences are proxied to AlertManager and need ceph dashboard set-alertmanager-api-host. A view whose passthrough is missing stays empty, and nothing else is affected.

Managing Clusters

  1. Click Sources in the left navigation bar.
  2. Open the workspace selector in the sidebar (press W) and pick Ceph Clusters.

The table lists your connections with columns Cluster (the connection name with its dashboard URL underneath), Status, FSID (the cluster's unique id, discovered on the first successful refresh), and Last check (the result of the latest test from this session, plus any Connect, Disconnect or Remove that failed - their successes are left out, since the Status column already shows them). The search box matches the connection name and dashboard URL only, not the FSID or the status. Select a row and press o or y for the Overview and YAML sidebar tabs with the full record; Esc clears the selection, which disables every row action until you pick a row again.

The Status column is the connection lifecycle, not Ceph's own health:

StatusMeaning
disconnectedNot connected. This is also what a never-connected cluster shows.
connectingLogin and the first health probe are in flight.
connectedThe dashboard login succeeded and the background poller is running.
errorThe last connect or poll failed.

Ceph's own verdict (HEALTH_OK, HEALTH_WARN, HEALTH_ERR) is a different axis and lives in the data views - see Browsing Ceph Data.

Adding a Cluster

Press Add (n) and fill in the form:

FieldNotes
NameLabel for this cluster, and also its unique id. Required. It cannot be changed later - the Edit dialog renders it read-only. Adding a second connection with the same name is rejected. Leading and trailing spaces are trimmed.
Dashboard URLBase URL of the Manager Dashboard, for example https://mgr-host:8443. Required. Kunobi normalises it before saving: https:// is assumed when no scheme is given, any query string or fragment is dropped, and a trailing slash is removed. A URL with a scheme other than http/https, or with no host, is rejected at save time.
Accept untrusted certsOff by default. Turn it on for a dashboard serving a self-signed certificate - most on-cluster deployments do.
UsernameDashboard username. Required.
PasswordDashboard password. Required. It goes to your OS keychain, never to a config file.

Test Connection in the dialog performs a real dashboard login with exactly what is in the form, without saving anything. A green "Connection succeeded" banner means the credentials work; a failure shows the dashboard's own error. Leaving Name or Dashboard URL empty is caught up front with "{field} is required.". Test Connection does not apply that check to Username and Password - it attempts the login and lets the dashboard's rejection come back - while saving the form does require them.

Saving only stores the connection - it does not connect. Connect it from the row (c) or by picking it in the connection selector.

Testing, Editing & Removing

With a row selected:

  • Test (t) - logs in with the stored credentials. The result appears in the Last check column: Testing..., then OK or Failed, with the message in a tooltip.
  • Edit (e) - change the URL, username, password, or the untrusted-cert setting. Name is read-only. Leaving Password blank keeps the stored one (the dialog's Test Connection then verifies the stored password). Saving invalidates any live client for that cluster, so the next connect picks up the new endpoint or credentials.
  • Remove () - after a confirmation ("Remove cluster?" - "This permanently removes "{name}" and deletes its stored credential. This cannot be undone."), the connection is removed from the config, its password is deleted from the keychain, its poller is stopped, and every piece of data collected for it is dropped.

The Connected Cluster

Ceph connections are per tab: each Kunobi tab views one cluster, and different tabs can view different clusters at the same time.

  • Connect (c) on a selected row logs in, runs one health probe, starts that cluster's background poller and marks the row connected. Connecting is idempotent - a cluster that is already connected is left alone.
  • Disconnect (d) tears down the client and the poller and drops the cluster's collected data (health, capacity, hosts, OSDs, pools, RBD listings, events, alerts, metric history). The connection definition and its stored password stay. Disconnecting is app-wide: every tab viewing that cluster loses it.
  • The connection selector in the status bar (or ⌘0 / Ctrl+0) opens the Connections dialog. Its Ceph Clusters tab lists your clusters with per-row Connect / Disconnect buttons. Picking a cluster there points the current tab at it and connects it if it isn't already connected or connecting; if that connect fails, the selection is kept so you can fix the credentials and retry.

Data for other connected clusters stays in memory, so switching a tab back to a cluster it already loaded is instant.

Browsing Ceph Data

Open the Kubernetes data page, open the workspace selector (press W), and pick Ceph Clusters. The sidebar lists twelve views - filter them with the box at the top. All Ceph kinds are cluster-scoped, so there is no namespace filter.

  • Overview - one row: the cluster this tab is pointed at. Columns Cluster (name with the dashboard URL underneath), Status (the connection lifecycle, same four values as the Sources table), Health (HEALTH_OK green, HEALTH_WARN yellow, HEALTH_ERR red), FSID, Used, Total, Usage.
  • Hosts - the cluster's hosts: Hostname, Address, Labels, Services.
  • OSDs - one row per OSD, sorted by id: ID (rendered osd.<n>), Host, Up/In (two coloured flags - up/down and in/out), State, Used, Total, Usage.
  • Pools - Name, Type (replicated or erasure), Applications, PG#, Size (the replication factor) and Min size, both suffixed ×, Autoscale, Compression (mode with the algorithm in parentheses), Used, Total, Usage, CRUSH rule, EC profile, Quota (max bytes / max objects), Flags.
  • Block Images - RBD images across every RBD-tagged pool: Name, Pool, Used, Total, Usage, Features, Snapshots (count), Format (rendered v1/v2), Namespace, Clone of (the parent as <pool>/<image>@<snapshot> for cloned images).
  • Block Snapshots - Name, Image, Pool, Used, Total, Usage, Protected, Created. Opened from the sidebar it lists every snapshot on the connection; drilled into from a Block image (press Enter or double-click) it narrows to that image's snapshots.
  • RBD Trash - soft-deleted images: Name (with the trash id beside it in monospace), Pool, Namespace, Source, Deleted, Expires.
  • RBD Namespaces - sub-tenants inside a pool: Namespace, Pool, Images (a count derived from the image listing, not from the cluster's own field, which several Ceph versions omit).
  • Events - the cluster, audit and dashboard logs merged into one stream, newest first: Severity (info, warning, error), Source (cluster, audit, dashboard), Message, Timestamp.
  • Alerts - every alert AlertManager currently holds, not only the firing ones: Alert (the alert name with the instance underneath), Severity, State (firing, suppressed when a silence covers it, or unprocessed), Summary.
  • Alert Rules - the cluster's alerting rules (recording rules are filtered out): Severity, State (firing, pending, inactive), Rule, Group, Query, For (the rule's for: window in seconds).
  • Alert Silences - AlertManager silences, ordered by silence id: State (active, pending, expired, or other for a value Kunobi doesn't recognise), Matchers (rendered in AlertManager syntax, for example alertname="CephOSDNearFull"), Created by, Comment, Starts, Ends.

Health, capacity, hosts, OSDs, pools, events and the alert surfaces are refreshed by the background poller. The Block Images, Block Snapshots and RBD Namespaces views additionally list every RBD-tagged pool's images (and, for RBD Namespaces, its namespaces) when you open them, so the first paint doesn't wait for a poll tick. RBD Trash is fetched on entry only - it is not part of the poll, so a purge or a trash move made elsewhere shows up when you re-enter the view. See Drilldown for how drilling, breadcrumbs and the kind filter work.

Each observability view is gated on its own passthrough: Alert Rules on Prometheus, Alerts and Alert Silences on AlertManager. A missing passthrough leaves that view empty and the rest of the snapshot untouched, so one can be populated while the others aren't. Dashboard permissions are coarser: all three sit behind the dashboard's single Prometheus scope, so a user denied that scope loses all three at once - and since Kunobi can't tell a denial from a missing passthrough, both look the same from here.

Resource Details

Selecting a row opens detail tabs in the sidebar: an Overview with the kind's fields and a read-only YAML tab with the raw record. Values that are unset render as -.

  • Cluster → Overview - Cluster Summary (Health, Connection Status, FSID, URL, Username) and Capacity (Used, Total, Used Ratio as a percentage).
  • Cluster → Metrics - see Cluster Metrics.
  • Host → Overview - Host Summary (Hostname, Address, Status) and Ceph Labels (the host's labels, or "No labels").
  • Host → Services - the Ceph daemons on the host as badges, each type.id (for example mon.node-1) or just type when the daemon has no id. Empty hosts show "No services on this host".
  • OSD → Overview - OSD Summary (ID, Host, Up, In, State) and Usage (Used, Total).
  • Pool → Overview - Pool Settings (Type rendered as replicated x <size> or erasure (<profile>), Pool ID, Applications, PG Num, Min Size, Autoscale, CRUSH Rule, Flags), Compression (Mode, Algorithm) and Quotas & Usage (Quota Max Bytes, Quota Max Objects, Bytes Used, Max Available).
  • Block image → Overview - Image Summary (Pool, Namespace, Size, Used, Format, Features, Clone of).
  • Block image → Snapshots - a table of the image's snapshots with Name, Size, Created and a Protected badge. Images without snapshots show "No snapshots for this image".
  • Block snapshot → Overview - Snapshot Summary (Size, Used, Created, Protected, Parent Image, Pool, Namespace).
  • Trashed image → Overview - Trashed Image (Name, Pool, Namespace, Source, Deleted, Expires, Expired).
  • RBD namespace → Overview - Namespace Summary (Namespace, Pool, Image Count).
  • Event → Overview - Event (Severity, Source, Channel, Timestamp, Message).
  • Alert → Overview - Alert (Name, Severity, State, Instance, Summary, Description) and a Labels table.
  • Alert rule → Overview - Alert Rule (Name, Severity, State, Group, Duration in seconds, Query).
  • Alert silence → Overview - Silence (State, Matchers, Created By, Comment, Starts, Ends).

Cluster Metrics

The Cluster's Metrics tab charts the cluster-wide IO history Kunobi has collected for that connection while it was connected. Nothing is fetched when you open it - the numbers come from the background poller, one sample per tick, so a freshly connected cluster shows "Collecting metrics… (1 sample, ~30s per tick)" until it has at least two.

A range switcher offers 5m, 30m and 1h (default 1h), windowed relative to the newest sample rather than to wall-clock time. Five charts:

  • Client IOPS (read + write)
  • Client throughput (read + write)
  • Recovery throughput
  • Recovery ops/sec
  • Object integrity (degraded + misplaced + unfound)

History is in memory only, capped at 120 samples per series - about an hour at the default 30-second interval. It is discarded when you disconnect the cluster, remove it, or the Pro license stops covering Ceph.

Actions

Ceph's actions appear in the action bar when a matching row is selected, in the command palette, and on their keyboard shortcuts. Every one of them is Pro-gated: without a Pro license they stay visible with a lock icon and a tooltip ending "available with Kunobi Pro", and clicking one opens the upgrade page.

All of them act on the connection that owns the selected row, so they need a Ceph row selected. With nothing selected they are greyed out in the action bar.

The kind-scoped ones simply don't fire outside their kind - their shortcut and their command-palette entry are both gated on the selected row's kind, so pressing ⌘⌥P without a Block snapshot selected does nothing at all rather than reporting an error. The four selection-independent actions (Create pool, Create image, New snapshot and Refresh Ceph snapshot) do fire, and report "No Ceph connection selected" when the selected row doesn't belong to a Ceph connection.

Destructive actions come in three shapes: a confirmation dialog with a summary of what is about to change and a red confirm button; a form with a red confirm button (Delete image and Purge, which both need an extra choice from you); and one that runs straight away with no confirmation at all (Purge expired). Only shrinking a Block image asks you to type a name first.

Pool Actions

Create pool (⌘⌥O / Ctrl+Alt+O) opens a form:

FieldNotes
NameLowercase letters, digits, ., - and _ only; the form refuses anything else.
Typereplicated (default) or erasure. Fixed after creation.
PG count (pg_num)Minimum 1, default 32.
PG autoscaleoff, warn or on (default on).
Size (replicas)Replicated pools only, default 3, minimum 1. Must not be lower than Min size.
Min sizeReplicated pools only, default 2.
ProfileErasure pools only, and required for them. The dropdown is filled from the cluster's erasure-code profiles and shows each profile's k and m; its empty entry reads "— choose a profile —", with a "Loading profiles…" hint underneath while the list is empty (which also persists when the cluster has no profiles, or the lookup failed). Fixed after creation.
ApplicationsCheckboxes for rbd, rgw and cephfs, plus a free-text box to add any other tag. A pool must carry rbd to hold block images.
CompressionMode (none, passive, aggressive, force) and algorithm (snappy, zlib, zstd, lz4). Both default to a leave unchanged entry.
QuotasMax bytes as a value plus unit (B, KiB, MiB, GiB, TiB) and Max objects. Empty means unlimited.
CRUSH ruleOptional; the dropdown is filled from the cluster's CRUSH rules.
Pool flagsCheckboxes for nodelete, nopgchange, nosizechange, noscrub and nodeep-scrub.

Edit pool (⌘⌥U / Ctrl+Alt+U) with a Pool selected opens the same form, pre-filled. Name, Type and the erasure-code Profile are fixed. Only the fields you actually change are sent to the cluster, so an edit never rewrites settings you didn't touch.

Three settings can be changed here but not cleared: emptying Max bytes, Max objects or Min size, or moving compression back to leave unchanged, sends nothing and the pool keeps its current value. Drop a quota from the Ceph dashboard or the CLI instead.

Delete pool () with a Pool selected asks to confirm: "This action cannot be undone. The pool and all of its data are removed permanently.", with the pool's name, type, applications and used bytes in the summary. Ceph itself refuses pool deletion unless the cluster has mon_allow_pool_delete = true; if it does, its error is shown as-is.

Create namespace (⌘⌥N / Ctrl+Alt+N) with a Pool selected creates an RBD namespace inside it. The name follows the same character rules as pools and images. Existing images aren't moved; new images can be placed in the namespace from the create-image form.

Block Image Actions

Create image (⌘⌥I / Ctrl+Alt+I) opens a form. If the cluster has no rbd-tagged pool the action refuses with "No RBD pools" and "Create an RBD-application pool before adding block images."

FieldNotes
PoolOne of the cluster's rbd-tagged pools. Changing it clears the namespace selection.
Namespace (optional)The pool's RBD namespaces, or the blank entry for the pool root.
NameLowercase letters, digits, ., - and _ only.
SizeValue plus unit, default 1 GiB. Required and must be positive - Create stays disabled while the field is empty or not a positive number.
Featureslayering, exclusive-lock, object-map, fast-diff and deep-flatten are ticked by default; journaling is available and off.
Object size (advanced)Default 4 MiB, and only sent when you change it. Smaller objects mean more metadata overhead.
QoS limitsIOPS limit, read IOPS limit, write IOPS limit, throughput limit, read throughput limit and write throughput limit. Numbers only; an empty field means no limit.

Edit image (⌘⌥M / Ctrl+Alt+M) with a Block image selected changes size, features and QoS in one operation, and sends only what changed - the dialog says "No changes detected." until something does. It shows the image's current and used size, and:

  • Growing an image just saves.
  • Shrinking turns the footer red (Save (shrink)) and shows "Shrinking will discard data past the new size."; you must type the image's name into Type the image name to confirm before the button enables.
  • layering is locked because Ceph rejects toggling it on an existing image; the other five features are free.
  • QoS values are read back from the image's own overrides. Ceph stores "no limit" as 0, which Kunobi shows as an empty field so create and edit read the same way; clearing a field removes the override.

Delete image () with a Block image selected opens a dialog showing the image's provisioned size, used size and snapshot count, and asks which kind of delete:

  • Move to trash (recoverable) - the default. "Image goes to the Ceph trash. Restore it via the Trash dialog before someone purges it."
  • Delete permanently (irreversible) - "Skips trash. Image is destroyed immediately and cannot be recovered from the dashboard."

Either way the confirm button is red and labelled for the mode you chose (Move to trash or Delete permanently).

New snapshot (⌘⌥S / Ctrl+Alt+S) has two entry points to the same form. With a Block image selected it opens pre-bound to that image, with Pool and Image locked. From the command palette with any Ceph row selected it opens with free Pool and Image pickers instead. Either way you type a Snapshot name (same character rules as image names).

Block Snapshot Actions

Toggle protection (⌘⌥P / Ctrl+Alt+P) with a Block snapshot selected flips the snapshot's protected flag and reports "Snapshot protected" or "Snapshot unprotected". Protection is what makes a snapshot cloneable and what stops it being deleted.

Clone snapshot (⌘⌥C / Ctrl+Alt+C) creates a new image from the snapshot. The snapshot must be protected first - otherwise the action stops with "Protect the snapshot first.", and a cluster with no rbd-tagged pool stops it with "No RBD pools". The form shows the source as <pool>/<image>@<snapshot> and asks for a Target pool (any rbd-tagged pool), a Target name (pre-filled <image>-clone) and the feature set. Features start from the parent image's when Kunobi still holds that image, from the default set when it holds the image but the image reports none, and from the full feature list when the image isn't in the store at all.

Rollback to snapshot with a Block snapshot selected reverts the whole image to that snapshot. It has no keyboard shortcut - use the action bar or the command palette. The confirmation is explicit about the blast radius: "All data written after the snapshot was taken will be lost; existing clones are unaffected."

Delete snapshot () with a Block snapshot selected confirms with "Snapshot deletion is irreversible." A protected snapshot cannot be deleted - the action stops first with "Unprotect the snapshot first."

Trash Actions

Restore (⌘⌥T / Ctrl+Alt+T) with a trashed image selected brings it back as an active image. The Name field is pre-filled with the original name; edit it to restore under a different one. The name is required and follows the usual character rules.

Purge () with a trashed image selected permanently removes that one entry: "Permanently delete {pool}/{name}. This action cannot be undone." Ceph protects a trashed image until its deferment window expires; while it hasn't, the dialog warns "Trash protection has not expired.", shows the expiry time, and the red Purge button stays disabled until you tick Force purge despite active deferment.

Purge expired (⌘⌥E / Ctrl+Alt+E) with a trashed image selected removes every entry in that image's pool whose deferment window has already passed. It runs immediately, with no confirmation dialog, and reports "Expired trash purged". The cluster decides what counts as expired, so a clock skew between Kunobi and the cluster can't cause an early purge.

Namespace Actions

Delete namespace () with an RBD namespace selected confirms with "This action cannot be undone. The cluster will reject this if the namespace still holds images". Ceph refuses to delete a namespace that still holds images, and its error is surfaced.

Refresh

Refresh Ceph snapshot asks the extension to re-poll the selected connection immediately instead of waiting for the next tick. It has no shortcut - run it from the action bar or, in the command palette, from the Extensions category rather than Ceph where the rest live. It waits for the re-poll rather than just firing it off: "Ceph refresh requested" means the refresh itself completed, and "Ceph refresh failed" carries the reason - the connection isn't live, the Pro entitlement is gone, or one of the core fetches (health, hosts, OSDs, pools) failed.

What Happens After You Submit

Ceph performs several of these operations asynchronously, so Kunobi re-reads the cluster rather than assuming a result:

  • Creating an image returns before the cluster has necessarily finished. Kunobi waits about 1.5 seconds and re-lists the pool; if the new image still isn't there - or the re-list itself failed - it inserts a provisional row built from what you typed so the table reflects your intent. The next poll replaces it with the cluster's own record, at which point server-computed fields such as used size become real.
  • Editing, resizing, snapshotting, protecting, cloning, rolling back and deleting re-list the affected pool right after the call, so the table catches up immediately.
  • Moving an image to trash removes it from the image list locally and re-fetches the trash list from the cluster (the trash id, deletion time and expiry are all server-generated).
  • Restoring removes the trash entry locally and re-lists the pool's images.
  • Purging one image removes the entry locally; purging expired re-fetches that pool's trash list.
  • Creating a namespace re-lists the pool's namespaces; deleting one removes it locally.
  • Pool create, edit and delete trigger a full snapshot refresh of the cluster.

A success notification means the cluster accepted the request. If the cluster rejects it, the error is surfaced verbatim - in the dialog for form actions, and as an error notification for one-shot actions. Refresh Ceph snapshot is no exception: it waits for the re-poll and reports its failure.

Security

  • Passwords never touch the config file. Dashboard passwords are stored in your operating system's keychain (macOS Keychain, Windows Credential Manager, or the Linux Secret Service), one entry per connection keyed by the connection name. Removing a connection deletes its entry. Non-production Kunobi variants use a separate keychain service name, so a development build cannot read or overwrite a production install's secrets.
  • Legacy plaintext passwords are migrated. If an older config.toml still carries a password field, Kunobi moves it into the keychain on startup and rewrites the file without it. If every keychain write fails the file is left alone and the migration is retried on the next start, so a locked keychain keeps the plaintext on disk. If some succeed and others don't, the file is rewritten anyway and the failed connections lose their stored password - re-enter those from the Edit dialog.
  • Accepting untrusted certificates disables TLS verification for that connection. The traffic is still encrypted, but Kunobi will no longer detect a substituted certificate, so prefer a trusted certificate where you can and keep the toggle for lab and on-cluster deployments.

Configuration File

Connection definitions are persisted in a TOML file (read at startup, rewritten whenever you change something in the app):

  • macOS: ~/Library/Application Support/<app-id>/extensions/ceph/config.toml
  • Linux: ~/.local/share/<app-id>/extensions/ceph/config.toml
  • Windows: %APPDATA%\<app-id>\extensions\ceph\config.toml

where <app-id> matches your Kunobi variant (for example ninja.kunobi.desktop).

[extension]
default_poll_interval = 30       # seconds between background refreshes
accept_untrusted_certs = false   # fallback when a connection sets nothing

[[connections]]
name = "prod-ceph"               # also the id and the keychain account
url = "https://mgr-host:8443"
username = "admin"
accept_untrusted_certs = true    # per-connection override
# fsid = "..."                   # discovered on the first refresh - managed by the app

There is no password field - passwords live in the keychain, keyed by the connection's name. Leave fsid alone; Kunobi writes it after the first successful refresh and rewrites it if the cluster ever reports a different one.

The [extension] block has no UI, and the file is read exactly once when the extension starts. Edit it with Kunobi closed, then restart: a default_poll_interval changed while Kunobi is running affects nothing, not even a fresh connect, and is overwritten the next time the app saves the file (adding or editing a connection, or persisting a discovered FSID). Values below 5 seconds are clamped to 5. accept_untrusted_certs is only consulted for connections whose own setting is absent from the file - the Add and Edit dialogs always write an explicit value.

Polling Behavior

  • Connecting starts a per-connection poller whose first tick runs immediately, then every default_poll_interval seconds (30 by default). Each tick fetches cluster health (capacity and the metric sample are read from the same response), hosts, OSDs, pools, the merged log, and the alerts, rules and silences, then re-lists the namespaces and images of every rbd-tagged pool. The RBD Trash listing is not part of the tick - it is fetched when you open that view and after a trash write.
  • Each store is published as soon as its own fetch lands, so a view fills in progressively rather than all at once. The core fetches (health, hosts, OSDs, pools) still run one after another, and a failure in any of them ends that tick.
  • A failing tick marks the connection error and keeps polling, so a transient outage recovers on its own without you reconnecting.
  • The log and the three observability surfaces are failure-isolated: if they 404 or your dashboard user is denied, the rest of the tick still lands.
  • RBD listing is throttled: at most four pools are fetched at a time per connection, and at most eight across all connected clusters, so a cluster with many RBD pools doesn't flood its dashboard.
  • Everything except the metric history is a live snapshot - no history is kept. Events hold the most recent 500 log lines and Alerts the 500 most severe, both re-read on every tick. Metric history is the one exception, capped at 120 samples per series.
  • Disconnecting or removing a connection drops its data. If the Pro entitlement goes away mid-session, every poller stops and all collected data is cleared, leaving only the connection definitions and their stored passwords.

Troubleshooting

"Ceph requires a Pro license" - the data views are Pro-gated. See Plans & Pro.

"Ceph extension required" - the extension is installed but not running. Enable it from Settings → Extensions.

"No cluster connected" - the tab isn't pointed at a connected cluster. Use Manage connections in that notice, or connect the cluster from the Sources page with c.

"No Ceph connection selected" - an action fired with nothing selected, or with a row that isn't a Ceph row. Select a Ceph row in the data view first.

Test or Connect fails with an authentication error - the dashboard rejected the username or password. Check them against the dashboard's own login, and remember that leaving Password blank on edit keeps the old one.

Test or Connect fails with a certificate error - the dashboard is serving a certificate Kunobi doesn't trust. Either install a trusted certificate or tick Accept untrusted certs on the connection.

"the URL is empty", "expected an http:// or https:// URL", "... is not a valid URL" or "... has no host" - the Dashboard URL couldn't be parsed. Enter a host with an optional port, for example mgr-host:8443 (Kunobi will prepend https://).

"a connection named "..." already exists" - the name is the connection's id and must be unique. Pick a different one, or edit the existing connection instead.

"no password stored for connection ..." - the keychain entry is missing, usually because it was deleted outside Kunobi or the connection was copied between machines. Edit the connection and enter the password again.

"Ceph connection '...' is not connected" - an action ran against a cluster whose client isn't live, typically right after a disconnect or a credential change. Connect it again.

A view is empty right after connecting - the first tick may still be running. Give it a moment, or run Refresh Ceph snapshot. That refresh does not cover RBD Trash, which is fetched on view entry instead: leave the view and come back.

Alerts or Alert Silences are empty but Alert Rules isn't (or the other way round) - they ride different passthroughs. Alert Rules needs ceph dashboard set-prometheus-api-host; Alerts and Alert Silences need ceph dashboard set-alertmanager-api-host. A dashboard user denied access to either endpoint produces the same empty view.

"No RBD pools" - the create-image, create-snapshot and clone-snapshot actions all need a pool tagged with the rbd application. Create one, or add the rbd tag to an existing pool from Edit pool.

Create stays disabled on the create-image form - Pool, Name, Size and Object size all have to be valid. An empty or non-positive size is the usual cause.

Deleting a pool fails - Ceph requires mon_allow_pool_delete = true on the cluster. Its refusal is shown as-is.

Deleting a namespace fails - the namespace still holds images. Move or delete them first.

Purging a trashed image is refused - the deferment window hasn't expired. Tick Force purge despite active deferment, or wait until the Expires time.

A shrink won't submit - the confirmation field wants the image's exact name.

Limitations

  • Everything goes through the Manager Dashboard API. Kunobi can only do what your dashboard exposes and what your dashboard user is allowed to do.
  • Writes cover pools, RBD images, snapshots, trash and RBD namespaces. Hosts, OSDs, events, alerts, alerting rules and silences are read-only - you cannot mark an OSD out, silence an alert, or edit a rule from Kunobi.
  • Ceph's object (RGW) and filesystem (CephFS) services are not covered. Their pools show in the Pools view like any other, but there are no bucket, user or filesystem views.
  • Quotas, Min size and compression can be changed from Edit pool but not cleared.
  • Metric history is in-memory and per session: about an hour at the default interval, discarded on disconnect, and never written to disk.
  • Health detail beyond the HEALTH_OK / HEALTH_WARN / HEALTH_ERR verdict (Ceph's individual health checks, the PG state breakdown) is not surfaced. Use the Alerts and Events views for specifics.
  • The poll interval is a single extension-wide setting in the config file, with no per-connection override and no UI. It is read once at startup, so changing it needs Kunobi restarted.
  • The Create-image form does not expose RBD striping or a separate data pool.
Available for:
Apple macOS logomacOSMicrosoft Windows logoWindowsLinux logoLinux
Download Kunobi