1. Home
  2. Docs
  3. ClusterControl
  4. Components
  5. ClusterControl Controller
  6. HashiCorp Vault Integration

HashiCorp Vault Integration

Beginning with ClusterControl 1.8.0, it is possible to integrate HashiCorp’s Vault for storing credentials used in ClusterControl. When the controller starts up, it will connect to the Vault server and load the credentials.

See also

Check out this blog post, ClusterControl’s Vault Integration Adds Dynamic Data Security Protections on example configuration on ClusterControl with HashiCorp Vault.


The following is required in order to use the Vault Integration:

  • A running Vault Server. It must be reachable from the Controller. This has been tested with Vault v1.4.3.
  • ClusterControl version 1.8.0 or later.


The controller must be configured to use Vault. The following parameters are set in /etc/cmon.cnf (do not set in cmon.d/cmon_X.cnf):

Parameters Description
  • A token used by the controller to authorize itself against the Vault server. The Vault token is created by the Vault server. When the vault_token is present credentials for new clusters will be stored in Vault and not in the cmon configuration files.
  • The full URL (including protocol and port) where the Vault server is listening. You can set it to the same as you would set VAULT_ADDR environment variable for vault CLI. Default is https://localhost:8200.
  • Default value is clustercontrol. The controller is going to store the data within this path, e.g clustercontrol/controller_UUID/cluster_ID/mysql_password. Each ClusterControl instance and controller, and cluster can have its unique namespace.
  • Enable this to auto-move all existing secrets from existing cmon configuration files to the configured Vault instance.
Passwords will no longer be present in the CMON configuration files after this operation. Backup the configuration files and ensure that everything is working as expected before removing the backed up config files. The main /etc/cmon.cnf file is not modified.

Starting up

The Vault integration feature is enabled as soon as the vault_token configuration parameter is set. At this stage, provided there is a Vault server listening on the vault_addr, then any new cluster that is created will store its credentials in Vault.

Credentials of existing clusters are not affected until vault_auto_migrate have been enabled.

Since the Vault settings are applied to /etc/cmon.cnf, then these are global for all clusters. Hence, it is not possible to migrate one cluster at a time.

Reverting the Vault integration

Should you want to revert this process, you should follow these steps:

  1. Get all the keys and values from the Vault for all of the clusters.
  2. Stop cmon process.
  3. Remove Vault configuration from /etc/cmon.cnf.
  4. Add the keys and values you extracted from the Vault into respective configuration files in /etc/cmon.d. You can use the backup copy of the configuration from before Vault has been used but please keep in mind that some additional passwords might have been added in the meantime – double-check that your old configuration files contain all the data that is stored in the Vault.


  • In this version, ClusterControl only supports the KV v2 secrets engine in Vault.
  • Currently, the Controller must be restarted to re-read credentials from Vault.
  • Updating a credential in Vault will not change the underlying credential on the database node. Thus, when changing a password, then the account must be updated on the database node(s).
  • Not been tested with CMON HA.
  • The cmon-events, cmon-cloud, cmon-ssh services have not been migrated to use Vault yet. Hence the passwords are still present in /etc/cmon.cnf. You can ensure that the config files used by these services are reconfigured and then drop the passwords completely from /etc/cmon.cnf.
Was this article helpful to you? Yes No