Skip to main content

Secure Valkey Access with SSO, TLS, and Auditing

Secure Valkey access with SSO while keeping databases off the public internet, removing static passwords from certificate-authenticated accounts, and recording every command in the audit log.

Setup takes four steps: create a join token, configure the Valkey server, grant access through AlmaForge RBAC, and connect with native valkey-cli or redis-cli.

info

Running Redis? See the Redis access guide.

Prerequisites​

Complete these checks before configuring access.

Valkey or Redis CLI​

On your computer, you need either valkey-cli or redis-cli with TLS support. alma db connect uses redis-cli when it is on PATH, otherwise it uses valkey-cli. You only need one of them.

Check the client that alma will use. If both are installed, use the Redis CLI tab:

Terminal
valkey-cli --versionvalkey-cli 8.0.10valkey-cli --help | grep -- --tls  --tls              Establish a secure TLS connection.  --tls-ciphers <list> Sets the list of preferred ciphers (TLSv1.2 and below)  --tls-ciphersuites <list> Sets the list of preferred ciphersuites (TLSv1.3)
Install a client if it is missing or has no TLS support

If redis-cli is absent, install the Valkey package with Homebrew. It includes valkey-cli and a redis-cli alias that alma selects. You do not need to start a local Valkey server:

Terminal
brew install valkey...==> Summary...export PATH="$(brew --prefix valkey)/bin:$PATH"# No output on success.valkey-cli --versionvalkey-cli 9.1.2

If an existing redis-cli lacks TLS support, install the Homebrew Redis package and put its client first on PATH. Installing valkey-cli alone does not change which client alma selects:

Terminal
brew install redis...==> Summary...export PATH="$(brew --prefix redis)/bin:$PATH"# No output on success.redis-cli --versionredis-cli 8.10.2

Repeat the version and TLS checks for the client alma selects: redis-cli if present, otherwise valkey-cli. Its help output must list --tls. If you changed PATH, add the export line to your shell's startup file to keep using that client in new terminals.

Installed Valkey server​

This guide was validated on Valkey 8.0 on an RPM-based Linux system. Other configurations should work too, though installation commands and file paths may differ.

Valkey must already be installed with TLS support. This guide does not cover installing Valkey.

On the Valkey server, check the installed version and TLS library:

Terminal
valkey-server --versionValkey server v=8.0.10 ...ldd "$(command -v valkey-server)" | grep libssl        libssl.so.3 => /lib64/libssl.so.3 (0x00007f48b58b9000)

The libssl line shows that Valkey links to the OpenSSL TLS library. If the second command prints nothing, confirm that your Valkey package includes TLS support before continuing. Step 2 configures the TLS listener and certificates. The connection test in Step 4 verifies that the TLS setup works through AlmaForge.

AlmaForge CLI​

On your computer, check whether alma is installed:

Terminal
alma version --clientClient Version: v2026.1.0+<build>

If the command is not found, install it and repeat the check:

Terminal
curl -fL https://get.almaforge.com/install.sh | sh...==> AlmaForge installed successfullyalma version --clientClient Version: v2026.1.0+<build>

The installer supports Linux and macOS on both amd64 and arm64. See CLI installation for package-specific options.

AlmaForge Cluster​

On your computer, sign in to your cluster and check your permissions.

Get your cluster's hostname from its administrator. If you do not have an AlmaForge cluster yet, complete the standalone deployment before continuing. Replace almaforge.example.com below with that hostname. Run the login command and complete the sign-in in your browser:

Terminal
alma login --proxy=almaforge.example.com:443
text
...
> Profile URL:        https://almaforge.example.com:443
  Logged in as:       [email protected]
  Cluster:            almaforge.example.com
  Roles:              admin
  ...

After signing in, check your account and roles:

Terminal
alma status
text
> Profile URL:        https://almaforge.example.com:443
  Logged in as:       [email protected]
  Cluster:            almaforge.example.com
  Roles:              admin
  ...

In the status output, check that:

  • Cluster names the cluster you intend to configure.
  • Logged in as shows your account.
  • Roles includes admin.

If admin is missing, ask a cluster administrator to grant that role, then run alma logout and repeat the login and status commands. Continue once Roles includes admin.

Step 1. Create AlmaForge join token​

On your computer, create an AlmaForge join token. The database agent uses it to join your AlmaForge cluster:

Terminal
alma create token --services=databaseToken created.  client_id:     <client-id>  client_secret: <client-secret>

You will copy client_id and client_secret into the agent configuration in Step 2. They are valid for 30 minutes. If they expire before the agent joins, create a new token and use its values.

Step 2. Configure the Valkey server​

Install and configure the agent​

The agent is almad with its Database Service enabled. It connects outward to your cluster on port 443 and carries connections between users and Valkey.

On the Valkey server, check whether almad is installed:

Terminal
almad versionAlmaForge v2026.1.0+<build>

If the command is not found, install the AlmaForge package:

Terminal
curl -fL https://get.almaforge.com/install.sh | sh...==> AlmaForge installed successfullyalmad versionAlmaForge v2026.1.0+<build>

On an RPM-based system, the installer uses the RPM package and installs the almad systemd service. It supports both amd64 and arm64. The version command must succeed before you configure the agent. For other Linux distributions, see Linux package installation.

Already running an agent on this host?

Keep its existing settings and enable ALMA_DATABASE_SERVICE=true. Preserve the other services and label selectors. The join credentials must permit the database service. The local target created below does not need a label selector.

On the Valkey server, open the agent configuration:

Terminal
sudoedit /etc/almaforge/almad.env# Your text editor opens.

For a new agent, enter the settings below. Replace ALMA_PROXY with your cluster's hostname and port 443. Set ALMA_CLIENT_ID and ALMA_CLIENT_SECRET to the values from Step 1:

almad.env:

/etc/almaforge/almad.env
# Database Service agent on the Valkey host.
# Install at /etc/almaforge/almad.env as root:root with mode 0600.
ALMA_PROXY=almaforge.example.com:443

# Printed by `alma create token --services=database`.
ALMA_CLIENT_ID=paste-client-id-here
ALMA_CLIENT_SECRET=paste-client-secret-here

ALMA_DATABASE_SERVICE=true
ALMA_SSH_SERVICE=false

# Agent labels, separate from the database's labels.
ALMA_LABELS=env=prod

Save the file and close the editor. Restrict it to root because it contains the join credentials:

Terminal
sudo chown root:root /etc/almaforge/almad.env# No output on success.sudo chmod 0600 /etc/almaforge/almad.env# No output on success.

Create the TLS certificates​

The agent and Valkey run on the same server. Their connection uses the loopback interface (localhost, or 127.0.0.1), so this traffic stays on that server. A self-signed certificate for localhost is sufficient. You do not need a public hostname or a certificate from a public CA.

The agent still checks Valkey's certificate against the one you put in its configuration. Valkey uses the AlmaForge database CA to check the client certificate presented by the agent. The files below establish that trust in each direction.

Keep running these commands on the Valkey server.

Download your cluster's public database CA. Replace almaforge.example.com with the same hostname you used to sign in. Validate the downloaded certificate, then install it where Valkey can read it:

Terminal
curl -fsS -o almaforge-db-ca.pem 'https://almaforge.example.com:443/api/v1/auth/export?type=db'# No output on success.openssl x509 -in almaforge-db-ca.pem -noout# No output means the file contains a valid certificate.sudo install -o valkey -g valkey -m 0644 almaforge-db-ca.pem /etc/valkey/server.cas# No output on success.

Create a server certificate for localhost, the address the agent will use. The command writes a new certificate and private key at the paths below. For an existing TLS installation, preserve its certificate and adapt the paths and trusted CA instead.

Terminal
sudo openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \    -subj '/CN=localhost' \    -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \    -keyout /etc/valkey/server.key -out /etc/valkey/server.crt...-----sudo chown valkey:valkey /etc/valkey/server.key /etc/valkey/server.crt# No output on success.sudo chmod 0600 /etc/valkey/server.key# No output on success.

Enable TLS in Valkey​

These settings restrict network access to TLS on localhost. The Unix socket remains available for local administration by root and the Valkey service account.

Open the Valkey configuration on the server:

Terminal
sudoedit /etc/valkey/valkey.conf# Your text editor opens.

Set the following values, replacing any existing entries for these settings. Keep your data directory, ACLs, replication settings, and other configuration:

valkey.conf:

/etc/valkey/valkey.conf
# Serve Valkey over TLS only and trust AlmaForge client certificates.
# Merge these settings into /etc/valkey/valkey.conf on the agent's host.
bind 127.0.0.1 -::1
protected-mode yes
port 0
tls-port 6379
tls-cert-file /etc/valkey/server.crt
tls-key-file /etc/valkey/server.key
tls-ca-cert-file /etc/valkey/server.cas
tls-auth-clients yes
tls-protocols "TLSv1.2 TLSv1.3"
unixsocket /run/valkey/valkey.sock
unixsocketperm 700

tls-auth-clients yes requires a client certificate signed by the AlmaForge database CA for every TLS connection.

Save the file, close the editor, and restart Valkey:

Terminal
sudo systemctl restart valkey# No output on success.systemctl is-active valkeyactivesudo valkey-cli -s /run/valkey/valkey.sock PINGPONG

active and PONG confirm that Valkey started and responds locally. This example uses Valkey's default account without a password. For an existing password-protected account, see Authentication required.

Register Valkey with the agent​

Still on the Valkey server, display the public server certificate:

Terminal
sudo cat /etc/valkey/server.crt-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

Copy the entire certificate, including the BEGIN and END lines. The agent uses it to verify Valkey. Then open the target configuration:

Terminal
sudo install -d -o root -g root -m 0700 /etc/almaforge/almad.d# No output on success.sudoedit /etc/almaforge/almad.d/valkey.yaml# Your text editor opens.

For a new file, copy the following YAML. If the file already exists, update the existing resource and preserve its other settings. Replace <paste the complete server certificate here> with the certificate you copied. Indent every certificate line by six spaces beneath caCert: |:

target.yaml.in:

/etc/almaforge/almad.d/valkey.yaml
# Connect the local Valkey TLS listener through AlmaForge.
# Replace the placeholder with the contents of /etc/valkey/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: valkey
  labels:
    db: valkey
    env: prod
spec:
  protocol: redis
  uri: rediss://localhost:6379
  tls:
    caCert: |
      <paste the complete server certificate here>

Check that the certificate includes both its BEGIN and END lines, then save the file and close the editor. Restrict the file to root:

Terminal
sudo chown root:root /etc/almaforge/almad.d/valkey.yaml# No output on success.sudo chmod 0600 /etc/almaforge/almad.d/valkey.yaml# No output on success.

The target uses protocol: redis for Valkey's Redis-compatible protocol and rediss://localhost:6379 for its TLS listener.

Start and check the agent​

Enable the services at boot and start the agent:

Terminal
sudo systemctl enable valkey almad...Created symlink ...sudo systemctl restart almad# No output on success.systemctl is-active valkey almadactiveactive

enable may print nothing if the services are already enabled. Both services must report active. If either fails, inspect its log:

Terminal
sudo journalctl -u valkey -u almad -n 50 --no-pager...<date> <time> <valkey-host> <service>[<pid>]: <log-message>...

Each log entry identifies the process and its message. Resolve the reported error before continuing. The agent reads the target file at startup, so restart it after changing /etc/almaforge/almad.d/valkey.yaml.

Step 3. Grant access​

On your computer, confirm that the agent has registered Valkey:

Terminal
alma get dbHost             Name            Protocol       URI                 Labels             Version---------------- --------------- -------------- ------------------- ------------------ --------<valkey-host>    valkey          redis          <database-uri>      db=valkey ... 2026.1.0

Check that valkey appears with protocol redis and your Valkey server in the Host column. If the entry or host is missing, see Database is missing or has no host.

On your computer, copy the following YAML into a file named valkey-access.yaml. This role allows access to targets labeled db: valkey as the default database user. To allow other database users or restrict access further, see the RBAC guide:

valkey-access.yaml:

valkey-access.yaml
# Grants access to every Valkey target labeled db: valkey, as the Valkey
# default user. Map an SSO group to this role in your SSO connector.
apiVersion: almaforge.com/v1
kind: Role
metadata:
  name: valkey-access
spec:
  allow:
    databaseLabels: # Targets the user can reach, matched against DatabaseTarget labels.
      db: valkey
    databaseUsers: # Accounts the user may connect as with --db-user.
      - default

This evaluation role grants standing access to every matching Valkey target, regardless of its environment label. Before granting production access, follow Scope production access.

Apply the role:

Terminal
alma apply -f valkey-access.yamlrole 'valkey-access' has been created

Creating the role does not assign it to anyone. To grant it to an SSO group, list your connectors:

Terminal
alma get oidcKind          Name------------- -----------OIDCConnector company-sso

Find the connector your team uses to sign in. Replace <connector-name> with its name from the output, then open it in your text editor:

Terminal
alma edit oidc/<connector-name># Your text editor opens. After saving your changes:oidc connector "<connector-name>" has been updated

Under spec.claimsToRoles, find the entry for the group that should have Valkey access. Add valkey-access to that entry's roles list. Preserve the existing roles and mappings, including those that grant admin, then save and close the editor. The command applies your changes. If the group has no mapping yet, follow OIDC role mapping to add one.

Step 4. Connect​

On your computer, sign out of saved sessions, then sign back in with an account in the group granted access in Step 3 to get a session with the new role. logout clears saved sessions for all clusters. Use your cluster's hostname in the login command:

Terminal
alma logoutLogged out all users from all proxies.alma login --proxy=almaforge.example.com:443...> Profile URL:        https://almaforge.example.com:443  Logged in as:       [email protected]  Cluster:            almaforge.example.com  Roles:              valkey-access  ...alma status> Profile URL:        https://almaforge.example.com:443  Logged in as:       [email protected]  Cluster:            almaforge.example.com  Roles:              valkey-access  ...

Check that Roles includes valkey-access. If it is missing, check your SSO group membership and the mapping from Step 3 before continuing.

note

In this release, AlmaForge does not provision Valkey users or authenticate to Valkey for you. This example uses Valkey's passwordless default user. For a named account, authenticate with AUTH <name> <password> as shown in Named ACL users.

Connect to the database. The --db-user flag is an AlmaForge RBAC guard: it validates your requested identity against spec.allow.databaseUsers before opening the tunnel. When the Valkey prompt appears, type PING, then ACL WHOAMI:

Terminal
alma db connect --db-user=default valkeylocalhost:54321> PINGPONGlocalhost:54321> ACL WHOAMI"default"

PONG confirms that the connection through AlmaForge works. ACL WHOAMI reports Valkey's current user, default in this example. --db-user=default is checked against your AlmaForge roles and limits which user you may authenticate as with AUTH. It does not log in to Valkey. The local port is chosen for each connection, so yours may differ from 54321. If the default user requires a password, see Authentication required. Type exit to return to your normal terminal.

Advanced configuration​

Scope production access​

Use a separate role for production targets and an existing Valkey ACL account with the command and key permissions the task needs. This example requires both db: valkey and env: prod on the target and allows --db-user=ops.

Before granting this role, disable Valkey's default user or require a password for it. An enabled, passwordless default user lets a connection run commands as default without AUTH, even with --db-user=ops. Verify that a new connection returns NOAUTH for PING before you authenticate as ops.

valkey-prod.yaml:

valkey-prod.yaml
# Production Valkey access through the existing ops ACL account.
# Disable or password-protect Valkey's default user before granting this role.
# Grant this role through an access request for temporary elevation.
apiVersion: almaforge.com/v1
kind: Role
metadata:
  name: valkey-prod
spec:
  options:
    maxSessionTTL: 1h
  allow:
    databaseLabels:
      db: valkey
      env: prod
    databaseUsers:
      - ops

Replace ops with your existing ACL account and apply the role:

Terminal
alma apply -f valkey-prod.yaml

The role authorizes the account name. Configure the account's permissions with Valkey ACLs, and authenticate as described in Named ACL users.

For temporary on-call access, follow the JIT role configuration, using valkey-prod as the elevated role. Create requester and reviewer roles for it and set the requester's maxDuration to 1h. Map those roles to the appropriate SSO groups. Keep valkey-prod out of standing SSO grants, and remove the evaluation role's production access before relying on approval. Use Slack to route requests to your reviewers.

An engineer with the requester role can then run:

Terminal
alma request create --roles=valkey-prod --max-duration=1h \    --reason="Investigate production cache errors"Creating request...Waiting for request approval...

After approval, the command refreshes the engineer's certificate. Run alma db connect --db-user=ops valkey and authenticate as the selected ACL account. The request window and role certificate limit bound the grant. Configure session limits to enforce your policy for connections that are already open.

Automate onboarding​

Keep target and role manifests in your configuration repository. Render the public server certificate into spec.tls.caCert in target.yaml.in, and set the URI and labels for each database. Store join credentials and the OIDC client secret in your secret manager, and supply them when deploying configuration.

Choose one source for each target:

Target sourceDeployment procedure
Files on the agentDeploy the rendered target to /etc/almaforge/almad.d/valkey.yaml as root:root 0600. Keep the directory root:root 0700. Restart the agent after changing the target or its environment file.
Central resourcesApply the rendered target with alma apply -f valkey.yaml. Configure matching labels on the agents that can reach it. Agents watch central target changes.

For a new, dedicated database agent using central resources, set ALMA_MATCH_LABELS=db=valkey,env=prod in /etc/almaforge/almad.env alongside the agent settings, then restart the agent. Do not also install that target through a local file. The selector is shared with any Application and Kubernetes services in the same process. Preserve their matching requirements when configuring an existing agent. See Service matchers.

All agents that match a central target must reach its URI. Use the private address and certificate setup when agents run on separate hosts.

For central registration, apply the target and access role from your deployment job. These commands use the evaluation role. For production, use the scoped role and JIT configuration:

Terminal
alma apply -f valkey.yamlalma apply -f valkey-access.yaml

Manage SSO role mappings in the complete connector manifest using the OIDC configuration and verification procedure. Preserve existing mappings and supply its client secret from your secret manager when applying it. Authenticate the deployment job through workload identity, with permission to manage only the resources it deploys.

Deploy /etc/almaforge/almad.env with install -o root -g root -m 0600 so its join credentials are protected as soon as the file is created. For static joins, obtain the token shortly before starting the agent so its 30-minute enrollment window covers startup. Configure your deployment tool to restart services when their files change, then run the agent checks and connection check.

GUI clients and scripts​

Run this command on the computer where your client runs, and leave it running while you use the connection:

Terminal
alma proxy db --tunnel --db-user=default valkeyStarted authenticated tunnel for the Redis database "valkey" in cluster "almaforge.example.com" on 127.0.0.1:54321....

Connect your client to 127.0.0.1 and the port printed by the command. Use a plain TCP connection to this local address. In GUI tools such as DBeaver, leave SSL/TLS disabled in the tool's connection settings: alma handles the authenticated TLS connection to the cluster.

For example, open a second terminal on the same computer and use valkey-cli directly. Replace 54321 with the printed port:

Terminal
valkey-cli -h 127.0.0.1 -p 54321127.0.0.1:54321> PINGPONG

Choose RESP2 in your client or driver. Connections currently reject HELLO, PUNSUBSCRIBE, SSUBSCRIBE, and SUNSUBSCRIBE.

Run a check from CI​

Use a disposable Linux runner with alma, a TLS-capable valkey-cli or redis-cli, and GNU timeout from Coreutils installed. Create a bot and join token using the workload identity setup. Give the bot a role that permits the target's labels and database user. The check below uses this guide's evaluation target valkey and its passwordless default account.

In the job environment, set ALMA_PROXY to your proxy's hostname and port, ALMA_CLIENT_ID to the workload token's name, and ALMA_JOIN_METHOD to the method for your runner. Configure the runtime identity and token allow rules for that method. For example, a GitHub Actions job uses ALMA_JOIN_METHOD=github and needs id-token: write permission.

Save this script as check-valkey.sh in your job's workspace:

check-valkey.sh:

check-valkey.sh
#!/bin/sh# Check the evaluation Valkey target from a disposable Linux CI runner.# Requires workload identity, alma, a TLS-capable client, and GNU timeout.set -eu
: "${ALMA_PROXY:?Set the cluster proxy address}": "${ALMA_CLIENT_ID:?Set the workload token name}": "${ALMA_JOIN_METHOD:?Set the runner workload identity method}"
# Complete login before capturing the database reply.timeout --kill-after=5s 30s alma login >/dev/null
reply=$(printf 'PING\n' | timeout --kill-after=5s 30s \    alma db connect --db-user=default valkey)
if [ "${reply}" != PONG ]; then    printf '%s\n' 'Valkey check failed: expected PONG.' >&2    exit 1fi
printf '%s\n' PONG

Run it as a job step:

Terminal
sh check-valkey.shPONG

The script signs in through workload identity, then sends PING to the native client's standard input. It exits successfully only when the reply is PONG. Authentication errors, connection failures, unexpected replies, and timeouts fail the job. Each command has a 30-second timeout, followed by a kill signal five seconds later if needed.

alma db connect manages its local proxy for the duration of the command. It closes the connection and proxy when the client exits. Discard the runner and its saved credential profile after the job. For production checks, use the database account and target scope assigned to that workload, and retain any required upstream ACL authentication.

Named ACL users​

To connect as another existing Valkey user, replace <name> and <password> below with that user's credentials. Ensure that your assigned role includes <name> in its databaseUsers list. Run the connection command, then enter AUTH at the Valkey prompt. AlmaForge rejects an AUTH for a different user name. A successful authentication replies OK:

Terminal
alma db connect --db-user=<name> valkeylocalhost:54321> AUTH <name> <password>OK

Valkey Cluster​

For an existing Valkey cluster, configure TLS on every node before registering it with AlmaForge. Give each node a server certificate. On every node, set tls-ca-cert-file to a PEM bundle containing both:

  • The CA that issued the node certificates, so nodes can authenticate their peers.
  • The AlmaForge database CA, so nodes can authenticate the agent.

Add the node CA to the server.cas file from the single-server setup, keeping the AlmaForge database CA in that file. Valkey uses this same trust bundle for incoming clients, replication, and cluster connections. Alongside each node's TLS listener settings in /etc/valkey/valkey.conf, enable TLS for the cluster bus and replica connections:

valkey-cluster.conf:

/etc/valkey/valkey.conf
# Additional TLS settings for an existing Valkey cluster.
# Apply on every node alongside its TLS listener and certificate settings.
# The tls-ca-cert-file bundle must trust both the node CA and AlmaForge database CA.
tls-cluster yes
tls-replication yes

Use a node's private address in the DatabaseTarget URI and append ?mode=cluster, for example rediss://valkey.internal:6379?mode=cluster. The agent must reach every node address advertised by the cluster. Each node's certificate must cover the address the agent uses to reach it. Set spec.tls.caCert to the CA that issued the node certificates. The single-server example above uses a certificate for localhost. A cluster needs certificates for its node addresses. See the Valkey TLS guide for server configuration.

Cluster connections currently reject SCAN, MULTI, EXEC, and WATCH, along with administration commands including CONFIG, INFO, MONITOR, and CLUSTER. Of the ACL subcommands, only ACL WHOAMI is supported. Applications and GUI clients that require key scanning, transactions, or these administration commands cannot use those features through a cluster connection.

Dynamic labels​

DatabaseTarget static labels live in metadata.labels. For values that change between deployments, such as replication role or engine version, use spec.dynamicLabels. Each entry runs a command on the agent host at the configured period and stores standard output as the label value:

target-dynamic-labels.yaml.in:

/etc/almaforge/almad.d/valkey.yaml
# Connect the local Valkey TLS listener through AlmaForge with dynamic labels.
# Replace the placeholder with the contents of /etc/valkey/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: valkey
  labels:
    db: valkey
    env: prod
spec:
  protocol: redis
  uri: rediss://localhost:6379
  tls:
    caCert: |
      <paste the complete server certificate here>
  dynamicLabels:
    role:
      period: 1m
      command:
        - /bin/sh
        - -c
        - valkey-cli -s /run/valkey/valkey.sock INFO replication | grep '^role:' | cut -d: -f2 | tr -d '\r\n'

The agent runs the command directly as the user running almad (root in the systemd service), so the command must be on $PATH. Surrounding whitespace is trimmed. If the command fails, the label value records the error until the next check.

Multiple Valkey targets and high availability​

One Database Service agent can front multiple Valkey instances. Drop additional resource files into /etc/almaforge/almad.d/ on the agent host (for example valkey-cache.yaml and valkey-queue.yaml), or apply them centrally with alma apply -f.

With centrally applied targets, the agent claims resources whose labels match ALMA_MATCH_LABELS in /etc/almaforge/almad.env. See Automate onboarding for the deployment procedure.

For agent high availability, run two database agents on separate hosts. Join them to the same AlmaForge cluster. This protects against an agent failure. Valkey availability still depends on your database topology.

First, make Valkey reachable from both agent hosts:

  1. Choose a private hostname, such as valkey.internal, that resolves to the Valkey server's private IP from both hosts. Issue a server certificate whose Subject Alternative Names (SANs) include that hostname. The single-server certificate above covers only localhost.

  2. In /etc/valkey/valkey.conf, replace the loopback-only bind line with the following, substituting your server's private IP for 10.0.0.10. Keep the TLS listener and client certificate requirement:

    valkey-ha.conf:

    /etc/valkey/valkey.conf
    # Replace the single-host bind line with the Valkey server's private IP.
    # Permit port 6379 only from the database agents in your firewall.
    bind 127.0.0.1 -::1 10.0.0.10

  3. Allow inbound TCP port 6379 on that private interface only from the two agent hosts. Apply this restriction in the host firewall and any network firewall. Keep the port closed to other hosts and the public internet.

  4. Install the matching certificate and key at the configured TLS paths, preserve their ownership and permissions, and restart Valkey.

Set the DatabaseTarget URI to rediss://valkey.internal:6379 and spec.tls.caCert to the CA that issued the server certificate, or to the server certificate itself when it is self-signed. Register this target with both agents using one of these methods:

  • Centrally applied targets: Run two agents with identical ALMA_MATCH_LABELS in /etc/almaforge/almad.env. Both agents claim the target from the Auth Service.
  • File-drop targets: Install the same DatabaseTarget resource file in /etc/almaforge/almad.d/valkey.yaml on both agent hosts, using the shared address in uri.

Restart each agent after changing its local configuration. Check alma get db for both agent hosts, then test a connection with PING. During a planned failover test, stop one agent and verify that a new connection succeeds through the remaining agent. Restore the first agent before testing the second.

The Proxy load-balances connections across healthy agents. An established database connection does not migrate between agents. If an agent fails, reconnect through alma db connect. See Agent topology.

Architecture​

tip

Read how AlmaForge works across different services in How it works.

Access to Valkey uses three AlmaForge services alongside your Valkey server:

  • Auth Service (almad --auth-service): Issues short-lived certificates, keeps cluster state, and enforces RBAC roles.
  • Proxy Service (almad --proxy-service): The public TLS entry point at almaforge.example.com:443. It handles user sign-in and brokers connections to agents through reverse tunnels.
  • Database Service (almad --database-service): Runs on a host that can reach Valkey (typically the database server itself). It maintains an outbound reverse tunnel to the Proxy, validates incoming connections, and connects to Valkey over TLS.

In smaller environments, the Auth and Proxy services can run together in a single almad process. Larger setups typically split them across dedicated hosts. See How it works for common topologies.

alma is the CLI engineers use on their workstations. After signing in with SSO (alma login), running alma db connect retrieves a short-lived client certificate and launches an installed redis-cli or valkey-cli. For GUI tools, alma proxy db opens a local listener.

Valkey database access topology

When an engineer connects:

  1. alma db connect gets a short-lived certificate and reaches out to the Proxy on port 443 over TLS. For GUI tools, alma proxy db provides the same authenticated tunnel over a local TCP port.
  2. The Proxy authenticates the session, verifies that the user's roles allow access to the database, and routes traffic through the agent's reverse tunnel.
  3. The database agent checks the requested --db-user, establishes the TLS connection to Valkey, and streams the session while recording audit events.

The agent dials outbound to the cluster, so Valkey needs no public IP address or public inbound port. With an agent on the Valkey host, the database listener can stay on loopback. Agents on separate hosts need private network access to Valkey's TLS port, as described in agent high availability.

Troubleshooting​

Client executable not found​

alma db connect needs either redis-cli or valkey-cli on your computer's PATH. Follow the client checks. If both are installed, alma selects redis-cli.

Database is missing or has no host​

On the Valkey server, check that /etc/almaforge/almad.d/valkey.yaml exists and that ALMA_DATABASE_SERVICE=true is set in /etc/almaforge/almad.env. Use the service and log checks to confirm that the agent is running. After editing either file, restart almad, then run alma get db on your computer again.

Authentication required​

NOAUTH Authentication required means your Valkey configuration requires a password. Inside the alma db connect session, type AUTH <password> at the Valkey prompt, then try PING again. For another account, follow Named ACL users.

text
localhost:54321> AUTH <password>
OK
localhost:54321> PING
PONG

Database user denied​

For access denied to database user "<name>", check that your assigned role permits the user selected with --db-user. The valkey-access role above permits the default user. Add any additional Valkey users to spec.allow.databaseUsers. Check your assigned roles with alma status. After a role mapping changes, follow the sign-out and sign-in commands to get a new session.

Certificate validation fails​

The agent and Valkey trust different certificates:

  • spec.tls.caCert in /etc/almaforge/almad.d/valkey.yaml must contain the CA that issued the Valkey server certificate. For the self-signed single-server example, use /etc/valkey/server.crt itself. The target URI hostname must match a certificate SAN: localhost for that example, or the private hostname configured for remote agents.
  • /etc/valkey/server.cas must contain the AlmaForge database CA. It lets Valkey verify the client certificates presented by the agent.

Confirm that Valkey can read its certificate, private key, and CA file. If the cluster's database CA has changed, repeat the CA download and installation in Create the TLS certificates, then restart Valkey.

Certificate maintenance​

The certificate command above creates a server certificate valid for 3,650 days. Check its expiration date on the Valkey server:

Terminal
sudo openssl x509 -in /etc/valkey/server.crt -noout -enddatenotAfter=Sep 29 18:47:02 2036 GMT

To replace an expiring certificate, issue its replacement for the same hostnames and IP addresses used by your agents, then apply the ownership and permissions above. For the local evaluation, repeat the localhost certificate command. Then repeat Register Valkey with the agent to embed the new certificate, and restart Valkey and almad. After a rotation of the AlmaForge database CA, download and install the new CA in server.cas and restart Valkey. Verify either change with PING through alma db connect --db-user=default valkey.

Limitations​

In this release, the AlmaForge database proxy has the following limitations for connections to Valkey:

ConnectionProxy limitations
Standalone and clusterThe proxy supports RESP2 and rejects HELLO. The subscription commands PUNSUBSCRIBE, SSUBSCRIBE, and SUNSUBSCRIBE are unsupported.
ClusterSCAN, MULTI, EXEC, and WATCH are also rejected. Administration commands including CONFIG, INFO, MONITOR, and CLUSTER are unavailable. The only supported ACL subcommand is ACL WHOAMI.

See GUI clients and scripts for connection settings and Valkey Cluster for cluster details.

References​

Documentation and upstream configuration resources for Valkey and AlmaForge: