Configuring the plugin
Once you’ve successfully configured the Vault server instance, it’s time we start using it with MySQL. Minimum configuration that’ll get you up and going will look similar to this:
To verify that plugin is up and running, and that it was able to establish a connection to the Vault server instance, you should query the state of the variables exposed by the plugin (variable prefix below shortened intentionally for better overview):
There are two sets of information that the plugin exposes – first is the intended configuration, and the second is the currently applied/commited configuration. If everything went well, the committed configuration in the upper listing should match the intended. Otherwise, you’ll see applied configuration set to Not Committed. If this happens to you, you may try and investigate some of the hints in our Troubleshooting section below.
While MySQL is up, you may need to change some of the configuration variables, for which you can use SET GLOBAL directive. The effect of the changes won’t be seen until you’ve issued the special UDF:
The plugin will try to use the new values in the intended configuration to form a new connection to the Vault server. If such connection is successful, the new connection will replace the current one, and the committed configuration will get updated. On failure, the committed configuration will remain the same as before issuing the UDF command. That means that the plugin will continue to function properly with the old settings until it is able to verify the new settings.
By default, MySQL keys are stored directly to the Vault server instance. This has the advantage of safeguarding the keys, and being able to revoke authentication rights almost immediately. But also, MySQL won’t be able to retrieve keys in an event of a networking issue, and so may fail to retrieve encrypted data and keys, especially on startup.
In order to mitigate this issue, keyring_hashicorp plugin exposes a key caching feature which will maintain an in-memory key cache during server operation. This is governed by setting the keyring-hashicorp-caching on.
By default, keyring_hashicorp plugin will open an https connection to any endpoint, trusting the delivered Vault server certificate implicitly. If you want MySQL server to explicitly validate Vault certificate using a CA certificate file, you may use keyring-hashicorp-ca-path to provide the plugin with the file path of CA certificate. In such case, MySQL will refuse to connect to any Vault server for which the certificate chain was not successfully verified.
By default, the plugin will use https://127.0.0.1:8200 as a Vault address. If your setup differs from this setting, you should change the keyring-hashicorp-server-url.
Custom authentication URL
Similar to the server url endpoint, the Vault AppRole authentication endpoint may reside on a path different from default (if your Vault instance is setup that way). You can configure the keyring-hashicorp-auth-path to point to appropriate path within the Vault server instance.
Use the keyring infrastructure
From this point forward, you’ll be able to use Hashicorp Vault as a storage backend for the MySQL Keyring infrastructure. For quick tests of the feature, you may install a set of keyring UDF’s that’ll allow you to store/retrieve keys via command line.
As with most of the things, you may bump into some roadblocks during the setup. Here are some of the tips to help you get back on the right track.
1) Double check your certificate and steps to produce them
- check the IP/domain parts of your certificate, and how they apply to your setup
2) Ensure that Vault instance is up and unsealed
- check the vault binary output for possible warnings/errors
- check Vault status over console to verify it’s unsealed
3) Check that you’re not bumping into a firewall/proxy issues
- access Vault using a command line tool such as wget/curl
- you should get response from Vault, not the proxy or similar
4) Check that your role_id/secret_id are valid
- try authenticating via command line from your server
- you should be able to obtain authentication token
5) Check that you can access store path within Vault, using token obtained through your AppRole credentials
- first obtain authentication token as in 4)
- try storing/accessing secrets in KV storage via curl CLI
We always strive to provide you with best tools for your workflow. Let us know how you like our new keyring backend – we’d also appreciate if you have some ideas for improving it. And as always, thank you for your support and using MySQL!