Fediversity

Feature Specification: Component valkey

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/shared/valkey/, the cache web UI of the hosting provider and the wiring in the setups at 14504f80d, pull requests #1381, #1560, #1571, #1595, #1597, #1656, #1741, #1747, #1749, #1760, #1809, #1822, #1835, #1852 and #1996.

User Scenarios & Testing (mandatory)

User Story 1 - Give each application its own cache instance (Priority: P1)

The valkey component provides redis (see redis). The node runs one instance per requested namespace, on a port that is derived from the namespace, so a consumer knows the port without a lookup.

Why this priority: The applications do not start without their cache.

Independent Test: A VM test with the OpenBao valkey engine checks the ACL, the rotation and the backup. A provider contract test and unit tests cover the configuration, the gate and the port derivation.

Acceptance Scenarios:

  1. Given no namespaces, When the node evaluates, Then it runs no instance.
  2. Given a certificate, When an instance starts, Then it serves only TLS and asks clients for no certificate.

User Story 2 - Keep the cache passwords secret and rotated (Priority: P1)

Each instance has a default user with a bootstrap password that is generated once and kept (see generateFiles), and an application user whose password OpenBao rotates daily. An apply step sets the rotated password.

Why this priority: An instance without a password is open to the network.

Independent Test: The VM test.

Acceptance Scenarios:

  1. Given no bootstrap password, When the instance starts, Then it fails.
  2. Given a new render of the rotated password, When the apply step runs, Then it sets the password, reads it back and saves the ACL. In a tenant deployment, the credential carries the deployment namespace.

User Story 3 - Back up and restore a namespace (Priority: P2)

A daily timer streams a dump of each instance with restic to the garage of the group (see garage). A missed run runs at the next boot. The restore loads the snapshot into a scratch valkey and moves the keys into the live instance.

Why this priority: The cache can be built again, but some applications keep queues in it.

Independent Test: The VM test.

Acceptance Scenarios:

  1. Given a snapshot, When an admin restores it, Then the live instance gets the keys and keeps running.

User Story 4 - Inspect the cache in a web UI (Priority: P3)

An admin inspects the keys in redis-commander, behind forward-auth for the admin group with one factor. The node runs the UI only when it serves its forward-auth front and at least one namespace. The UI connects with TLS and the PKI CA when the instances serve TLS.

Why this priority: The UI is for diagnosis only.

Independent Test: A unit test checks that the UI reads the CA after the node fetches it, that every request goes through authelia, that the firewall keeps the UI port closed, and that a node without the front runs no UI. No check starts the UI.

Acceptance Scenarios:

  1. Given the switch for admin UIs is off, When the setups evaluate, Then the UI is not deployed.

Edge Cases

  • Without a certificate, the instances serve plain text on the management network.
  • The cache TLS policy is on by default when the PKI plan holds the valkey host. Consumers read the same policy from the contract result, so both sides agree.
  • The first boot makes the application user without a password. Later starts keep it and rewrite only the default user.
  • The apply step retries without a limit, and its failure does not stop the instance.
  • The node publishes only the host of each instance to OpenBao KV, because consumers derive the port.
  • The command-line tools get the password from the environment, not the command line.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST provide redis and MUST use valkey.
  • FR-002: The component MUST request spiffe, and MUST import its module through nixos-module.
  • FR-003: The component MUST request a redis grant for itself in its own namespace.
  • FR-004: The node MUST run one instance per namespace on the derived port, and none without namespaces.
  • FR-005: An instance MUST NOT start without a non-empty bootstrap password.
  • FR-006: The apply step MUST set the rotated password and MUST verify it before it saves the ACL.
  • FR-007: The backup MUST stream to restic through the streaming backup contract, with the S3 keys as credentials.
  • FR-008: The restore MUST NOT restart the live instance.
  • FR-009: The web UI MUST listen only on loopback and MUST rely on forward-auth.

Key Entities

  • Namespace: One instance, with its port, users and backup bucket. It saves snapshots and keeps an append-only log.
  • TLS certificate: From the internal PKI. A dedicated group reads its key, and a renewal restarts the instances (see ssl).

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The VM test and the provider contract test pass.
  • SC-002: The unit tests of the configuration, gate, coordinates, TLS agreement and port derivation pass.
  • SC-003: The catalog test passes with the valkey icon.

Assumptions

  • The hosting-provider and operator groups each run a cache.
  • The OpenBao valkey engine owns the rotation period.
  • The icon colors must not change, because of the valkey trademark policy.

Known Deviations

  • redis-commander has no native OIDC and relies on forward-auth only.