MySQL Keyring now speaks Hashicorp Vault

Let’s put it in action

First we need to setup the Hashicorp Vault instance. You’ll need to obtain the binary from the Hashicorp site. Although Vault supports development mode that enables access over HTTP connection (which should not be considered secure), the keyring_hashicorp plugin is designed to support only HTTPS. In order to setup a production-like Vault instance, you’ll need to create a key pair and a certificate for it. Also, your certificate authority will need to sign the Vault certificate itself. Plenty of resources on that topic are already available (including our own MySQL Reference Manual section), so we wont regurgitate them here.

Once you’ve obtained those files, it is required to prepare a configuration file (config.hcl) for Hashicorp Vault server:

Naturally, the filepaths should be replaced to match your current setup. After you’ve created the configuration file, issuing the following command should get your Vault instance happy and running:

user@host $ vault server --config=config.hcl
Enter passphrase for /home/username/certificates/vault.key:
==> Vault server configuration:
*** general info about Vault server instance ***
==> Vault server started! Log data will stream in below:

Note: Depending on your configuration, Vault might complain about mlock syscall not working/available. Disabling mlock is not recommended for a production instance, but you may temporarily alleviate the issue by adding disable_mlock = true to the config.hcl file.

Configuring Vault instance

Vault server is running, but its configuration is not completed. Next step is to open another terminal and create unseal key(s):

user@host $ vault operator init -n 1 -t 1
Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS+JybL39BjcOE=
Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
*** some additional output ***

Upon initialization, Vault server creates a series of unseal keys which are ideally to be given to the key custodians within your organization. Arguments of the “operator init” command govern the number of keys to be generated, as well as the minimum number of keys required to unseal the Vault after the startup. Store the unseal key, and the root token to a safe place.

We’re currently just experimenting, so we generated a single unseal key which is required to unseal the Vault instance. Vault initialization is done once, and the Vault unseal operation is done on each Vault server startup as followed:

user@host $ vault operator unseal
Unseal Key (will be hidden):
*** output ***
Initialized true
Sealed false
*** output ***

Note1: If your Vault’s CA certificate is not available in the OS certificate store, the vault binary run as a client will refuse to connect to running Vault server instance due to the untrusted Certificate Authority. If you are not able, or willing to add your CA certificate, you can temporarily (not recommended) set the environment variable VAULT_SKIP_VERIFY to 1 before issuing vault commands.

Note2: As shown here, vault binary will try to connect to the default Vault server address ( If your setup differs from the default values, you should set the VAULT_ADDR environment variable accordingly.

Enable AppRole authentication and backend storage

At this point you’ll be able to connect to the Vault server both by using command line and browser interface. We’ll continue by using command line interface, but you can always perform equivalent actions through Vault UI available at

First you should login to the Vault server instance, using your root token:

user@host $ vault login
Token (will be hidden):
Success! You are now authenticated. The token information displayed
below is already stored in the token helper. You do NOT need to run
“vault login” again. Future Vault requests will automatically
use this token.

On successful login, you can issue the vault status command to verify everything’s looking good. Once we’re here, let’s enable AppRole authentication style and enable KV version 1 secret storage:

user@host $ vault auth enable approle
Success! Enabled approle auth method at: approle/
user@host $ vault secrets enable -version=1 kv
Success! Enabled the kv secrets engine at: kv/
user@host $ vault write auth/approle/role/mysql token_num_uses=0
token_ttl=20m token_max_ttl=30m secret_id_num_uses=0
Success! Data written to: auth/approle/role/mysql

The final command added a new Vault server role (mysql) for use with our keyring_hashicorp plugin. Next we’ll provide some additional rights to that role.

Assigning policy to role and retrieving credentials

At this point we should create a policy file, which we will import into Vault server instance. It will enable Vault server users (having Vault’s mysql role) to read and write secrets to/from a specific store path under Vault server. Store following content under the file name mysql.hcl:

Finalizing the Vault instance setup, we need to import the policy file, and retrieve credentials for our new role:

user@host $ vault policy write mysql-policy mysql.hcl
Success! Uploaded policy: mysql-policy
user@host $ vault write auth/approle/role/mysql policies=mysql-policy
Success! Data written to: auth/approle/role/mysql
user@host $ vault read auth/approle/role/mysql/role-id
Key Value
--- -----
role_id 01b611c6-e7b8-4e02-e05d-8de97e7e7f13
user@host $ vault write -f auth/approle/role/mysql/secret-id
Key Value
--- -----
secret_id c49556c3-f80e-6972-a0e7-60eeee5a770b
secret_id_accessor 1fbb1374-b798-a01f-22b2-c1ed174bf8b1

In order to configure MySQL keyring_hashicorp plugin (which we will do next), you’ll need the AppRole role_id and secret_id credentials retrieved in the last step.

Note: The policy allows a single MySQL server instance to connect to Vault server and read/write secrets under a particular path. Multiple MySQL server instances may use the same Vault server instance, albeit each MySQL instance should be assigned a different path (e.g. “kv/mysql/instance1”, “kv/mysql/instance2”, etc.) This is especially to be considered in replication setup context.

Leave a Reply