Create a dynamic MySQL or MariaDB secret

A shared database password lives in every app that uses it, and changing it means changing it everywhere at once. A dynamic secret replaces it with an account of its own for each machine: your Burrow creates it in MySQL or MariaDB the moment a machine reads the secret, with only the privileges you choose, and removes it when its time is up. Both work the same way, so this one guide covers them.

What you need#

• A MySQL or MariaDB database your Burrow can reach, and a role in your Burrow that can write secrets.

• An admin login there that can create 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 your database#

Name the secret, such as MYSQL. Machines read it as api/prod/MYSQL, like any other secret. Set Provider to the one you run, MySQL or MariaDB: each machine's login is then an account that can connect from any host, 'name'@'%'. The other databases work the same way, each with its own kind of login, and SSH user, below the line, issues SSH certificates instead.

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

• Host and Port: where your Burrow reaches the database, 3306 by default.

• Database: the database your Burrow connects to. The grant builder starts on it.

• Admin user and Admin password: the login your Burrow uses to create and remove each machine's account. 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 your database's certificate comes from your own CA, paste that CA's certificate there. A managed database's certificate is trusted already, so leave it empty.

Select Test connection. Your Burrow signs in with the admin login and checks it can create accounts, by making a throwaway one and dropping it again. Each machine's own account is made when it first reads the secret. Select Continue.

Shape each password#

Every account 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 account's real password is made when it's issued.

Decide what each login may do#

The grants are SQL, run on each login as it's created, with {{name}} standing for its account. Without any, an account can sign in but can't touch your data. Select Build to write them from a list:

• Access: Read-only reads rows, Read / write also inserts, updates and deletes them, and Full can change the schema too.

• Privileges: tick them one by one instead, under Data, Schema changes (creating, dropping and altering tables, indexes, foreign keys and temporary tables) and Routines and views. Any mix that isn't a preset is marked Custom.

• Scope: the database the grants apply to, the secret's own unless you change it. A grant on a database covers every table in it, including ones created later.

The statement shows as you choose. Use these grants puts it in the grants box. Read / write on app, with Temporary tables ticked for an app whose queries make them, writes this one:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES ON `app`.* TO {{name}};

Then select Test the grants. Your Burrow makes a throwaway account, applies the grants to it and drops it again, so a typo or a missing table shows up now rather than when a machine reads.

Set the lease policy#

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

MySQL and MariaDB can't expire an account at a set time, so there's no Database expiry setting here: your Burrow drops each account when its lease ends.

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 account as fields: host, port, database, 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 your database's own list of users.

ratel run sets one variable per field, so MYSQL gives MYSQL_HOST, MYSQL_USERNAME, MYSQL_PASSWORD and so on:

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

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

Change it later#

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

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

See and revoke logins#

Choose Logins from the row menu to see every account 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 account now. Your Burrow locks it so it can't sign in, ends its open sessions where the admin login may, and drops it. Its machine gets a new account on its next read.

If a login isn't issued#

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