Create a dynamic Redis secret

A shared Redis password lives in every app that uses it, and changing it means changing it everywhere at once. A dynamic secret replaces it with a user of its own for each machine: your Burrow creates an ACL user in Redis the moment a machine reads the secret, with only the commands and keys you allow, and deletes it when its time is up.

What you need#

• Redis 6 or later, reachable from your Burrow, and a role in your Burrow that can write secrets.

• An admin user in Redis that can manage users, ideally one made for your Burrow.

• Machines with access to the environment the secret goes in. This guide uses api's prod.

Open a new dynamic secret#

Open the environment in Projects, select the + at the top right of the secrets table and choose Dynamic. The dialog has three steps: Connection, Lease & credential, and Review.

Connect to Redis#

Name the secret, such as CACHE. Machines read it as api/prod/CACHE, like any other secret. Provider starts on the first in the list; set it to Redis.

Then fill in where Redis is and how your Burrow signs in to it:

• Host and Port: where your Burrow reaches Redis, 6379 by default. Redis has no database to name, so there's no Database field.

• Admin user and Admin password: the user your Burrow signs in as to create and delete each machine's user. It never leaves your Burrow, and machines never see it.

Choose how the connection is protected:

With either checking option, a CA certificate field appears. If Redis's certificate comes from your own CA, paste that CA's certificate there. A managed Redis's certificate is trusted already, so leave it empty.

Select Test connection. Your Burrow signs in with the admin user and checks it can create users. Nothing is created in Redis until a machine reads the secret. Select Continue.

Shape each password#

Every user gets its own random password. Under Password, set its length, from 8 to 64, which of A to Z, a to z, 0 to 9 and symbols it uses, and whether to leave out characters that look alike, such as 0 and O. Or choose UUID. The example shows the shape; each user's real password is made when it's issued.

Write each user's access rules#

On Redis the grants are the user's ACL rules, such as ~app:* +@read +@write. Every user can also run the connection commands, AUTH, PING and SELECT. Without any rules, a user can sign in but can't touch any key. Select Build to make them from a list:

• Access: Read-only runs read commands, Read / write also writes, and Full adds keyspace commands such as DEL and EXPIRE, transactions and scripting.

• Commands: tick command groups one by one instead: read, write and keyspace; data types such as hashes, lists and streams; or transactions, scripting and pub/sub. Any mix that isn't a preset is marked Custom.

• Scope: a glob pattern for the keys a user may touch, such as app:*, and for pub/sub, the channels.

The rule shows as you choose. Use these grants puts it in the grants box. Read / write on app:* writes one rule:

~app:* +@read +@write

Then select Test the grants. Your Burrow creates a switched-off user with the rules and deletes it again, so a rule Redis won't take shows up now rather than when a machine reads.

Set the lease policy#

The lease policy decides how each user lives. A new secret starts with sensible defaults, so you may not need to change any of them:

Redis can't expire a user at a set time, so your Burrow deletes each user when its lease ends, which also disconnects it. That's why there's no Database expiry setting for Redis.

Review and create#

Select Continue to see everything on one page, then Create dynamic secret. The admin password and CA certificate are saved with the secret, encrypted like any other value.

Read it from a machine#

A machine reads a dynamic secret the way it reads a structured one, and gets its own user as fields: host, port, sslmode, sslrootcert when you gave a CA, username and password. The username starts with rk_ and names the machine and the secret, so you can pick it out in ACL LIST.

ratel run sets one variable per field, so CACHE gives CACHE_HOST, CACHE_USERNAME, CACHE_PASSWORD and so on:

ratel run --env api/prod -- ./server

A machine keeps its user across reads until it ends, and the secret's row counts the logins out. With ratel run --watch, the command restarts when its user gets a new password; a renewal keeps the password, so it restarts nothing.

When Redis restarts#

Redis keeps its users in memory, so a Redis that restarts without them in its own configuration forgets every user your Burrow made. Each time a machine reads its login, your Burrow checks the user is still there as it was issued. If it isn't, it puts it back with the same password and rules, so the login works again from that read on, without a new password. Each time a user is put back is recorded in your audit log.

Change it later#

Choose Configure from the secret's row menu. Each tab saves on its own:

The connection and rules are kept as the secret's value, so Version History lists every change, and reverting to an earlier one replaces the users like any other change.

See and revoke logins#

Choose Logins from the row menu to see every user out: the machine holding it, its username, its state, and when it was issued and ends.

The bin at the end of a row revokes that user now. Your Burrow deletes it from Redis, which also disconnects every session signed in as it. Its machine gets a new user on its next read.

If a user isn't issued#

Every option in one place: Dynamic secrets in the documentation.