349 lines
9.4 KiB
Plaintext
349 lines
9.4 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: Consul - Secrets Engines - HTTP API
|
||
description: This is the API documentation for the Vault Consul secrets engine.
|
||
---
|
||
|
||
# Consul Secrets Engine (API)
|
||
|
||
@include 'x509-sha1-deprecation.mdx'
|
||
|
||
This is the API documentation for the Vault Consul secrets engine. For general
|
||
information about the usage and operation of the Consul secrets engine, please
|
||
see the [Vault Consul documentation](/docs/secrets/consul).
|
||
|
||
This documentation assumes the Consul secrets engine is enabled at the `/consul`
|
||
path in Vault. Since it is possible to enable secrets engines at any location,
|
||
please update your API calls accordingly.
|
||
|
||
## Configure Access
|
||
|
||
This endpoint configures the access information for Consul. This access
|
||
information is used so that Vault can communicate with Consul and generate
|
||
Consul tokens.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `POST` | `/consul/config/access` |
|
||
|
||
### Parameters
|
||
|
||
- `address` `(string: <required>)` – Specifies the address of the Consul
|
||
instance, provided as `"host:port"` like `"127.0.0.1:8500"`.
|
||
|
||
- `scheme` `(string: "http")` – Specifies the URL scheme to use.
|
||
|
||
- `token` `(string: "")` – Specifies the Consul ACL token to use. This
|
||
must be a management type token. If this is not provided, Vault will try to
|
||
bootstrap the ACL system of the Consul cluster automatically.
|
||
|
||
- `ca_cert` `(string: "")` - CA certificate to use when verifying Consul server certificate,
|
||
must be x509 PEM encoded.
|
||
|
||
- `client_cert` `(string: "")` - Client certificate used for Consul's TLS communication,
|
||
must be x509 PEM encoded and if this is set you need to also set client_key.
|
||
|
||
- `client_key` `(string: "")` - Client key used for Consul's TLS communication,
|
||
must be x509 PEM encoded and if this is set you need to also set client_cert.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"address": "127.0.0.1:8500",
|
||
"scheme": "https",
|
||
"token": "adha..."
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--request POST \
|
||
--header "X-Vault-Token: ..." \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/consul/config/access
|
||
```
|
||
|
||
## Create/Update Role
|
||
|
||
This endpoint creates or updates the Consul role definition. If the role does
|
||
not exist, it will be created. If the role already exists, it will receive
|
||
updated attributes. At least one of `consul_policies`, `consul_roles`,
|
||
`service_identities`, or `node_identities` is required depending on the
|
||
Consul version.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------- |
|
||
| `POST` | `/consul/roles/:name` |
|
||
|
||
### Parameters for Consul versions 1.11 and above
|
||
|
||
- `partition` `(string: "")` - Specifies the Consul admin partition in which the token is generated.
|
||
The partition must exist, and the Consul policies or roles assigned to the
|
||
Vault role must also exist inside the given partition. If not provided, the partition `default`
|
||
is used.
|
||
|
||
To create a client token within a particular Consul admin partition:
|
||
|
||
```json
|
||
{
|
||
"partition": "admin1"
|
||
}
|
||
```
|
||
|
||
### Parameters for Consul versions 1.8 and above
|
||
|
||
- `node_identities` `(list: <node identity or identities>)` - The list of node identities to assign to the generated
|
||
token. This may be a comma-separated list to attach multiple node identities to a token.
|
||
|
||
To create a client token with node identities attached:
|
||
|
||
```json
|
||
{
|
||
"node_identities": [
|
||
"client-1:dc1",
|
||
"client-2:dc1"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Parameters for Consul versions 1.7 and above
|
||
|
||
- `consul_namespace` `(string: "")` - Specifies the Consul namespace in which the token is generated.
|
||
The namespace must exist, and the Consul policies or roles assigned to the Vault role must also exist
|
||
inside the given Consul namespace. If not provided, the namespace `default` is used.
|
||
|
||
To create a client token within a particular Consul namespace:
|
||
|
||
```json
|
||
{
|
||
"consul_namespace": "ns1"
|
||
}
|
||
```
|
||
|
||
### Parameters for Consul version 1.5 and above
|
||
|
||
- `service_identities` `(list: <service identity or identities>)` - The list of service identities to assign to the generated
|
||
token. This may be a comma-separated list to attach multiple service identities to a token.
|
||
|
||
- `consul_roles` `(list: <role or roles>)` – The list of Consul roles to attach to the
|
||
token generated by Vault.
|
||
|
||
To create a client token with roles defined in Consul:
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"consul_roles": "role-a,role-b"
|
||
}
|
||
```
|
||
|
||
To create a client token with service identities attached:
|
||
|
||
```json
|
||
{
|
||
"service_identities": [
|
||
"myservice-1:dc1,dc2",
|
||
"myservice-2:dc1"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Parameters for Consul versions 1.4 and above
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of an existing role against
|
||
which to create this Consul credential. This is part of the request URL.
|
||
|
||
- `token_type` <sup>DEPRECATED (1.11)</sup> `(string: "client")` - Specifies the type of token to create
|
||
when using this role. Valid values are `"client"` or `"management"`. If a `"management"`
|
||
token, the `policy` parameter is not required. Defaults to `"client`". [Deprecated from Consul as of 1.4 and
|
||
removed as of Consul 1.11.](https://www.consul.io/api/acl/legacy)
|
||
|
||
- `policy` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the base64-encoded ACL policy.
|
||
This is required unless the `token_type` is `"management"`. [Deprecated from Consul as of 1.4 and
|
||
removed as of Consul 1.11.](https://www.consul.io/api/acl/legacy)
|
||
|
||
- `policies` <sup>DEPRECATED (1.11)</sup> `(list: <policy or policies>)` - Same as `consul_policies`.
|
||
Deprecated in favor of using `consul_policies`.
|
||
|
||
- `consul_policies` `(list: <policy or policies>)` – The list of Consul policies to assign
|
||
to the generated token. This field is required if using using Consul 1.4.
|
||
|
||
- `local` `(bool: false)` - Indicates that the token should not be replicated
|
||
globally and instead be local to the current datacenter. Only available in Consul
|
||
1.4 and greater.
|
||
|
||
- `ttl` `(duration: "")` – Specifies the TTL for this role. If not
|
||
provided, the default Vault TTL is used. Uses [duration format strings](/docs/concepts/duration-format).
|
||
|
||
- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
|
||
provided, the default Vault Max TTL is used. Uses [duration format strings](/docs/concepts/duration-format).
|
||
|
||
### Sample Payload
|
||
|
||
To create a client token with policies defined in Consul:
|
||
|
||
```json
|
||
{
|
||
"consul_policies": "policy-1,policy-2"
|
||
}
|
||
```
|
||
|
||
### Parameters for Consul version below 1.4
|
||
|
||
- `lease` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the lease for this role.
|
||
Uses [duration format strings](/docs/concepts/duration-format). If not
|
||
provided, the default Vault lease is used.
|
||
|
||
- `policy` <sup>DEPRECATED (1.11)</sup> `(string: <policy>)` – Specifies the base64-encoded ACL policy. The
|
||
ACL format can be found in the [Consul ACL
|
||
documentation](https://www.consul.io/docs/security/acl/acl-legacy). This is
|
||
required unless the `token_type` is `"management"`.
|
||
|
||
### Sample Payload
|
||
|
||
To create a client token with a base64-encoded policy:
|
||
|
||
```json
|
||
{
|
||
"policy": "a2V5ICIi...=="
|
||
}
|
||
```
|
||
|
||
To create management tokens:
|
||
|
||
```json
|
||
{
|
||
"token_type": "management"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--request POST \
|
||
--header "X-Vault-Token: ..." \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/consul/roles/example-role
|
||
```
|
||
|
||
## Read Role
|
||
|
||
This endpoint queries for information about a Consul role with the given name.
|
||
If no role exists with that name, a 404 is returned.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------- |
|
||
| `GET` | `/consul/roles/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the role to query. This
|
||
is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/consul/roles/example-role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"policy": "abd2...==",
|
||
"lease": "1h0m0s",
|
||
"token_type": "client"
|
||
}
|
||
}
|
||
```
|
||
|
||
## List Roles
|
||
|
||
This endpoint lists all existing roles in the secrets engine.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------- |
|
||
| `LIST` | `/consul/roles` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/consul/roles
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": ["example-role"]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Role
|
||
|
||
This endpoint deletes a Consul role with the given name. Even if the role does
|
||
not exist, this endpoint will still return a successful response.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------------- |
|
||
| `DELETE` | `/consul/roles/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
|
||
is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--request DELETE \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/consul/roles/example-role
|
||
```
|
||
|
||
## Generate Credential
|
||
|
||
This endpoint generates a dynamic Consul token based on the given role
|
||
definition.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------- |
|
||
| `GET` | `/consul/creds/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of an existing role against
|
||
which to create this Consul credential. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/consul/creds/example-role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
|
||
}
|
||
}
|
||
```
|