Backport of NET-1825: More new ACL token creation docs into release/1.16.x (#18257)
NET-1825: More new ACL token creation docs (#18063) Co-authored-by: Paul Glass <pglass@hashicorp.com> Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
hc-github-team-consul-core
GitHub
parent
aa76093615
commit
095b7887cb
|
|
@ -0,0 +1,382 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Create tokens for for Consul external service monitor
|
||||||
|
description: >-
|
||||||
|
Learn how to create ACL tokens for the Consul external service monitor
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create a Consul ESM token
|
||||||
|
|
||||||
|
This topic describes how to create a token for the Consul external service monitor.
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
Consul external service monitor (ESM) can monitor third-party or external services in contexts where you are unable to run a Consul agent. To learn more about Consul ESM, refer to the [Register External Services with Consul Service Discovery](/consul/tutorials/developer-discovery/service-registration-external-services) tutorial.
|
||||||
|
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Core ACL functionality is available in all versions of Consul.
|
||||||
|
|
||||||
|
Consul ESM must present a token linked to policies that grant the following permissions:
|
||||||
|
|
||||||
|
* `agent:read`: Enables checking version compatibility and calculating network coordinates
|
||||||
|
* `key:write`: Enables storing state in the Consul KV store
|
||||||
|
* `node:read`: Enables discovering Consul nodes to monitor
|
||||||
|
* `node:write`: Enables updating status for the nodes that Consul ESM monitors
|
||||||
|
* `service:write`: Enables Consul ESM to register as a service in the catalog
|
||||||
|
* `session:write`: Enables Consul ESM is registered to acquire a leader lock
|
||||||
|
* `acl:read`: (Enterprise-only) Enables Consul ESM to scan namespaces for nodes and health checks to monitor
|
||||||
|
|
||||||
|
Consul ESM only supports `default` admin partitions.
|
||||||
|
|
||||||
|
@include 'create-token-requirements.mdx'
|
||||||
|
|
||||||
|
## Consul ESM token in Consul OSS
|
||||||
|
|
||||||
|
To create a token for Consul ESM, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions for Consul ESM running on an agent with the node name `agent1` to monitor two nodes named `node1` and `node2`. It allows Consul ESM to register into the catalog as the `consul-esm` service and write keys with the prefix `consul-esm/` in the Consul KV store.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
agent "agent1" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
key_prefix "consul-esm/" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
node_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
service "consul-esm" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
session "agent1" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
node "node1" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
node "node2" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent": {
|
||||||
|
"agent1": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"key_prefix": {
|
||||||
|
"consul-esm/": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"node": {
|
||||||
|
"node1": [{
|
||||||
|
"policy": "write"
|
||||||
|
}],
|
||||||
|
"node2": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"node_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service": {
|
||||||
|
"consul-esm": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"session": {
|
||||||
|
"agent1": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `esm-policy.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create \
|
||||||
|
-name "esm-policy" -rules @esm-policy.hcl \
|
||||||
|
-description "Policy for Consul ESM"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `esm-policy.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "esm-policy",
|
||||||
|
"Description": "Policy for Consul ESM",
|
||||||
|
"Rules": "agent \"agent1\" {\n policy = \"read\"\n}\nkey_prefix \"consul-esm/\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nservice \"consul-esm\" {\n policy = \"write\"\n}\nsession \"agent1\" {\n policy = \"write\"\n}\nnode \"node1\" {\n policy = \"write\"\n}\nnode \"node2\" {\n policy = \"write\"\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following example creates an ACL token linked to the policy `esm-policy`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create \
|
||||||
|
-description "Token for Consul ESM" \
|
||||||
|
-policy-name "esm-policy"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates an ACL token linked to the policy `esm-policy`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "esm-policy"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
|
||||||
|
## Consul ESM token in Consul Enterprise
|
||||||
|
|
||||||
|
To create a token for Consul ESM, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions for Consul ESM running on an agent named `agent1` to monitor two nodes named `node1` and `node2`. It allows Consul ESM to register into the catalog as the `consul-esm` service, to write keys with the prefix `consul-esm/` in the Consul KV store, and to scan the `default` and `ns1` namespaces for nodes and health checks to monitor.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
partition "default" {
|
||||||
|
agent "agent1" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
key_prefix "consul-esm/" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
node_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
service "consul-esm" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
session "agent1" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
|
||||||
|
node "node1" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
node "node1" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
|
||||||
|
namespace "default" {
|
||||||
|
acl = "read"
|
||||||
|
}
|
||||||
|
namespace "ns1" {
|
||||||
|
acl = "read"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"partition": {
|
||||||
|
"default": [{
|
||||||
|
"agent": {
|
||||||
|
"agent1": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"key_prefix": {
|
||||||
|
"consul-esm/": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"namespace": {
|
||||||
|
"default": [{
|
||||||
|
"acl": "read"
|
||||||
|
}],
|
||||||
|
"ns1": [{
|
||||||
|
"acl": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"node": {
|
||||||
|
"node1": [{
|
||||||
|
"policy": "write"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"node_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service": {
|
||||||
|
"consul-esm": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"session": {
|
||||||
|
"agent1": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. The example policy contains permissions for multiple namespaces in multiple partitions. You must create ACL policies that grant permissions for multiple namespaces in multiple partitions in the `default` namespace and the `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following command registers a policy defined in `esm-policy.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create -partition "default" -namespace "default" \
|
||||||
|
-name "esm-policy" -rules @esm-policy.hcl \
|
||||||
|
-description "Policy for Consul ESM"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `esm-policy.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "esm-policy",
|
||||||
|
"Description": "Policy for Consul ESM",
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Rules": "partition \"default\" {\n agent \"agent1\" {\n policy = \"read\"\n }\n key_prefix \"consul-esm/\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service \"consul-esm\" {\n policy = \"write\"\n }\n session \"agent1\" {\n policy = \"write\"\n }\n\n node \"node1\" {\n policy = \"write\"\n }\n node \"node1\" {\n policy = \"write\"\n }\n\n namespace \"default\" {\n acl = \"read\"\n }\n namespace \"ns1\" {\n acl = \"read\"\n }\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token must be created in the partition and namespace where the policy was created. The following example creates an ACL token in the `default` namespace in the `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `esm-policy`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create -partition "default" -namespace "default" \
|
||||||
|
-description "Token for Consul ESM" \
|
||||||
|
-policy-name "esm-policy"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates an ACL token linked to the policy `esm-policy`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "esm-policy"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
@ -0,0 +1,331 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Create tokens for service registration
|
||||||
|
description: >-
|
||||||
|
Learn how to create ACL tokens to enable Consul DNS.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create a DNS token
|
||||||
|
|
||||||
|
This topic describes how to create a token that enables the Consul DNS to query services in the network when ACLs are enabled.
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The Consul binary ships with a DNS server that you can use for service discovery in your network. The agent that fulfills DNS lookups requires appropriate ACL permissions to discover services, nodes, and prepared queries registered in Consul.
|
||||||
|
|
||||||
|
A Consul agent must be configured with a token linked to policies that grant the appropriate set of permissions.
|
||||||
|
|
||||||
|
Specify the [`default`](/consul/docs/agent/config/config-files#acl_tokens_default) token to the Consul agent to authorize the agent to respond to DNS queries. Refer to [DNS usage overview](/consul/docs/services/discovery/dns-overview) for details on configuring and using Consul DNS.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Core ACL functionality is available in all versions of Consul.
|
||||||
|
|
||||||
|
The DNS token must be linked to policies that grant the following permissions:
|
||||||
|
|
||||||
|
* `service:read`: Enables the agent to perform service lookups for DNS
|
||||||
|
* `node:read`: Enables node lookups over DNS
|
||||||
|
* `query:read`: Enables the agent to perform prepared query lookups for DNS
|
||||||
|
|
||||||
|
@include 'create-token-requirements.mdx'
|
||||||
|
|
||||||
|
## DNS token in Consul OSS
|
||||||
|
|
||||||
|
To create a token for DNS, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions to enable a Consul agent to respond to DNS queries.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
node_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
service_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
query_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"node_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"query_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `dns-access.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create \
|
||||||
|
-name "dns-access" -rules @dns-access.hcl \
|
||||||
|
-description "DNS Policy"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `dns-access.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "dns-access",
|
||||||
|
"Description": "DNS Policy",
|
||||||
|
"Rules": "node_prefix \"\" {\n policy = \"read\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nquery_prefix \"\" {\n policy = \"read\"\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `dns-access`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create \
|
||||||
|
-description "DNS token" \
|
||||||
|
-policy-name "dns-access"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates the ACL token linked to the policy `dns-access`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "dns-access"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## DNS token in Consul Enterprise
|
||||||
|
|
||||||
|
To create a token for DNS, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions to enable a Consul agent to respond to DNS queries for resources in any namespace in any partition.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
partition_prefix "" {
|
||||||
|
namespace_prefix "" {
|
||||||
|
node_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
service_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
query_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"partition_prefix": {
|
||||||
|
"": [{
|
||||||
|
"namespace_prefix": {
|
||||||
|
"": [{
|
||||||
|
"node_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"query_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. The example policy contains permissions for multiple namespaces in multiple partitions. You must create ACL policies that grant permissions for multiple namespaces in multiple partitions in the `default` namespace and the `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
consul acl policy create -partition "default" -namespace "default" \
|
||||||
|
-name dns-access -rules @dns-access.hcl \
|
||||||
|
-description "DNS Policy"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `dns-access.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "dns-access",
|
||||||
|
"Description": "DNS Policy",
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Rules": "partition_prefix \"\" {\n namespace_prefix \"\" {\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n query_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `dns-access`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create -partition "default" -namespace "default" \
|
||||||
|
-description "DNS token" \
|
||||||
|
-policy-name "dns-access"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates the ACL token linked to the policy `dns-access`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "dns-access"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Apply the token
|
||||||
|
|
||||||
|
Configure the Consul agent with the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command.
|
||||||
|
|
||||||
|
### Apply the token in a file
|
||||||
|
|
||||||
|
Specify the token in the [`default`](/consul/docs/agent/config/config-files#acl_tokens_default) field of the agent configuration file so that the agent can present it and register into the catalog on startup.
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
acl = {
|
||||||
|
enabled = true
|
||||||
|
tokens = {
|
||||||
|
default = "<token>"
|
||||||
|
...
|
||||||
|
}
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Apply the token with a command
|
||||||
|
|
||||||
|
Set the `default` token using the [`acl.token.default`](/consul/docs/agent/config/config-files#acl_tokens_default) command. The following command configures a running Consul agent token with the specified token.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul set-agent-token default <acl-token-secret-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
@ -0,0 +1,312 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Create tokens for service registration
|
||||||
|
description: >-
|
||||||
|
Learn how to create ACL tokens that a server agent in a secondary datacenter can use for ACL token replication between WAN-federated datacenters.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create a replication token
|
||||||
|
|
||||||
|
This topic describes how to configure an ACL token for ACL replication between WAN-federated datacenters. If your Consul clusters are connected through peer connections, ACL replication is not required. To learn more about cluster peering, refer to the [comparison between WAN federation and cluster peering](/consul/docs/connect/cluster-peering#compared-with-wan-federation).
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
Consul agents must present a token linked to policies that grant the appropriate set of permissions.
|
||||||
|
Specify the [`replication`](/consul/docs/agent/config/config-files#acl_tokens_replication) token on each server in a non-primary datacenter. For hands-on instructions on how to configure ACL replication across datacenters, refer to the [ACL Replication for Multiple Datacenters](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters) tutorial.
|
||||||
|
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Core ACL functionality is available in all versions of Consul.
|
||||||
|
|
||||||
|
For a Consul server agent with ACL replication enabled in a secondary datacenter, the token must be linked to a policy that grants the following permissions:
|
||||||
|
|
||||||
|
* `acl:write`: Enables replication of ACL resources
|
||||||
|
* `operator:write`: Enables replication of the proxy-defaults configuration entry and enables CA certification signing in the secondary datacenter
|
||||||
|
* `service:read` and `intention:read`: Enables replication of the service-defaults and intentions configuration entries
|
||||||
|
|
||||||
|
@include 'create-token-requirements.mdx'
|
||||||
|
|
||||||
|
## Replication token in Consul OSS
|
||||||
|
|
||||||
|
To create a token for ACL replication, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions for ACL replication.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
acl = "write"
|
||||||
|
operator = "write"
|
||||||
|
service_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
intentions = "read"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"acl": "write",
|
||||||
|
"operator": "write",
|
||||||
|
"service_prefix": {
|
||||||
|
"": [{
|
||||||
|
"intentions": "read",
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `acl-replication.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create \
|
||||||
|
-name "acl-replication" -rules @acl-replication.hcl \
|
||||||
|
-description "ACL replication token"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `acl-replication.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "acl-replication",
|
||||||
|
"Description": "ACL replication",
|
||||||
|
"Rules": "acl = \"write\"\noperator = \"write\"\nservice_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `acl-replication`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create \
|
||||||
|
-description "ACL replication" \
|
||||||
|
-policy-name "acl-replication"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates the ACL token linked to the policy `acl-replication`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "acl-replication"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Replication token in Consul Enterprise
|
||||||
|
|
||||||
|
To create a token for ACL replication, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The following example policy grants the appropriate permissions for ACL replication.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
operator = "write"
|
||||||
|
service_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
intentions = "read"
|
||||||
|
}
|
||||||
|
namespace_prefix "" {
|
||||||
|
acl = "write"
|
||||||
|
service_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
intentions = "read"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"namespace_prefix": {
|
||||||
|
"": [{
|
||||||
|
"acl": "write",
|
||||||
|
"service_prefix": {
|
||||||
|
"": [{
|
||||||
|
"intentions": "read",
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"operator": "write",
|
||||||
|
"service_prefix": {
|
||||||
|
"": [{
|
||||||
|
"intentions": "read",
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
You can specify an admin partition, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the specified scopes. The policy for replication must be created in the `default` namespace and `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `acl-replication.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create -partition "default" -namespace "default" \
|
||||||
|
-name "acl-replication" -rules @acl-replication.hcl \
|
||||||
|
-description "ACL replication token"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `acl-replication.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "acl-replication",
|
||||||
|
"Description": "ACL replication",
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Rules": "operator = \"write\"\nservice_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n}\nnamespace_prefix \"\" {\n acl = \"write\"\n service_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n }\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create -partition "default" -namespace "default" \
|
||||||
|
-description "ACL replication" \
|
||||||
|
-policy-name "acl-replication"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates the ACL token linked to the policy `acl-replication`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "acl-replication"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Apply the token
|
||||||
|
|
||||||
|
Configure the Consul agent with the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command.
|
||||||
|
|
||||||
|
### Apply the token in a file
|
||||||
|
|
||||||
|
Specify the token in the [`replication`](/consul/docs/agent/config/config-files#acl_tokens_replication) field of the agent configuration file so that the agent can present it and register into the catalog on startup.
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
acl = {
|
||||||
|
enabled = true
|
||||||
|
tokens = {
|
||||||
|
replication = "<token>"
|
||||||
|
...
|
||||||
|
}
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Apply the token with a command
|
||||||
|
|
||||||
|
Set the `replication` token using the [`consul set-agent-token`](/consul/commands/acl/set-agent-token) command. The following command configures a running Consul agent token with the specified token.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul set-agent-token replication <acl-token-secret-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
@ -0,0 +1,173 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Create tokens for snapshot agents
|
||||||
|
description: >-
|
||||||
|
Learn how to create an ACL token for the Consul snapshot agent.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create a snapshot agent token
|
||||||
|
|
||||||
|
This topic describes how to create a token for the Consul snapshot agent.
|
||||||
|
|
||||||
|
<EnterpriseAlert />
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The `consul snapshot agent` command starts a process that takes snapshots of the state of the Consul
|
||||||
|
servers and either saves them locally or pushes them to a remote storage service. Refer to [Consul Snapshot Agent](/consul/commands/snapshot/agent) for additional information.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Core ACL functionality is available in all versions of Consul.
|
||||||
|
|
||||||
|
### Requirements for the `agent` command
|
||||||
|
|
||||||
|
The [`agent`](/consul/commands/snapshot/agent) subcommand requires [Consul Enterprise](https://www.hashicorp.com/products/consul/). All other [`snapshot` subcommands](/consul/commands/snapshot) are available in the open source version of Consul.
|
||||||
|
|
||||||
|
### Snapshot agent ACL requirements
|
||||||
|
|
||||||
|
The Consul snapshot agent must present a token linked to policies that grant the following set of permissions.
|
||||||
|
|
||||||
|
* `acl:write`: Enables the agent read and snapshot ACL data
|
||||||
|
* `key:write`: Enables the agent to create a key in the Consul KV store that serves as a leader election lock when multiple snapshot agents are running in an environment
|
||||||
|
* `session:write`: Enables the agent to create sessions for the specified Consul node where it is running
|
||||||
|
* `service:write`: Enables the agent to register into the catalog
|
||||||
|
|
||||||
|
@include 'create-token-requirements.mdx'
|
||||||
|
|
||||||
|
## Create a token
|
||||||
|
|
||||||
|
To create a token for the snapshot agent, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions for a snapshot agent running on a node named `server-1234` to register into the catalog as the `consul-snapshot` service. It uses the key `consul-snapshot/lock` for a leader election lock.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
acl = "write"
|
||||||
|
key "consul-snapshot/lock" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
session "server-1234" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
service "consul-snapshot" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"acl": "write",
|
||||||
|
"key": {
|
||||||
|
"consul-snapshot/lock": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service": {
|
||||||
|
"consul-snapshot": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"session": {
|
||||||
|
"server-1234": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
You can specify an admin partition and namespace when creating policies in Consul Enterprise. Policies are only valid in the specified scopes. You must create the policy for the snapshot agent in the `default` namespace in the `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `snapshot-agent.hcl`:
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create -partition "default" -namespace "default" \
|
||||||
|
-name snapshot-agent -rules @snapshot-agent.hcl \
|
||||||
|
-description "Snapshot agent policy"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `snapshot-agent.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "snapshot-agent",
|
||||||
|
"Description": "Snapshot agent policy",
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default",
|
||||||
|
"Rules": "acl = \"write\"\nkey \"consul-snapshot/lock\" {\n policy = \"write\"\n}\nsession \"server-1234\" {\n policy = \"write\"\n}\nservice \"consul-snapshot\" {\n policy = \"write\"\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
You can specify an admin partition and namespace when creating tokens in Consul Enterprise. Tokens are only valid in the specified scopes. The snapshot agent token must be created in the `default` namespace in the `default` partition.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `snapshot-agent`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create -partition "default" -namespace "default" \
|
||||||
|
-description "Snapshot agent token" \
|
||||||
|
-policy-name "snapshot-agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "snapshot-agent"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Partition": "default",
|
||||||
|
"Namespace": "default"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
|
@ -0,0 +1,164 @@
|
||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: Create tokens for service registration
|
||||||
|
description: Learn how to create an ACL token for Vault’s Consul storage backend.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create a token for Vault with Consul storage backend
|
||||||
|
|
||||||
|
This topic describes how to create a token for Vault’s Consul storage backend.
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
If you are using Vault to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/consul/docs/dynamic-app-config/kv) and the [Vault storage documentation](/vault/docs/configuration/storage) for additional information.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Core ACL functionality is available in all versions of Consul.
|
||||||
|
|
||||||
|
The Vault Consul storage backend must present a token linked to policies that grant the following permissions:
|
||||||
|
|
||||||
|
* `agent:read`: Provides KV visibility to all agents
|
||||||
|
* `key:write`: Enables writing to the KV store
|
||||||
|
* `service:write`: Enables the Vault service to register into the catalog
|
||||||
|
* `session:write`: Enables the agent to initialize a new session
|
||||||
|
|
||||||
|
@include 'create-token-requirements.mdx'
|
||||||
|
|
||||||
|
## Create a token linked to a policy
|
||||||
|
|
||||||
|
To create a token for Vault’s Consul storage backend, you must define a policy, register the policy with Consul, and link the policy to a token.
|
||||||
|
|
||||||
|
### Define a policy
|
||||||
|
|
||||||
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
||||||
|
|
||||||
|
The following example policy is defined in a file. The policy grants the appropriate permissions to enable Vault to register as a service named `vault` and provides access to the `vault/` path in Consul's KV store.
|
||||||
|
|
||||||
|
<CodeTabs>
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
agent_prefix "" {
|
||||||
|
policy = "read"
|
||||||
|
}
|
||||||
|
key_prefix "vault/" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
service "vault" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
session_prefix "" {
|
||||||
|
policy = "write"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "read"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"key_prefix": {
|
||||||
|
"vault/": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"service": {
|
||||||
|
"vault": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
},
|
||||||
|
"session_prefix": {
|
||||||
|
"": [{
|
||||||
|
"policy": "write"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</CodeTabs>
|
||||||
|
|
||||||
|
### Register the policy with Consul
|
||||||
|
|
||||||
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
|
||||||
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
||||||
|
|
||||||
|
The following example registers a policy defined in `vault-storage-backend.hcl`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl policy create -partition "default" -namespace "default" \
|
||||||
|
-name vault-storage-backend -rules @vault-storage-backend.hcl \
|
||||||
|
-description "Policy for the Vault Consul storage backend"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example registers the policy defined in `vault-storage-backend.hcl`. You must embed policy rules in the `Rules` field of the request body.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Name": "vault-storage-backend",
|
||||||
|
"Description": "Policy for the Vault Consul storage backend",
|
||||||
|
"Rules": "agent_prefix \"\" {\n policy = \"read\"\n}\nkey_prefix \"vault/\" {\n policy = \"write\"\n}\nservice \"vault\" {\n policy = \"write\"\n}\nsession_prefix \"\" {\n policy = \"write\"\n}\n"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### Link the policy to a token
|
||||||
|
|
||||||
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="CLI" group="CLI">
|
||||||
|
|
||||||
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
||||||
|
|
||||||
|
The following command creates the ACL token linked to the policy `vault-storage-backend`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul acl token create \
|
||||||
|
-description "Token for the Vault Consul storage backend" \
|
||||||
|
-policy-name "vault-storage-backend"
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="API" group="API">
|
||||||
|
|
||||||
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
||||||
|
|
||||||
|
The following example creates the ACL token linked to the policy `vault-storage-backend`.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
||||||
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
||||||
|
--data '{
|
||||||
|
"Policies": [
|
||||||
|
{
|
||||||
|
"Name": "vault-storage-backend"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
|
@ -165,7 +165,7 @@ service_prefix "" {
|
||||||
|
|
||||||
### Register the policy with Consul
|
### Register the policy with Consul
|
||||||
|
|
||||||
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
<Tabs>
|
<Tabs>
|
||||||
|
|
||||||
|
|
@ -299,7 +299,7 @@ partition "ptn1" {
|
||||||
|
|
||||||
### Register the policy with Consul
|
### Register the policy with Consul
|
||||||
|
|
||||||
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
|
||||||
|
|
||||||
<Tabs>
|
<Tabs>
|
||||||
|
|
||||||
|
|
@ -340,7 +340,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf
|
||||||
|
|
||||||
### Link the policy to a token
|
### Link the policy to a token
|
||||||
|
|
||||||
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
<Tabs>
|
<Tabs>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -950,6 +950,26 @@
|
||||||
{
|
{
|
||||||
"title": "Create a terminating gateway token",
|
"title": "Create a terminating gateway token",
|
||||||
"path": "security/acl/tokens/create/create-a-terminating-gateway-token"
|
"path": "security/acl/tokens/create/create-a-terminating-gateway-token"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Create a DNS token",
|
||||||
|
"path": "security/acl/tokens/create/create-a-dns-token"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Create a replication token",
|
||||||
|
"path": "security/acl/tokens/create/create-a-replication-token"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Create a snapshot agent token",
|
||||||
|
"path": "security/acl/tokens/create/create-a-snapshot-agent-token"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Create a token for Vault's Consul storage backend",
|
||||||
|
"path": "security/acl/tokens/create/create-a-token-for-vault-consul-storage"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Create a Consul ESM token",
|
||||||
|
"path": "security/acl/tokens/create/create-a-consul-esm-token"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue