luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Update Consul secrets features docs, api-docs for 1.11 (#15854) 

* Overhaul consul docs and api-docs for new 1.11 features

Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
Co-authored-by: Calvin Leung Huang <1883212+calvn@users.noreply.github.com>
Co-authored-by: John-Michael Faircloth <fairclothjm@users.noreply.github.com>
This commit is contained in:
Robert 2022-06-08 13:54:55 -05:00 committed by GitHub
parent 5259cd0ab2
commit 91b298d274
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 191 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
website/content/api-docs/secret/consul.mdx
View File

@ -35,7 +35,7 @@ Consul tokens.
- `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.
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.
@ -70,7 +70,9 @@ $ curl \
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.
updated attributes. At least one of `consul_policies`, `consul_roles`,
`service_identities`, or `node_identities` is required depending on the
Consul version.
| Method | Path |
| :----- | :-------------------- |
@ -78,10 +80,10 @@ updated attributes.
### Parameters for Consul versions 1.11 and above
- `partition` `(string: "")` <EnterpriseAlert inline /> - Specifies the Consul admin partition the token
will be generated within. The partition must exist, and the policies or roles assigned to the
Vault role must also exist inside the given partition. If not provided, the "default"
partition is used.
- `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:
@ -93,14 +95,13 @@ To create a client token within a particular Consul admin partition:
### Parameters for Consul versions 1.8 and above
- `consul_namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the Consul namespace the token
will be generated within. The namespace must exist, and the policies or roles assigned to the
Vault role must also exist inside the given Consul namespace. If not provided, the "default"
namespace is used.
- `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.
- `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:
@ -114,34 +115,61 @@ To create a client token with node identities attached:
```json
{
"node_identities": "client-1:dc1,client-2:dc1"
"node_identities": [
"client-1:dc1",
"client-2:dc1"
]
}
```
### Parameters for Consul versions 1.5 and above
### 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` `(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`, `policies`, and `consul_roles` parameters are not required.
Defaults to `"client`".
- `policy` `(string: <policy>)` – Specifies the base64-encoded ACL policy. This is
required unless the `token_type` is `"management"`. [Deprecated as of Consul 1.4 and
- `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)
- `policies` `(list: <policy or policies>)` – The list of policies to assign to the
generated token. Either `policies` or `consul_roles` are required for Consul 1.5 and
above, or just `policies` if using Consul 1.4.
- `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)
- `consul_roles` `(list: <role or roles>)` – The list of Consul roles to assign to the
generated token. Either `policies` or `consul_roles` are required for Consul 1.5 and above.
- `policies` <sup>DEPRECATED (1.11)</sup> `(list: <policy or policies>)` - Same as `consul_policies`.
Deprecated in favor of using `consul_policies`.
- `service_identities` `(list: <service identity or identities>)` - The list of
service identities to assign to the generated token. This may be a semicolon-separated list to
attach multiple service identities to a token.
- `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
@ -157,6 +185,35 @@ To create a client token with node identities attached:
### 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. 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` <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
@ -165,30 +222,6 @@ To create management tokens:
}
```
To create a client token with defined policies:
```json
{
"policies": "global-management,policy-2"
}
```
To create a client token with defined roles:
```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"
}
```
### Sample Request
```shell-session
@ -199,37 +232,6 @@ $ curl \
http://127.0.0.1:8200/v1/consul/roles/example-role
```
### Parameters for Consul version below 1.4
- `lease` `(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` `(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 custom base64-encoded policy:
```json
{
"policy": "a2V5ICIi...=="
}
```
### 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.

1
website/content/docs/deprecation/index.mdx
View File

@ -28,6 +28,7 @@ This announcement page is maintained and updated periodically to communicate imp
| *****AppID (OSS) | v0.6 | N/A | v1.13 | Use the alternative feature: [AppRole auth method](https://www.vaultproject.io/docs/auth/approle) | [AppID Auth Method Deprecation Notice](/docs/auth/app-id) |
| AAD Graph on Azure Secrets Engine | v1.10 | 1.11 | v1.12 | Microsoft will end its support of the [AAD Graph API on June 30, 2022](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview). Support for Microsoft Graph API was introduced in Vault 1.9. If your Vault deployment is on a prior release, you may use the Azure Secrets Engine as an external plugin while you plan to upgrade. | [AAD (Azure Active Directory](https://vault-git-post-1-10-doc-changes-hashicorp.vercel.app/docs/secrets/azure#aad-azure-active-directory) |
| Optional `api_token` parameter in Okta Auth Method | v1.4 | 1.11 | v1.12 | The `api_token` parameter on the Okta Auth Method will change from being optional to being required. | [API Documentation](https://www.vaultproject.io/api-docs/auth/okta#api_token) |
| Consul secrets engine parameter changes | v1.11 | N/A | N/A | The `policies` parameter on the Consul secrets engine has been changed in favor of `consul_policies`. The `token_type` and `policy` parameters have been deprecated as the latest versions of Consul no longer support the older ACL system they were used for. | [Consul secrets engine API documentation](/api-docs/secret/consul) |
*If you use **Standalone DB Engines** or **AppID (OSS)**, you should actively plan to migrate away from their usage. If you use these features and upgrade to Release 1.12, Vault will log error messages and shut down, and any attempts to add new mounts will result in an error.
If you are still using these deprecated features and attempt to upgrade to 1.13 (the target feature removal timeframe), you will not be able to start up Vault without downgrading and migrating away from these features.

197
website/content/docs/secrets/consul.mdx
View File

@ -27,128 +27,137 @@ management tool.
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.
1. Vault can bootstrap the ACL system of your Consul cluster if it has
not already been done. In this case, you only need the address of your
Consul cluster to configure the Consul secret engine:
1. Configure Vault to connect and authenticate to Consul.
```text
$ vault write consul/config/access \
address=127.0.0.1:8500
Success! Data written to: consul/config/access
```
Vault can bootstrap the Consul ACL system automatically if it hasn't already been done. If you
have already bootstrapped the ACL system, then you will need to provide Vault with a management
token. This can either be the bootstrap token or another management token you've created
yourself.
If you have already bootstrapped the ACL system of your Consul cluster, you
will need to give Vault a management token:
1. Configuring Vault without previously bootstrapping the Consul ACL system:
In Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul, using the
`acl_master_token` from your Consul configuration file or another management
token:
```shell-session
$ vault write consul/config/access \
address="127.0.0.1:8500"
Success! Data written to: consul/config/access
```
```sh
$ curl \
--header "X-Consul-Token: my-management-token" \
--request PUT \
--data '{"Name": "sample", "Type": "management"}' \
https://consul.rocks/v1/acl/create
```
~> **Note:** Vault will silently store the bootstrap token as the configuration token when
it performs the automatic bootstrap; it will not be presented to the user. If you need
another management token, you will need to generate one by writing a Vault role with the
`global-management` policy and then reading new creds back from it.
1. Configuring Vault after manually bootstrapping the Consul ACL system:
Vault must have a management type token so that it can create and revoke ACL
tokens. The response will return a new token:
1. For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
```json
{
"ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
}
```
```shell-session
$ CONSUL_HTTP_TOKEN="<bootstrap-token>" consul acl token create -policy-name="global-management"
AccessorID: 865dc5e9-e585-3180-7b49-4ddc0fc45135
SecretID: ef35f0f1-885b-0cab-573c-7c91b65a7a7e
Description:
Local: false
Create Time: 2018-10-22 17:40:24.128188 -0700 PDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
```shell-session
$ vault write consul/config/access \
address="127.0.0.1:8500" \
token="ef35f0f1-885b-0cab-573c-7c91b65a7a7e"
Success! Data written to: consul/config/access
```
```shell-session
$ CONSUL_HTTP_TOKEN="<management-token>" consul acl token create -policy-name="global-management"
AccessorID: 865dc5e9-e585-3180-7b49-4ddc0fc45135
SecretID: ef35f0f1-885b-0cab-573c-7c91b65a7a7e
Description:
Local: false
Create Time: 2018-10-22 17:40:24.128188 -0700 PDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
1. For Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul, using the
`acl_master_token` from your Consul configuration file or another management token:
1. Configure Vault to connect and authenticate to Consul:
```shell-session
$ curl \
--header "X-Consul-Token: my-management-token" \
--request PUT \
--data '{"Name": "sample", "Type": "management"}' \
https://consul.rocks/v1/acl/create
```
```shell-session
$ 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 must have a management type token so that it can create and revoke ACL
tokens. The response will return a new token:
```json
{
"ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
}
```
1. 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, a list of policies or roles, or a set of
service or node identities.
When users generate credentials, they are generated against this role.
you will either provide a policy document and a token type, a list of policies or roles, or a set of
service or node identities. 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](https://www.consul.io/docs/security/acl/acl-legacy).
1. For Consul versions 1.8 and above, attach [a Consul node identity](https://www.consul.io/commands/acl/token/create#node-identity) to the role.
Write a policy and proceed to link it to the role:
```shell-session
$ vault write consul/roles/my-role \
node_identities="server-1:dc1" \
node_identities="server-2:dc1"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role policy="$(base64 <<< 'key "" { policy = "read" }')"
Success! Data written to: consul/roles/my-role
```
1. For Consul versions 1.5 and above, attach either [a role in Consul](https://www.consul.io/api/acl/roles) or [a Consul service identity](https://www.consul.io/commands/acl/token/create#service-identity) to the role:
For Consul versions 1.4 and above, [generate a policy in Consul](https://www.consul.io/docs/guides/acl.html),
and proceed to link it to the role:
```shell-session
$ vault write consul/roles/my-role consul_roles="api-server"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role policies="readonly"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role \
service_identities="myservice-1:dc1,dc2" \
service_identities="myservice-2:dc1"
Success! Data written to: consul/roles/my-role
```
1. For Consul versions 1.4 and above, generate [a policy in Consul](https://www.consul.io/docs/guides/acl.html),
and proceed to link it to the role:
For Consul versions 1.5 and above, [generate a role in Consul](https://www.consul.io/api/acl/roles) and
proceed to link it to the role, or [attach a Consul service identity](https://www.consul.io/commands/acl/token/create#service-identity) to the role:
```shell-session
$ vault write consul/roles/my-role consul_policies="readonly"
Success! Data written to: consul/roles/my-role
```
1. For Consul versions below 1.4, the policy must be base64-encoded. The policy language is
[documented by Consul](https://www.consul.io/docs/security/acl/acl-legacy). Support for this method is
deprecated as of Vault 1.11.
```shell-session
$ vault write consul/roles/my-role consul_roles="api-server"
Success! Data written to: consul/roles/my-role
```
Write a policy and proceed to link it to the role:
```shell-session
$ vault write consul/roles/my-role service_identities="myservice:dc1,dc2"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role policy="$(base64 <<< 'key "" { policy = "read" }')"
Success! Data written to: consul/roles/my-role
```
For Consul versions 1.8 and above, [attach a Consul node identity](https://www.consul.io/commands/acl/token/create#node-identity) to the 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".
```shell-session
$ vault write consul/roles/my-role node_identities="server-1:dc1"
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".
1. For Enterprise users, you may further limit a role's access by adding the optional parameters `consul_namespace` and/or
1. You may further limit a role's access by adding the optional parameters `consul_namespace` and
`partition`. Please refer to Consul's [namespace documentation](https://www.consul.io/docs/enterprise/namespaces) and
[admin partition documentation](https://www.consul.io/docs/enterprise/admin-partitions) for further information about
these features.
For Consul versions 1.7 and above, link a Consul namespace to the role:
1. For Consul version 1.11 and above, link an admin partition to a role:
```shell-session
$ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
Success! Data written to: consul/roles/my-role
```
1. For Consul versions 1.7 and above, link a Consul namespace to the role:
For Consul version 1.11 and above, link an admin partition to a role:
```shell-session
$ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
Success! Data written to: consul/roles/my-role
```
```shell-session
$ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
Success! Data written to: consul/roles/my-role
```
## Usage