Skip to content

Latest commit

 

History

History
349 lines (255 loc) · 9.45 KB

consul.mdx

File metadata and controls

349 lines (255 loc) · 9.45 KB
Raw
layout page_title description
api
Consul - Secrets Engines - HTTP API
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.

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

{
  "address": "127.0.0.1:8500",
  "scheme": "https",
  "token": "adha..."
}

Sample Request

$ 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: "default") - 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 it's not provided, the partition default is used.

To create a client token within a particular Consul admin partition:

{
  "partition": "admin1"
}

Parameters for Consul versions 1.8 and above

  • consul_namespace (string: "default") - 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.

  • 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 within a particular Consul namespace:

{
  "consul_namespace": "ns1"
}

To create a client token with node identities attached:

{
  "node_identities": [
      "client-1:dc1",
      "client-2:dc1"
    ]
}

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

{
  "consul_roles": "role-a,role-b"
}

To create a client token with service identities attached:

{
  "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 DEPRECATED (1.11) (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.

  • policy DEPRECATED (1.11) (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.

  • policies DEPRECATED (1.11) (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. This is provided as a string duration with a time suffix like "30s" or "1h" or as seconds. If not provided, the default Vault TTL is used.

  • max_ttl (duration: "") – Specifies the max TTL for this role. This is provided as a string duration with a time suffix like "30s" or "1h" or as seconds. If not provided, the default Vault Max TTL is used.

Sample Payload

To create a client token with policies defined in Consul:

{
  "consul_policies": "policy-1,policy-2"
}

Parameters for Consul version below 1.4

  • lease DEPRECATED (1.11) (string: "") – Specifies the lease for this role. This is provided as a string duration with a time suffix like "30s" or "1h". If not provided, the default Vault lease is used.

  • policy DEPRECATED (1.11) (string: <policy>) – Specifies the base64-encoded ACL policy. The ACL format can be found in the Consul ACL documentation. This is required unless the token_type is "management".

Sample Payload

To create a client token with a base64-encoded policy:

{
  "policy": "a2V5ICIi...=="
}

To create management tokens:

{
  "token_type": "management"
}

Sample Request

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/consul/roles/example-role

Sample Response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/consul/roles

Sample Response

{
  "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

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/consul/creds/example-role

Sample Response

{
  "data": {
    "token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
  }
}