Valkey key-value store for other NethServer 8 modules, as a standalone server or as a highly available Valkey Cluster spread over the nodes of the NethServer cluster.
- Standalone: one server, nothing to know about clustering.
- Cluster: install one instance per node; the first one is the initial node, the others join it. With 3 or more members the store survives the loss of any one node.
- Consumer modules get their own Valkey user from a guarded action; passwords never go through the cluster Redis keys.
Documentation:
- Consumer integration: the contract for modules
that use Valkey (discovery,
grant-client, events, HA modes, KumoMTA) - High availability: design, failure behaviour, membership, upgrades
- Operations: backup and restore, updates, troubleshooting
add-module ghcr.io/geniusdynamics/valkey:latest 1
Output example:
{"module_id": "valkey1", "image_name": "valkey", "image_url": "ghcr.io/geniusdynamics/valkey:latest"}
The UI Settings page has a role picker. From the command line:
# Standalone server
api-cli run configure-module --agent module/valkey1 --data '{"role": "standalone"}'
# New cluster on node 1, then members on nodes 2 and 3
api-cli run configure-module --agent module/valkey1 --data '{"role": "initial"}'
api-cli run configure-module --agent module/valkey2 --data '{"role": "join", "cluster_id": "valkey1"}'
api-cli run configure-module --agent module/valkey3 --data '{"role": "join", "cluster_id": "valkey1"}'Input fields:
| Field | Description |
|---|---|
role |
standalone, initial (first node of a new cluster) or join |
cluster_id |
with join: the cluster to join, from get-configuration cluster_candidates |
maxmemory_mb |
memory limit of each Valkey process, 0 (default) for none; writes fail when reached (noeviction) |
allow_same_node |
with initial: allow several members on one node. Tests only: such a cluster does not survive a node failure |
Read the settings with get-configuration, the health with
get-cluster-status, the client users with list-clients.
| Action | Who | Purpose |
|---|---|---|
configure-module |
administrators | role and settings |
get-configuration, get-cluster-status, list-clients |
readers | settings, health, clients (no secrets) |
grant-client, revoke-client |
role valkeyclient |
client credentials, see integration |
admit-member, reconcile-cluster |
role valkeypeer |
used between ns8-valkey instances to form and repair a cluster |
remove-module --no-preserve valkey1
A cluster member hands its slots over to the other members before it is removed.
- Valkey listens on the node cluster VPN address and on loopback only. The
VPN is WireGuard and is in the
trustedfirewall zone: no public port. - The
defaultValkey user is disabled. Each consumer has its own ACL user, stored as a SHA-256 hash. - The cluster bus between members uses mutual TLS with a CA private to the cluster.
- Secrets (admin and replication passwords, CA key) are in
0600files of the module state, never in the environment, argv, logs or Redis keys.
runagent -m valkey1 systemctl --user status valkey valkey-replica
runagent -m valkey1 journalctl --user -u valkey -n 50
api-cli run module/valkey1/get-cluster-status | jqvalkey-cli inside the container, as the module administrator (the
password is read from the state file, not typed on the command line):
runagent -m valkey1 sh -c '. ./secrets.env; VALKEYCLI_AUTH=$VALKEY_ADMIN_PASSWORD podman exec -i -e VALKEYCLI_AUTH valkey valkey-cli --user ns8admin -p ${TCP_PORTS%%,*} cluster nodes'./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/valkey:latest
The Robot Framework suites in tests/ cover the standalone server and a
three-member cluster on one node (allow_same_node), including member
restart, rolling restart, member removal and client revocation.
Translated with Weblate.