luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #12972 from hashicorp/docs/simplify-acl-policy-examples 

* Fix JSON formatted example ACL policies
* Remove HCL examples of roles since only JSON payloads can be used
* Remove unnecessary quotes from HCL variables
* Clarify purpose of example ACL rules and policies
* Redirect /api-docs/acl/acl to the new URL
This commit is contained in:
Blake Covarrubias 2022-05-13 10:39:37 -07:00 committed by GitHub
parent 7de052dfbe e653cb58ad
commit d33d06e033
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 348 additions and 439 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
website/content/docs/discovery/checks.mdx
View File

@ -151,7 +151,7 @@ A script check:
```hcl ```hcl
check = { check = {
id = "mem-util" id = "mem-util"
name = "Memory utilization" name = "Memory utilization"
args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"] args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"]
interval = "10s" interval = "10s"
timeout = "1s" timeout = "1s"
@ -186,12 +186,12 @@ check = {
tls_skip_verify = false tls_skip_verify = false
method = "POST" method = "POST"
header = { header = {
Content-Type = ["application/json"] Content-Type = ["application/json"]
} }
body = "{\"method\":\"health\"}" body = "{\"method\":\"health\"}"
disable_redirects = true disable_redirects = true
interval = "10s" interval = "10s"
timeout = "1s" timeout = "1s"
} }
``` ```
@ -248,11 +248,11 @@ A TTL check:
<CodeTabs heading="TTL Check"> <CodeTabs heading="TTL Check">
```hcl ```hcl
check = { check = {
id = "web-app" id = "web-app"
name = "Web App Status" name = "Web App Status"
notes = "Web app does a curl internally every 10 seconds" notes = "Web app does a curl internally every 10 seconds"
ttl = "30s" ttl = "30s"
} }
``` ```
@ -305,11 +305,11 @@ A gRPC check for the whole application:
```hcl ```hcl
check = { check = {
id = "mem-util" id = "mem-util"
name = "Service health status" name = "Service health status"
grpc = "127.0.0.1:12345" grpc = "127.0.0.1:12345"
grpc_use_tls = true grpc_use_tls = true
interval = "10s" interval = "10s"
} }
``` ```
@ -482,11 +482,11 @@ health check definition, like so:
<CodeTabs heading="Status Field Example"> <CodeTabs heading="Status Field Example">
```hcl ```hcl
check = { check = {
"id": "mem", id = "mem"
"args": ["/bin/check_mem", "-limit", "256MB"] args = ["/bin/check_mem", "-limit", "256MB"]
"interval": "10s" interval = "10s"
"status": "passing" status = "passing"
} }
``` ```
@ -516,10 +516,10 @@ provided by adding a `service_id` field to a check configuration:
<CodeTabs heading="Status Field Example"> <CodeTabs heading="Status Field Example">
```hcl ```hcl
check = { check = {
id = "web-app" id = "web-app"
name = "Web App Status" name = "Web App Status"
service_id = "web-app" service_id = "web-app"
ttl = "30s" ttl = "30s"
} }
``` ```
@ -635,7 +635,7 @@ checks = [
name = "HTTP TCP on port 80" name = "HTTP TCP on port 80"
tcp = "localhost:80" tcp = "localhost:80"
interval = "10s" interval = "10s"
timeout = "1s" timeout = "1s"
success_before_passing = 3 success_before_passing = 3
failures_before_warning = 1 failures_before_warning = 1
failures_before_critical = 3 failures_before_critical = 3

127
website/content/docs/security/acl/acl-policies.mdx
View File

@ -32,13 +32,15 @@ A rule is composed of a resource declaration and an access level defined with th
```hcl ```hcl
<resource> { <resource> {
policy = "<policy disposition>" policy = "<policy disposition>"
} }
``` ```
```json ```json
"<resource>": [{ {
"policy": "<policy disposition>" "<resource>": {
}] "policy": "<policy disposition>"
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -60,11 +62,13 @@ The following syntax describes how to include a resource label in the rule:
``` ```
```json ```json
"<resource>": [{ {
"<label>": [{ "<resource>": {
"policy": "<policy disposition>" "<label>": {
}] "policy": "<policy disposition>"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -85,7 +89,9 @@ Use the following syntax to create rules for these resources:
``` ```
```json ```json
"<resource>": "<policy disposition>" {
"<resource>": "<policy disposition>"
}
``` ```
</CodeTabs> </CodeTabs>
@ -115,11 +121,13 @@ service "web-prod" {
``` ```
```json ```json
"service": [{ {
"web-prod" : [{ "service": {
"policy" : "deny" "web-prod": {
}] "policy": "deny"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -135,11 +143,13 @@ service_prefix "web" {
``` ```
```json ```json
"service_prefix": [{ {
"web" : [{ "service_prefix": {
"policy" : "write" "web": {
}] "policy": "write"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -155,11 +165,13 @@ service_prefix "" {
``` ```
```json ```json
"service_prefix" : [{ {
"" : [{ "service_prefix": {
"policy" :"read" "": {
}] "policy":"read"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -209,38 +221,22 @@ operator = "read"
```json ```json
{ {
"key": [ "key_prefix": {
{ "": {
"foo/bar/secret": [ "policy": "read"
{
"policy": "deny"
}
]
}
],
"key_prefix": [
{
"": [
{
"policy": "read"
}
]
}, },
{ "foo/": {
"foo/": [ "policy": "write"
{
"policy": "write"
}
]
}, },
{ "foo/private/": {
"foo/private/": [ "policy": "deny"
{
"policy": "deny"
}
]
} }
], },
"key": {
"foo/bar/secret": {
"policy": "deny"
}
},
"operator": "read" "operator": "read"
} }
``` ```
@ -283,7 +279,7 @@ You can can define several attributes that attach additional metadata and specif
### HTTP API Endpoint ### HTTP API Endpoint
The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api-docs/acl/acl) for details about the API. The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api-docs/acl) for details about the API.
The following example adds a set of rules to a policy called `my-app-policy`. The policy defines access to the `key` resource (Consul K/V). The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL: The following example adds a set of rules to a policy called `my-app-policy`. The policy defines access to the `key` resource (Consul K/V). The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL:
@ -457,31 +453,37 @@ service "consul-snapshot" {
If you are using [Vault](https://www.vaultproject.io/docs) 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](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information. If you are using [Vault](https://www.vaultproject.io/docs) 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](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information.
In the following example, Vault is registered as a service and provided access to Consul's KV store. In the following example, the ACL policy enables Vault to register as a service
and provides access to the `vault/` path in Consul's KV store.
<CodeTabs> <CodeTabs>
```hcl ```hcl
# Provide KV visibility to all agents. # Provide KV visibility to all agents.
agent_prefix "" { agent_prefix "" {
"policy" = "read" policy = "read"
} }
# Enable resources prefixed with 'vault/' to write to the KV # Enable resources prefixed with 'vault/' to write to the KV
key_prefix "vault/" { key_prefix "vault/" {
"policy" = "write" policy = "write"
} }
# Enable the vault service to write to the KV # Enable the vault service to write to the KV
service "vault" { service "vault" {
"policy" = "write" policy = "write"
} }
# Enable the agent to initialize a new session. # Enable the agent to initialize a new session.
session_prefix "" { session_prefix "" {
"policy" = "write" policy = "write"
} }
``` ```
```json ```json
{ {
"agent_prefix": {
"": {
"policy": "read"
}
},
"key_prefix": { "key_prefix": {
"vault/": { "vault/": {
"policy": "write" "policy": "write"
@ -492,11 +494,6 @@ session_prefix "" {
"policy": "write" "policy": "write"
} }
}, },
"agent_prefix": {
"": {
"policy": "read"
}
},
"session_prefix": { "session_prefix": {
"": { "": {
"policy": "write" "policy": "write"

71
website/content/docs/security/acl/acl-roles.mdx
View File

@ -79,8 +79,6 @@ Service identities are used during the authorization process to automatically ge
Use the following syntax to define a service identity: Use the following syntax to define a service identity:
<CodeTabs>
```json ```json
{ {
"ServiceIdentities": [ "ServiceIdentities": [
@ -92,16 +90,6 @@ Use the following syntax to define a service identity:
} }
``` ```
```hcl
"ServiceIdentities" = {
"ServiceName" = "<service name>"
"Datacenters" = ["<datacenter name>"]
}
```
</CodeTabs>
- `ServiceIdentities`: Declares a service identity block. - `ServiceIdentities`: Declares a service identity block.
- `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy. - `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy.
- `ServiceIdentities.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional. - `ServiceIdentities.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional.
@ -136,28 +124,6 @@ Refer to the [rules reference](/docs/security/acl/acl-rules) for information abo
The following role configuration contains service identities for the `web` and `db` services. Note that the `db` service is also scoped to the `dc1` datacenter so that the policy will only be applied to instances of `db` in `dc1`. The following role configuration contains service identities for the `web` and `db` services. Note that the `db` service is also scoped to the `dc1` datacenter so that the policy will only be applied to instances of `db` in `dc1`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```hcl
Description = "Showcases all input parameters"
Name = "example-role"
Policies = {
ID = "783beef3-783f-f41f-7422-7087dc272765"
}
Policies = {
Name = "node-read"
}
ServiceIdentities = {
ServiceName = "web"
}
ServiceIdentities = {
Datacenters = ["dc1"]
ServiceName = "db"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json"> <CodeBlockConfig filename="example-role.json">
```json ```json
@ -191,7 +157,6 @@ ServiceIdentities = {
``` ```
</CodeBlockConfig> </CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token: During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token:
@ -243,9 +208,7 @@ node_prefix "" {
## Node Identities ## Node Identities
<!-- -> Added in Consul 1.8.1 -- remove and lean on doc version? --> You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container.
You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container.
Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent. Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
@ -253,8 +216,6 @@ Node identities enable you to quickly construct policies for nodes, rather than
Use the following syntax to define a node identity: Use the following syntax to define a node identity:
<CodeTabs>
```json ```json
{ {
"NodeIdentities": [ "NodeIdentities": [
@ -266,16 +227,6 @@ Use the following syntax to define a node identity:
} }
``` ```
```hcl
NodeIdentities = {
NodeName = "<node name>"
Datacenter = "<datacenter name>"
}
```
</CodeTabs>
- `NodeIdentities`: Declares a node identity block. - `NodeIdentities`: Declares a node identity block.
- `NodeIdentities.NodeName`: String value that specifies the name of the node you want to associate with the policy. - `NodeIdentities.NodeName`: String value that specifies the name of the node you want to associate with the policy.
- `NodeIdentities.Datacenter`: String value that specifies the name of the datacenter in which the node identity applies. - `NodeIdentities.Datacenter`: String value that specifies the name of the datacenter in which the node identity applies.
@ -306,25 +257,6 @@ Refer to the [rules reference](/docs/security/acl/acl-rules) for information abo
The following role configuration contains a node identity for `node-1`. Note that the node identity is also scoped to the `dc2` datacenter. As a result, the policy will only be applied to nodes named `node-1` in `dc2`. The following role configuration contains a node identity for `node-1`. Note that the node identity is also scoped to the `dc2` datacenter. As a result, the policy will only be applied to nodes named `node-1` in `dc2`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```hcl
Description = "Showcases all input parameters"
Name = "example-role"
NodeIdentities = {
Datacenter = "dc2"
NodeName = "node-1",
}
Policies = {
ID = "783beef3-783f-f41f-7422-7087dc272765"
}
Policies = {
Name = "node-read"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json"> <CodeBlockConfig filename="example-role.json">
```json ```json
@ -349,7 +281,6 @@ Policies = {
``` ```
</CodeBlockConfig> </CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policy will be generated and linked to the token: During the authorization process, the following policy will be generated and linked to the token:

500
website/content/docs/security/acl/acl-rules.mdx
View File

@ -15,7 +15,7 @@ The following table provides an overview of the resources you can use to create
| Resource | Description | Labels | | Resource | Description | Labels |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `acl` | Controls access to ACL operations in the [ACL API](/api-docs/acl/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details. | No | | `acl` | Controls access to ACL operations in the [ACL API](/api-docs/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details. | No |
| `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details. | Yes | | `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details. | Yes |
| `agent`<br/>`agent_prefix` | Controls access to the utility operations in the [Agent API](/api-docs/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details. | Yes | | `agent`<br/>`agent_prefix` | Controls access to the utility operations in the [Agent API](/api-docs/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details. | Yes |
| `event`<br/>`event_prefix` | Controls access to event operations in the [Event API](/api-docs/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details. | Yes | | `event`<br/>`event_prefix` | Controls access to event operations in the [Event API](/api-docs/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details. | Yes |
@ -47,7 +47,8 @@ The `acl = "write"` rule is also required to create snapshots. This is because a
Rules for ACL resources do not use labels. Rules for ACL resources do not use labels.
In the following example, `write` access to the ACL API. The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token. In the following example, the `acl` rule is configured with `write` access to the ACL API.
The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token.
<CodeTabs heading="Example acl rule"> <CodeTabs heading="Example acl rule">
@ -56,7 +57,9 @@ acl = "write"
``` ```
```json ```json
"acl" : "write" {
"acl": "write"
}
``` ```
</CodeTabs> </CodeTabs>
@ -66,8 +69,15 @@ acl = "write"
The `partition` and `partition_prefix` resource controls access to one or more admin partitions. The `partition` and `partition_prefix` resource controls access to one or more admin partitions.
You can include any number of namespace rules inside the admin partition. You can include any number of namespace rules inside the admin partition.
In the following example, the agent has write access to the `ex-namespace` namespace, as well as namespaces prefixed with `ex-` in the `example` partition. In the following example, the policy grants `write` access to the `ex-namespace`
The `mesh` resource is also scoped to the admin partition rule, which grants `write` access to mesh-level resources in the partition: namespace, as well as namespaces prefixed with `exns-` in the `example` partition.
The `mesh` resource is also scoped to the admin partition rule, which grants
`write` access to mesh-level resources in the `example` partition.
In addition, the policy grants `read` access to the `ex-namespace` namespace, as
well as namespaces prefixed with `exns-` in all partitions containing the
`example-` prefix. Read access is granted for `mesh` resource scoped within the
associated partition.
<CodeTabs heading="Example admin partition rules"> <CodeTabs heading="Example admin partition rules">
@ -77,91 +87,64 @@ partition "example" {
node "my-node" { node "my-node" {
policy = "write" policy = "write"
} }
...
namespace "ex-namespace" { namespace "ex-namespace" {
... policy = "write"
} }
namespace_prefix "exns-" { namespace_prefix "exns-" {
... policy = "write"
} }
} }
partition_prefix "ex-" {
... (Same as above) partition_prefix "example-" {
mesh = "read"
node "my-node" {
policy = "read"
}
namespace "ex-namespace" {
policy = "read"
}
} }
``` ```
```json ```json
{ {
"partition": [ "partition": {
{ "example": {
"example": [ "mesh": "write",
{ "node": {
"mesh": "write", "my-node": {
"node": [ "policy": "write"
{
"my-node": [
{
"policy": "write"
}
],
"namespace": [
{
"ex-namespace": [
{
"policy": "read"
}
]
}
],
"namespace_prefix": [
{
"exns-": [
{
"policy": "read"
}
]
}
]
}
]
} }
] },
"namespace": {
"ex-namespace": {
"policy": "write"
}
},
"namespace_prefix": {
"exns-": {
"policy": "write"
}
}
} }
] },
}, "partition_prefix": {
{ "example-": {
"partition_prefix": [ "mesh": "read",
{ "node": {
"": [ "my-node": {
{
"policy": "read" "policy": "read"
} }
], },
"example": [ "namespace": {
{ "ex-namespace": {
"mesh": "read", "policy": "read"
"node": [
{
"my-node": [
{
"policy": "read"
}
]
}
],
"namespace": [
{
"ex-namespace": [
{
"policy": "read"
}
]
}
]
} }
] }
} }
] }
} }
``` ```
@ -176,39 +159,41 @@ and [`service` or `service_prefix`](#service-rules) policies instead.
<CodeTabs heading="Example agent rules"> <CodeTabs heading="Example agent rules">
```hcl ```hcl
agent_prefix "" {
policy = "read"
}
agent "foo" { agent "foo" {
policy = "write" policy = "write"
} }
agent_prefix "" {
policy = "read"
}
agent_prefix "bar" { agent_prefix "bar" {
policy = "deny" policy = "deny"
} }
``` ```
```json ```json
"agent_prefix" : [{ {
"" : [{ "agent": {
"policy" : "read" "foo": {
}], "policy": "write"
"bar" : [{ }
"policy" : "deny" },
}] "agent_prefix": {
}], "": {
"agent" : [{ "policy": "read"
"foo" : [{ },
"policy" : "write" "bar": {
}] "policy": "deny"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
Agent rules are keyed by the node name they apply to. In the example above the rules Agent rules are keyed by the node name they apply to. In the example above the rules
allow read-only access to any node name by using the empty prefix, read-write access to allow read-write access to the node with the _exact_ name `foo`, read-only access
the node with the _exact_ name `foo`, and denies all access to any node name that starts to any node name by using the empty prefix, and denies all access to any node
with `bar`. name that starts with `bar`.
Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to
a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
@ -232,16 +217,18 @@ event "deploy" {
``` ```
```json ```json
"event_prefix" : [{ {
"" : [{ "event_prefix": {
"policy" : "read" "": {
}] "policy": "read"
}], }
"event" : [{ },
"deploy" : [{ "event": {
"policy" : "write" "deploy": {
}] "policy": "write"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -273,19 +260,21 @@ key "bar" {
``` ```
```json ```json
"key_prefix" : [{ {
"" : [{ "key_prefix": {
"policy" : "read" "": {
}] "policy": "read"
}], }
"key" : [{ },
"foo" : [{ "key": {
"policy" : "write" "foo": {
}], "policy": "write"
"bar" : [{ },
"policy" : "deny" "bar": {
}] "policy": "deny"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -295,7 +284,12 @@ to any key name with the empty prefix rule, allow read-write access to the "foo"
### List Policy for Keys ### List Policy for Keys
Enable the `list` policy disposition (Consul 1.0+) by setting the `acl.enable_key_list_policy` parameter to `true`. The disposition provides recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse) documentation for additional information. In the following example, `key` resources that start with `bar` are listed. Enable the `list` policy disposition (Consul 1.0+) by setting the
`acl.enable_key_list_policy` parameter to `true`. The disposition provides
recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse)
documentation for additional information.
In the following example, `key` resources that start with `bar` may be listed.
<CodeTabs heading="Example 'key' rules"> <CodeTabs heading="Example 'key' rules">
@ -314,17 +308,19 @@ key_prefix "baz" {
``` ```
```json ```json
"key_prefix" : [{ {
"" : [{ "key_prefix": {
"policy" : "deny" "": {
}], "policy": "deny"
"bar" : [{ },
"policy" : "list" "bar": {
}], "policy": "list"
"baz" : [{ },
"policy" : "read" "baz": {
}] "policy": "read"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -364,7 +360,9 @@ keyring = "write"
``` ```
```json ```json
"keyring" : "write" {
"keyring": "write"
}
``` ```
</CodeTabs> </CodeTabs>
@ -380,7 +378,9 @@ mesh = "write"
``` ```
```json ```json
"mesh" : "write" {
"mesh": "write"
}
``` ```
</CodeTabs> </CodeTabs>
@ -399,6 +399,8 @@ The following examples describe how namespace rules can be defined in a policy:
```hcl ```hcl
namespace_prefix "" { namespace_prefix "" {
# grants permission to create and edit all namespaces
policy = "write"
# grant service:read for all services in all namespaces # grant service:read for all services in all namespaces
service_prefix "" { service_prefix "" {
@ -409,8 +411,6 @@ namespace_prefix "" {
node_prefix "" { node_prefix "" {
policy = "read" policy = "read"
} }
# grants permission to create and edit all namespace
policy = "write"
} }
namespace "foo" { namespace "foo" {
@ -444,79 +444,47 @@ namespace "foo" {
```json ```json
{ {
"namespace": [ "namespace_prefix": {
{ "": {
"foo": [ "policy": "write",
{ "service_prefix": {
"acl": "write", "": {
"key_prefix": [ "policy": "read"
{
"": [
{
"policy": "write"
}
]
}
],
"node_prefix": [
{
"": [
{
"policy": "read"
}
]
}
],
"policy": "write",
"service_prefix": [
{
"": [
{
"policy": "write"
}
]
}
],
"session_prefix": [
{
"": [
{
"policy": "write"
}
]
}
]
} }
] },
} "node_prefix": {
], "": {
"namespace_prefix": [ "policy": "read"
{
"": [
{
"node_prefix": [
{
"": [
{
"policy": "read"
}
]
}
],
"policy": "write",
"service_prefix": [
{
"": [
{
"policy": "read"
}
]
}
]
} }
] }
} }
] },
"namespace": {
"foo": {
"acl": "write",
"policy": "write",
"key_prefix": {
"": {
"policy": "write"
}
},
"session_prefix": {
"": {
"policy": "write"
}
},
"service_prefix": {
"": {
"policy": "write"
}
},
"node_prefix": {
"": {
"policy": "read"
}
}
}
}
} }
``` ```
@ -571,17 +539,21 @@ node "admin" {
``` ```
```json ```json
"node_prefix" : [{ {
"" : [{ "node_prefix": {
"policy" : "read" "": {
}], "policy": "read"
"app" : [{ },
"policy" : "write" },
}], "node": {
"admin" : [{ "app": {
"policy" : "deny" "policy": "write"
}] },
}] "admin": {
"policy": "deny"
}
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -604,7 +576,7 @@ These actions may required an ACL token to complete. Use the following methods t
* Provide an ACL token with `service` and `check` definitions at registration time. * Provide an ACL token with `service` and `check` definitions at registration time.
This allows for greater flexibility and enables the use of multiple tokens on the same agent. This allows for greater flexibility and enables the use of multiple tokens on the same agent.
Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples. Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/api) for operations that require them. Tokens may also be passed to the [HTTP API](/api-docs) for operations that require them.
## Operator Rules ## Operator Rules
@ -621,7 +593,9 @@ operator = "read"
``` ```
```json ```json
"operator" : "read" {
"operator": "read"
}
``` ```
</CodeTabs> </CodeTabs>
@ -645,16 +619,18 @@ query "foo" {
``` ```
```json ```json
"query_prefix" : [{ {
"" : [{ "query_prefix": {
"policy" : "read" "": {
}] "policy": "read"
}], }
"query" : [{ },
"foo" : [{ "query": {
"policy" : "write" "foo": {
}] "policy": "write"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -752,19 +728,21 @@ service "admin" {
``` ```
```json ```json
"service_prefix" : [{ {
"" : [{ "service_prefix": {
"policy" : "read" "": {
}] "policy": "read"
}], }
"service" : [{ },
"app" : [{ "service": {
"policy" : "write" "app": {
}], "policy": "write"
"admin" : [{ },
"policy" : "deny" "admin": {
}] "policy": "deny"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -790,10 +768,10 @@ to use for registration events:
tokens on the same agent. Examples of what this looks like are available for tokens on the same agent. Examples of what this looks like are available for
both [services](/docs/discovery/services) and both [services](/docs/discovery/services) and
[checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP [checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP
API](/api) for operations that require them. **Note:** all tokens API](/api-docs) for operations that require them. **Note:** all tokens
passed to an agent are persisted on local disk to allow recovery from passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag restarts. See [`-data-dir` flag
documentation](/docs/agent/config/config-files#acl_token) for notes on securing documentation](/docs/agent/config/cli-flags#_data_dir) for notes on securing
access. access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
@ -815,12 +793,14 @@ service "app" {
``` ```
```json ```json
"service" : [{ {
"app" : [{ "service": {
"policy" : "write" "app": {
}], "policy": "write",
"intentions" : "read" "intentions": "read"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>
@ -851,19 +831,21 @@ session "admin" {
``` ```
```json ```json
"session_prefix" : [{ {
"" : [{ "session_prefix": {
"policy" : "read" "": {
}] "policy": "read"
}], }
"session" : [{ },
"app" : [{ "session": {
"policy" : "write" "app": {
}], "policy": "write"
"admin" : [{ },
"policy" : "deny" "admin": {
}] "policy": "deny"
}] }
}
}
``` ```
</CodeTabs> </CodeTabs>

42
website/content/docs/security/acl/acl-tokens.mdx
View File

@ -38,12 +38,12 @@ Specify the value of the `SecretID` attribute with the `token` parameter when co
<CodeBlockConfig lineNumbers highlight="6"> <CodeBlockConfig lineNumbers highlight="6">
```hcl ```hcl
"service" = { service = {
"id" = "redis" id = "redis"
"name" = "redis" name = "redis"
... ...
"namespace" = "foo" namespace = "foo"
"token" = "233b604b-b92e-48c8-a253-5f11514e4b50" token = "233b604b-b92e-48c8-a253-5f11514e4b50"
} }
``` ```
@ -86,8 +86,8 @@ In the following example, the agent is configured to use a default token:
<CodeTabs> <CodeTabs>
```hcl ```hcl
"tokens" = { tokens = {
"default" = "233b604b-b92e-48c8-a253-5f11514e4b50" default = "233b604b-b92e-48c8-a253-5f11514e4b50"
} }
``` ```
@ -120,7 +120,7 @@ You can export tokens to environment variables on the local machine, which enabl
### API Requests ### API Requests
Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs/index#authentication) for details. Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs#authentication) for details.
The following example shows the header for a GET request to the `agent/members` endpoint. The following example shows the header for a GET request to the `agent/members` endpoint.
@ -137,12 +137,12 @@ Refer to the [API](/api-docs/acl/token) or [command line](/commands/acl/token) d
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- |
| `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | | `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated |
| `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated | | `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated |
| `Partition` | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | `default` | | `Partition` | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | String | `default` |
| `Namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` | | `Namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` |
| `Description` | Human-readable description for documenting the purpose of the token. | String | none | | `Description` | Human-readable description for documenting the purpose of the token. | String | none |
| `Local` | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` | | `Local` | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` |
| `ServiceIdentities` | Specifies a list of nodes to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | | `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none |
| `NodeIdentities` | Specifies a list of nodes to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | | `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none |
| `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` | | `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` |
| `Policies` | List of policies linked to the token, including the policy ID and name. | String | none | | `Policies` | List of policies linked to the token, including the policy ID and name. | String | none |
@ -162,7 +162,7 @@ All reserved tokens except the `initial_management` token can be created or upda
### Snapshot Tokens ### Snapshot Tokens
Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and require, and interacting with them requires a token with `write` privileges. Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges.
### ACL Agent Token ### ACL Agent Token
@ -174,6 +174,8 @@ The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special toke
Here's an example policy sufficient to accomplish the above for a node called `mynode`: Here's an example policy sufficient to accomplish the above for a node called `mynode`:
<CodeBlockConfig heading="Example agent policy permitting internal operations">
```hcl ```hcl
node "mynode" { node "mynode" {
policy = "write" policy = "write"
@ -186,19 +188,10 @@ key_prefix "_rexec" {
} }
``` ```
</CodeBlockConfig>
The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
<!-- Consider removing this content now that we have versioned docs
In Consul 1.4 - 1.10, the following special tokens were known by different names:
| New Name (1.11+) | Old Name (1.4 - 1.10) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) |
-->
## Built-in Tokens ## Built-in Tokens
Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster. Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster.
@ -215,7 +208,8 @@ The description and policies may be updated, but the anonymous token cannot be d
### Initial Management Token ### Initial Management Token
Including an initial management token in the Consul configuration creates the token and links it with the built-in global management policy. Including an initial management token in the Consul configuration creates the
token and links it with the built-in [global management](/docs/security/acl/acl-policies#global-management) policy.
The bearer will have have unrestricted privileges to resources and APIs. The bearer will have have unrestricted privileges to resources and APIs.
The `SecretID` attribute will be set to the value of the configuration entry. The `SecretID` attribute will be set to the value of the configuration entry.

6
website/content/docs/security/acl/index.mdx
View File

@ -69,7 +69,7 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat
## Service Identities ## Service Identities
Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh.
Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
@ -80,9 +80,9 @@ Refer to the following topics for additional information about service identitie
## Node Identities ## Node Identities
Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent. Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each service. Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each node.
Refer to the following topics for additional information about node identities: Refer to the following topics for additional information about node identities:

5
website/redirects.js
View File

@ -76,6 +76,11 @@ module.exports = [
destination: '/docs/security/acl/acl-legacy', destination: '/docs/security/acl/acl-legacy',
permanent: true, permanent: true,
}, },
{
source: '/api-docs/acl/acl',
destination: '/api-docs/acl',
permanent: true,
},
{ {
source: '/api-docs/acl-legacy', source: '/api-docs/acl-legacy',
destination: '/api-docs/acl/legacy', destination: '/api-docs/acl/legacy',