Skip to main content

Secure Redis Access with SSO, TLS, and Auditing

Secure Redis 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 Redis server, grant access through AlmaForge RBAC, and connect with native redis-cli.

info

Running Valkey? See the Valkey access guide.

Prerequisites​

Complete these checks before configuring access.

Redis CLI​

On your computer, you need redis-cli (or valkey-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:

Terminal
redis-cli --versionredis-cli 8.10.2redis-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 Redis 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 Redis server​

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

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

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

Terminal
redis-server --versionRedis server v=7.2.5 ...ldd "$(command -v redis-server)" | grep libssl        libssl.so.3 => /lib64/libssl.so.3 (0x00007f48b58b9000)

The libssl line shows that Redis links to the OpenSSL TLS library. If the second command prints nothing, confirm that your Redis 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 Redis 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 Redis.

On the Redis 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 Redis 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 Redis 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 Redis 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 Redis's certificate against the one you put in its configuration. Redis 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 Redis 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 Redis 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 redis -g redis -m 0644 almaforge-db-ca.pem /etc/redis/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/redis/server.key -out /etc/redis/server.crt...-----sudo chown redis:redis /etc/redis/server.key /etc/redis/server.crt# No output on success.sudo chmod 0600 /etc/redis/server.key# No output on success.

Enable TLS in Redis​

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

Open the Redis configuration on the server:

Terminal
sudoedit /etc/redis/redis.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:

redis.conf:

/etc/redis/redis.conf
# Serve Redis over TLS only and trust AlmaForge client certificates.
# Merge these settings into /etc/redis/redis.conf on the agent's host.
bind 127.0.0.1 -::1
protected-mode yes
port 0
tls-port 6379
tls-cert-file /etc/redis/server.crt
tls-key-file /etc/redis/server.key
tls-ca-cert-file /etc/redis/server.cas
tls-auth-clients yes
tls-protocols "TLSv1.2 TLSv1.3"
unixsocket /run/redis/redis.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 Redis:

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

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

Register Redis with the agent​

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

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

Copy the entire certificate, including the BEGIN and END lines. The agent uses it to verify Redis. 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/redis.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/redis.yaml
# Connect the local Redis TLS listener through AlmaForge.
# Replace the placeholder with the contents of /etc/redis/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: redis
  labels:
    db: redis
    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/redis.yaml# No output on success.sudo chmod 0600 /etc/almaforge/almad.d/redis.yaml# No output on success.

The target uses protocol: redis for the Redis 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 redis almad...Created symlink ...sudo systemctl restart almad# No output on success.systemctl is-active redis 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 redis -u almad -n 50 --no-pager...<date> <time> <redis-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/redis.yaml.

Step 3. Grant access​

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

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

Check that redis appears with protocol redis and your Redis 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 redis-access.yaml. This role allows access to targets labeled db: redis as the default database user. To allow other database users or restrict access further, see the RBAC guide:

redis-access.yaml:

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

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

Apply the role:

Terminal
alma apply -f redis-access.yamlrole 'redis-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 Redis access. Add redis-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:              redis-access  ...alma status> Profile URL:        https://almaforge.example.com:443  Logged in as:       [email protected]  Cluster:            almaforge.example.com  Roles:              redis-access  ...

Check that Roles includes redis-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 Redis users or authenticate to Redis for you. This example uses Redis'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 Redis prompt appears, type PING, then ACL WHOAMI:

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

PONG confirms that the connection through AlmaForge works. ACL WHOAMI reports Redis'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 Redis. 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 Redis ACL account with the command and key permissions the task needs. This example requires both db: redis and env: prod on the target and allows --db-user=ops.

Before granting this role, disable Redis'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.

redis-prod.yaml:

redis-prod.yaml
# Grants access to production Redis targets labeled db: redis and env: prod.
# Allows access as the ops database user. Map to an SSO group or use for JIT access.
apiVersion: almaforge.com/v1
kind: Role
metadata:
  name: redis-prod
spec:
  allow:
    databaseLabels: # Targets the user can reach, matched against DatabaseTarget labels.
      db: redis
      env: prod
    databaseUsers: # Accounts the user may connect as with --db-user.
      - ops

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

Terminal
alma apply -f redis-prod.yaml

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

For temporary on-call access, follow the JIT role configuration, using redis-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 redis-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=redis-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 redis 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/redis.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 redis.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=redis,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 redis.yamlalma apply -f redis-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 redisStarted authenticated tunnel for the Redis database "redis" 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 redis-cli directly. Replace 54321 with the printed port:

Terminal
redis-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 redis 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-redis.sh in your job's workspace:

check-redis.sh:

check-redis.sh
#!/bin/sh# Check the evaluation Redis 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 redis)
if [ "${reply}" != PONG ]; then    printf '%s\n' 'Redis check failed: expected PONG.' >&2    exit 1fi
printf '%s\n' PONG

Run it as a job step:

Terminal
sh check-redis.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 Redis 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 Redis prompt. AlmaForge rejects an AUTH for a different user name. A successful authentication replies OK:

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

Redis Cluster​

For an existing Redis 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. Redis uses this same trust bundle for incoming clients, replication, and cluster connections. Alongside each node's TLS listener settings in /etc/redis/redis.conf, enable TLS for the cluster bus and replica connections:

redis-cluster.conf:

/etc/redis/redis.conf
# Additional TLS settings for an existing Redis 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://redis.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 Redis 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/redis.yaml
# Connect the local Redis TLS listener through AlmaForge with dynamic labels.
# Replace the placeholder with the contents of /etc/redis/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: redis
  labels:
    db: redis
    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
        - redis-cli -s /run/redis/redis.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 Redis targets and high availability​

One Database Service agent can front multiple Redis instances. Drop additional resource files into /etc/almaforge/almad.d/ on the agent host (for example redis-cache.yaml and redis-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. Redis availability still depends on your database topology.

First, make Redis reachable from both agent hosts:

  1. Choose a private hostname, such as redis.internal, that resolves to the Redis 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/redis/redis.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:

    redis-ha.conf:

    /etc/redis/redis.conf
    # Replace the single-host bind line with the Redis 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 Redis.

Set the DatabaseTarget URI to rediss://redis.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/redis.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 Redis uses three AlmaForge services alongside your Redis 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 Redis (typically the database server itself). It maintains an outbound reverse tunnel to the Proxy, validates incoming connections, and connects to Redis 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.

Redis 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 Redis, and streams the session while recording audit events.

The agent dials outbound to the cluster, so Redis needs no public IP address or public inbound port. With an agent on the Redis host, the database listener can stay on loopback. Agents on separate hosts need private network access to Redis'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 Redis server, check that /etc/almaforge/almad.d/redis.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 Redis configuration requires a password. Inside the alma db connect session, type AUTH <password> at the Redis 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 redis-access role above permits the default user. Add any additional Redis 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 Redis trust different certificates:

  • spec.tls.caCert in /etc/almaforge/almad.d/redis.yaml must contain the CA that issued the Redis server certificate. For the self-signed single-server example, use /etc/redis/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/redis/server.cas must contain the AlmaForge database CA. It lets Redis verify the client certificates presented by the agent.

Confirm that Redis 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 Redis.

Certificate maintenance​

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

Terminal
sudo openssl x509 -in /etc/redis/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 Redis with the agent to embed the new certificate, and restart Redis and almad. After a rotation of the AlmaForge database CA, download and install the new CA in server.cas and restart Redis. Verify either change with PING through alma db connect --db-user=default redis.

Limitations​

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

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 Redis Cluster for cluster details.

References​

Documentation and upstream configuration resources for Redis and AlmaForge: