5.3 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| docs | Secret Backend: Consul | docs-secrets-consul | The Consul secret backend for Vault generates tokens for Consul dynamically. |
Consul Secret Backend
Name: consul
The Consul secret backend for Vault generates Consul API tokens dynamically based on Consul ACL policies.
This page will show a quick start for this backend. For detailed documentation
on every path, use vault path-help after mounting the backend.
Quick Start
The first step to using the consul backend is to mount it.
Unlike the generic backend, the consul backend is not mounted by default.
$ vault mount consul
Successfully mounted 'consul' at 'consul'!
Next, we must configure Vault to know how to contact Consul. This is done by writing the access information:
$ vault write consul/config/access address=127.0.0.1:8500 token=root
Success! Data written to: consul/config/access
In this case, we've configured Vault to connect to Consul
on the default port with the loopback address. We've also provided
an ACL token to use with the token parameter. Vault must have a management
type token so that it can create and revoke ACL tokens.
The next step is to configure a role. A role is a logical name that maps to a role used to generated those credentials. For example, lets create a "readonly" role:
POLICY='key "" { policy = "read" }'
$ echo $POLICY | base64 | vault write consul/roles/readonly policy=-
Success! Data written to: consul/roles/readonly
The backend expects the policy to be base64 encoded, so we need to encode it properly before writing. The policy language is documented by Consul, but we've defined a read-only policy.
To generate a new set Consul ACL token, we simply read from that role:
$ vault read consul/creds/readonly
Key Value
lease_id consul/creds/readonly/c7a3bd77-e9af-cfc4-9cba-377f0ef10e6c
lease_duration 3600
token 973a31ea-1ec4-c2de-0f63-623f477c2510
Here we can see that Vault has generated a new Consul ACL token for us. We can test this token out, and verify that it is read-only:
$ curl 127.0.0.1:8500/v1/kv/foo?token=973a31ea-1ec4-c2de-0f63-623f477c25100
[{"CreateIndex":12,"ModifyIndex":53,"LockIndex":4,"Key":"foo","Flags":3304740253564472344,"Value":"YmF6"}]
$ curl -X PUT -d 'test' 127.0.0.1:8500/v1/kv/foo?token=973a31ea-1ec4-c2de-0f63-623f477c2510
Permission denied
API
/consul/config/access
POST
- Description
- Configures the access information for Consul. This is a root protected endpoint.
- Method
- POST
- URL
- `/consul/config/access`
- Parameters
-
- address required The address of the Consul instance, provided as host:port
- scheme optional The URL scheme to use. Defaults to HTTP, as Consul does not expose HTTPS by default.
- token required The Consul ACL token to use. Must be a management type token.
- Returns
- A `204` response code.
/consul/roles/
POST
- Description
- Creates or updates the Consul role definition.
- Method
- POST
- URL
- `/consul/roles/`
- Parameters
-
- policy required The base64 encoded Consul ACL policy. This is documented in [more detail here](https://consul.io/docs/internals/acl.html).
- lease optional The lease value provided as a string duration with time suffix. Hour is the largest suffix.
- Returns
- A `204` response code.
GET
- Description
- Queries a Consul role definition.
- Method
- GET
- URL
- `/consul/roles/`
- Parameters
- None
- Returns
-
```javascript { "data": { "policy": "abcdef=" } } ```
Delete
- Description
- Deletes a Consul role definition.
- Method
- DELETE
- URL
- `/consul/roles/`
- Parameters
- None
- Returns
- A `204` response code.
/consul/creds/
GET
- Description
- Generates a dynamic Consul token based on the role definition.
- Method
- GET
- URL
- `/consul/creds/`
- Parameters
- None
- Returns
-
```javascript { "data": { "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" } } ```