Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.
Enable the Consul secrets engine:
$vault secrets enable consulSuccess! Enabled the consul secrets engine at: consul/
$vault secrets enable consulSuccess! Enabled the consul secrets engine at: consul/
By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the -path argument.
Bootstrap the Consul ACL system if not already done. To begin configuring the secrets engine, we must give Vault
the necessary credentials to manage Consul.
In Consul versions below 1.4, acquire a management token from Consul using the
acl_master_token from your Consul configuration file, or another management token:
Configure Vault to connect and authenticate to Consul:
$vault write consul/config/access \address="127.0.0.1:8500"\token="7652ba4c-0f6e-8e75-5724-5e083d72cfe4"Success! Data written to: consul/config/access
$vault write consul/config/access \address="127.0.0.1:8500"\token="7652ba4c-0f6e-8e75-5724-5e083d72cfe4"Success! Data written to: consul/config/access
Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version,
you will either provide a policy document and a token_type, or a set of policies.
When users generate credentials, they are generated against this role.
For Consul versions below 1.4, the policy must be base64-encoded. The policy language is
documented by Consul.
Write a policy and proceed to link it to the role:
$vault write consul/roles/my-role policy="$(base64 <<<'key "" { policy = "read" }')"Success! Data written to: consul/roles/my-role
$vault write consul/roles/my-role policy="$(base64 <<<'key "" { policy = "read" }')"Success! Data written to: consul/roles/my-role
$vault write consul/roles/my-role consul_roles="api-server"Success! Data written to: consul/roles/my-role
$vault write consul/roles/my-role consul_roles="api-server"Success! Data written to: consul/roles/my-role
Token lease duration: If you do not specify a value for ttl (or lease for Consul versions below 1.4) the
tokens created using Vault's Consul secrets engine are created with a Time To Live (TTL) of 30 days. You can change
the lease duration by passing -ttl=<duration> to the command above with "duration" being a string with a time
suffix like "30s" or "1h".
For Enterprise users, you may further limit a role's access by adding the optional parameters consul_namespace and/or
partition. Please refer to Consul's namespace documentation and
admin partition documentation for further information about
these features.
For Consul versions 1.7 and above, link a Consul namespace to the role:
$vault write consul/roles/my-role consul_roles="namespace-management"consul_namespace="ns1"Success! Data written to: consul/roles/my-role
$vault write consul/roles/my-role consul_roles="namespace-management"consul_namespace="ns1"Success! Data written to: consul/roles/my-role
For Consul version 1.11 and above, link an admin partition to a role:
$vault write consul/roles/my-role consul_roles="admin-management"partition="admin1"Success! Data written to: consul/roles/my-role
$vault write consul/roles/my-role consul_roles="admin-management"partition="admin1"Success! Data written to: consul/roles/my-role
Expired token rotation: Once a token's TTL expires, then Consul operations will no longer be allowed with it.
This requires you to have an external process to rotate tokens. At this time, the recommended approach for operators
is to rotate the tokens manually by creating a new token using the vault read consul/creds/my-role command. Once
the token is synchronized with Consul, apply the token to the agents using the Consul API or CLI.