Fediversity

Feature Specification: Component grafana

Created: 2026-11-07

Status: Implemented

Input: Reconstructed from the code of core/components/operator/grafana/, core/components/hosting-provider/metrics-query.nix and the wiring in the setups.

User Scenarios & Testing (mandatory)

User Story 1 - See the resources of a deployment (Priority: P1)

An operator needs to see what the deployment uses, and if the applications are healthy. Each operator deployment runs a Grafana node. An administrator of the deployment logs in through the Authelia of the deployment, and reads the provisioned dashboards. Resources gives the CPU, memory, disk and network of each machine, and the size of the databases and buckets. Applications gives the NodeInfo figures of each application, and the metrics of Mastodon and PeerTube. Pixelfed gives only NodeInfo.

Why this priority: This is the reason for the component.

Independent Test: A VM test logs in through Authelia and reads the dashboards through the session.

Acceptance Scenarios:

  1. Given a member of fediversity-admins of the deployment, When the user logs in, Then the user is a Viewer and sees the dashboards Resources and Applications.
  2. Given a user of the deployment that is not in fediversity-admins, When the user logs in, Then Grafana refuses the user.

User Story 2 - Show only the series of the deployment (Priority: P1)

The metrics of all deployments are in one Mimir on the telemetry node of the hosting provider. The only datasource of the node is the read path of its deployment on that node (see telemetry). The read path adds the deployment_id of the credential to each query.

Why this priority: The metrics of one deployment tell an operator about the users of a different deployment.

Independent Test: The VM test of the component checks that Grafana sends the published credential. The VM test of the telemetry node checks that a credential gives only the series of its deployment.

Acceptance Scenarios:

  1. Given a dashboard query, When Grafana sends it, Then it goes to the read path of the deployment, with a password whose hash is the one the node published to KV.

User Story 3 - Keep no state of value (Priority: P2)

The datasource and the dashboards are provisioned, and login makes the users. Thus the database is in a runtime directory, and each start begins with an empty database.

Why this priority: This removes the backup and the migrations of the database.

Independent Test: The VM test restarts the service, and logs in again.

Acceptance Scenarios:

  1. Given a running node, When the service restarts, Then the database is new, and the dashboards are there.

Edge Cases

  • A node without a read path, as in the test of a single node, has no datasource.
  • The vars have a temporary value at boot. A change of the password restarts Grafana, which reads it only at the start.
  • A dashboard must not have a matcher on deployment_id: the read path gives an error for it.

Requirements (mandatory)

Functional Requirements

  • FR-001: Each operator deployment MUST run the component, without a choice of the operator.
  • FR-002: Login MUST be only through OIDC, from the Authelia of the deployment, and only for the members of fediversity-admins.
  • FR-003: The node MUST NOT have an admin account or a password login. Each user MUST be a Viewer.
  • FR-004: The only datasource of the node MUST be the read path of its deployment.
  • FR-005: The password of the read path MUST stay on the node. The hash MUST go to <deployment prefix>/public/metrics-query/htpasswd, as grafana: and a bcrypt hash of cost 5.
  • FR-006: The dashboards MUST be provisioned, and MUST NOT have a matcher on deployment_id.
  • FR-007: The database MUST be in a runtime directory.

Key Entities

  • Read path: https://telemetry.<apex>/metrics-query/<deployment id> on the telemetry node.
  • Query credential: The user grafana and the generated password of the metrics-query instance.
  • Dashboards: The static JSON files in dashboards/.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The VM test of the component passes.
  • SC-002: The VM test of the telemetry node shows that a credential does not give the series of a different deployment.

Assumptions

  • The hosting provider runs the telemetry node.
  • The logs have no deployment_id label, so the component shows only metrics.
  • A Viewer cannot use Explore, so an operator uses the dashboards.

Known Deviations

  • A user loses the preferences at each restart, because the database is in a runtime directory.