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:
commit
d33d06e033
|
@ -151,7 +151,7 @@ A script check:
|
|||
```hcl
|
||||
check = {
|
||||
id = "mem-util"
|
||||
name = "Memory utilization"
|
||||
name = "Memory utilization"
|
||||
args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"]
|
||||
interval = "10s"
|
||||
timeout = "1s"
|
||||
|
@ -186,12 +186,12 @@ check = {
|
|||
tls_skip_verify = false
|
||||
method = "POST"
|
||||
header = {
|
||||
Content-Type = ["application/json"]
|
||||
Content-Type = ["application/json"]
|
||||
}
|
||||
body = "{\"method\":\"health\"}"
|
||||
disable_redirects = true
|
||||
interval = "10s"
|
||||
timeout = "1s"
|
||||
interval = "10s"
|
||||
timeout = "1s"
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -248,11 +248,11 @@ A TTL check:
|
|||
<CodeTabs heading="TTL Check">
|
||||
|
||||
```hcl
|
||||
check = {
|
||||
check = {
|
||||
id = "web-app"
|
||||
name = "Web App Status"
|
||||
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
|
||||
check = {
|
||||
id = "mem-util"
|
||||
id = "mem-util"
|
||||
name = "Service health status"
|
||||
grpc = "127.0.0.1:12345"
|
||||
grpc = "127.0.0.1:12345"
|
||||
grpc_use_tls = true
|
||||
interval = "10s"
|
||||
interval = "10s"
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -482,11 +482,11 @@ health check definition, like so:
|
|||
<CodeTabs heading="Status Field Example">
|
||||
|
||||
```hcl
|
||||
check = {
|
||||
"id": "mem",
|
||||
"args": ["/bin/check_mem", "-limit", "256MB"]
|
||||
"interval": "10s"
|
||||
"status": "passing"
|
||||
check = {
|
||||
id = "mem"
|
||||
args = ["/bin/check_mem", "-limit", "256MB"]
|
||||
interval = "10s"
|
||||
status = "passing"
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -516,10 +516,10 @@ provided by adding a `service_id` field to a check configuration:
|
|||
<CodeTabs heading="Status Field Example">
|
||||
|
||||
```hcl
|
||||
check = {
|
||||
check = {
|
||||
id = "web-app"
|
||||
name = "Web App Status"
|
||||
service_id = "web-app"
|
||||
name = "Web App Status"
|
||||
service_id = "web-app"
|
||||
ttl = "30s"
|
||||
}
|
||||
```
|
||||
|
@ -635,7 +635,7 @@ checks = [
|
|||
name = "HTTP TCP on port 80"
|
||||
tcp = "localhost:80"
|
||||
interval = "10s"
|
||||
timeout = "1s"
|
||||
timeout = "1s"
|
||||
success_before_passing = 3
|
||||
failures_before_warning = 1
|
||||
failures_before_critical = 3
|
||||
|
|
|
@ -32,13 +32,15 @@ A rule is composed of a resource declaration and an access level defined with th
|
|||
```hcl
|
||||
<resource> {
|
||||
policy = "<policy disposition>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
"<resource>": [{
|
||||
"policy": "<policy disposition>"
|
||||
}]
|
||||
{
|
||||
"<resource>": {
|
||||
"policy": "<policy disposition>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -60,11 +62,13 @@ The following syntax describes how to include a resource label in the rule:
|
|||
```
|
||||
|
||||
```json
|
||||
"<resource>": [{
|
||||
"<label>": [{
|
||||
"policy": "<policy disposition>"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"<resource>": {
|
||||
"<label>": {
|
||||
"policy": "<policy disposition>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -85,7 +89,9 @@ Use the following syntax to create rules for these resources:
|
|||
```
|
||||
|
||||
```json
|
||||
"<resource>": "<policy disposition>"
|
||||
{
|
||||
"<resource>": "<policy disposition>"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -115,11 +121,13 @@ service "web-prod" {
|
|||
```
|
||||
|
||||
```json
|
||||
"service": [{
|
||||
"web-prod" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"service": {
|
||||
"web-prod": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -135,11 +143,13 @@ service_prefix "web" {
|
|||
```
|
||||
|
||||
```json
|
||||
"service_prefix": [{
|
||||
"web" : [{
|
||||
"policy" : "write"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"service_prefix": {
|
||||
"web": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -155,11 +165,13 @@ service_prefix "" {
|
|||
```
|
||||
|
||||
```json
|
||||
"service_prefix" : [{
|
||||
"" : [{
|
||||
"policy" :"read"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy":"read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -209,38 +221,22 @@ operator = "read"
|
|||
|
||||
```json
|
||||
{
|
||||
"key": [
|
||||
{
|
||||
"foo/bar/secret": [
|
||||
{
|
||||
"policy": "deny"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"key_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
"key_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
},
|
||||
{
|
||||
"foo/": [
|
||||
{
|
||||
"policy": "write"
|
||||
}
|
||||
]
|
||||
"foo/": {
|
||||
"policy": "write"
|
||||
},
|
||||
{
|
||||
"foo/private/": [
|
||||
{
|
||||
"policy": "deny"
|
||||
}
|
||||
]
|
||||
"foo/private/": {
|
||||
"policy": "deny"
|
||||
}
|
||||
],
|
||||
},
|
||||
"key": {
|
||||
"foo/bar/secret": {
|
||||
"policy": "deny"
|
||||
}
|
||||
},
|
||||
"operator": "read"
|
||||
}
|
||||
```
|
||||
|
@ -283,7 +279,7 @@ You can can define several attributes that attach additional metadata and specif
|
|||
|
||||
### 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:
|
||||
|
||||
|
@ -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.
|
||||
|
||||
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>
|
||||
|
||||
```hcl
|
||||
# Provide KV visibility to all agents.
|
||||
agent_prefix "" {
|
||||
"policy" = "read"
|
||||
policy = "read"
|
||||
}
|
||||
# Enable resources prefixed with 'vault/' to write to the KV
|
||||
key_prefix "vault/" {
|
||||
"policy" = "write"
|
||||
policy = "write"
|
||||
}
|
||||
# Enable the vault service to write to the KV
|
||||
service "vault" {
|
||||
"policy" = "write"
|
||||
policy = "write"
|
||||
}
|
||||
# Enable the agent to initialize a new session.
|
||||
session_prefix "" {
|
||||
"policy" = "write"
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"key_prefix": {
|
||||
"vault/": {
|
||||
"policy": "write"
|
||||
|
@ -492,11 +494,6 @@ session_prefix "" {
|
|||
"policy": "write"
|
||||
}
|
||||
},
|
||||
"agent_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"session_prefix": {
|
||||
"": {
|
||||
"policy": "write"
|
||||
|
|
|
@ -79,8 +79,6 @@ Service identities are used during the authorization process to automatically ge
|
|||
|
||||
Use the following syntax to define a service identity:
|
||||
|
||||
<CodeTabs>
|
||||
|
||||
```json
|
||||
{
|
||||
"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.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.
|
||||
|
@ -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`.
|
||||
|
||||
<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">
|
||||
|
||||
```json
|
||||
|
@ -191,7 +157,6 @@ ServiceIdentities = {
|
|||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
</CodeTabs>
|
||||
|
||||
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
|
||||
|
||||
<!-- -> 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.
|
||||
|
||||
|
@ -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:
|
||||
|
||||
<CodeTabs>
|
||||
|
||||
```json
|
||||
{
|
||||
"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.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.
|
||||
|
@ -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`.
|
||||
|
||||
<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">
|
||||
|
||||
```json
|
||||
|
@ -349,7 +281,6 @@ Policies = {
|
|||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
</CodeTabs>
|
||||
|
||||
During the authorization process, the following policy will be generated and linked to the token:
|
||||
|
||||
|
|
|
@ -15,7 +15,7 @@ The following table provides an overview of the resources you can use to create
|
|||
|
||||
| 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 |
|
||||
| `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 |
|
||||
|
@ -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.
|
||||
|
||||
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">
|
||||
|
||||
|
@ -56,7 +57,9 @@ acl = "write"
|
|||
```
|
||||
|
||||
```json
|
||||
"acl" : "write"
|
||||
{
|
||||
"acl": "write"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -66,8 +69,15 @@ acl = "write"
|
|||
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.
|
||||
|
||||
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.
|
||||
The `mesh` resource is also scoped to the admin partition rule, which grants `write` access to mesh-level resources in the partition:
|
||||
In the following example, the policy grants `write` access to the `ex-namespace`
|
||||
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">
|
||||
|
||||
|
@ -77,91 +87,64 @@ partition "example" {
|
|||
node "my-node" {
|
||||
policy = "write"
|
||||
}
|
||||
...
|
||||
namespace "ex-namespace" {
|
||||
...
|
||||
policy = "write"
|
||||
}
|
||||
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
|
||||
{
|
||||
"partition": [
|
||||
{
|
||||
"example": [
|
||||
{
|
||||
"mesh": "write",
|
||||
"node": [
|
||||
{
|
||||
"my-node": [
|
||||
{
|
||||
"policy": "write"
|
||||
}
|
||||
],
|
||||
"namespace": [
|
||||
{
|
||||
"ex-namespace": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"namespace_prefix": [
|
||||
{
|
||||
"exns-": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
"partition": {
|
||||
"example": {
|
||||
"mesh": "write",
|
||||
"node": {
|
||||
"my-node": {
|
||||
"policy": "write"
|
||||
}
|
||||
]
|
||||
},
|
||||
"namespace": {
|
||||
"ex-namespace": {
|
||||
"policy": "write"
|
||||
}
|
||||
},
|
||||
"namespace_prefix": {
|
||||
"exns-": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"partition_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
},
|
||||
"partition_prefix": {
|
||||
"example-": {
|
||||
"mesh": "read",
|
||||
"node": {
|
||||
"my-node": {
|
||||
"policy": "read"
|
||||
}
|
||||
],
|
||||
"example": [
|
||||
{
|
||||
"mesh": "read",
|
||||
"node": [
|
||||
{
|
||||
"my-node": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"namespace": [
|
||||
{
|
||||
"ex-namespace": [
|
||||
{
|
||||
"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">
|
||||
|
||||
```hcl
|
||||
agent_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
agent "foo" {
|
||||
policy = "write"
|
||||
}
|
||||
agent_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
agent_prefix "bar" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
"agent_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}],
|
||||
"bar" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}],
|
||||
"agent" : [{
|
||||
"foo" : [{
|
||||
"policy" : "write"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"agent": {
|
||||
"foo": {
|
||||
"policy": "write"
|
||||
}
|
||||
},
|
||||
"agent_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
},
|
||||
"bar": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
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
|
||||
the node with the _exact_ name `foo`, and denies all access to any node name that starts
|
||||
with `bar`.
|
||||
allow read-write access to the node with the _exact_ name `foo`, read-only access
|
||||
to any node name by using the empty prefix, and denies all access to any node
|
||||
name that starts with `bar`.
|
||||
|
||||
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
|
||||
|
@ -232,16 +217,18 @@ event "deploy" {
|
|||
```
|
||||
|
||||
```json
|
||||
"event_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}],
|
||||
"event" : [{
|
||||
"deploy" : [{
|
||||
"policy" : "write"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"event_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"event": {
|
||||
"deploy": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -273,19 +260,21 @@ key "bar" {
|
|||
```
|
||||
|
||||
```json
|
||||
"key_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}],
|
||||
"key" : [{
|
||||
"foo" : [{
|
||||
"policy" : "write"
|
||||
}],
|
||||
"bar" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"key_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"key": {
|
||||
"foo": {
|
||||
"policy": "write"
|
||||
},
|
||||
"bar": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</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
|
||||
|
||||
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">
|
||||
|
||||
|
@ -314,17 +308,19 @@ key_prefix "baz" {
|
|||
```
|
||||
|
||||
```json
|
||||
"key_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "deny"
|
||||
}],
|
||||
"bar" : [{
|
||||
"policy" : "list"
|
||||
}],
|
||||
"baz" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"key_prefix": {
|
||||
"": {
|
||||
"policy": "deny"
|
||||
},
|
||||
"bar": {
|
||||
"policy": "list"
|
||||
},
|
||||
"baz": {
|
||||
"policy": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -364,7 +360,9 @@ keyring = "write"
|
|||
```
|
||||
|
||||
```json
|
||||
"keyring" : "write"
|
||||
{
|
||||
"keyring": "write"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -380,7 +378,9 @@ mesh = "write"
|
|||
```
|
||||
|
||||
```json
|
||||
"mesh" : "write"
|
||||
{
|
||||
"mesh": "write"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -399,6 +399,8 @@ The following examples describe how namespace rules can be defined in a policy:
|
|||
|
||||
```hcl
|
||||
namespace_prefix "" {
|
||||
# grants permission to create and edit all namespaces
|
||||
policy = "write"
|
||||
|
||||
# grant service:read for all services in all namespaces
|
||||
service_prefix "" {
|
||||
|
@ -409,8 +411,6 @@ namespace_prefix "" {
|
|||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
# grants permission to create and edit all namespace
|
||||
policy = "write"
|
||||
}
|
||||
|
||||
namespace "foo" {
|
||||
|
@ -444,79 +444,47 @@ namespace "foo" {
|
|||
|
||||
```json
|
||||
{
|
||||
"namespace": [
|
||||
{
|
||||
"foo": [
|
||||
{
|
||||
"acl": "write",
|
||||
"key_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "write"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"node_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"policy": "write",
|
||||
"service_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "write"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"session_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "write"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
"namespace_prefix": {
|
||||
"": {
|
||||
"policy": "write",
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"namespace_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"node_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"policy": "write",
|
||||
"service_prefix": [
|
||||
{
|
||||
"": [
|
||||
{
|
||||
"policy": "read"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"node_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
|
||||
"node_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}],
|
||||
"app" : [{
|
||||
"policy" : "write"
|
||||
}],
|
||||
"admin" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"node_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
},
|
||||
},
|
||||
"node": {
|
||||
"app": {
|
||||
"policy": "write"
|
||||
},
|
||||
"admin": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</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.
|
||||
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.
|
||||
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
|
||||
|
||||
|
@ -621,7 +593,9 @@ operator = "read"
|
|||
```
|
||||
|
||||
```json
|
||||
"operator" : "read"
|
||||
{
|
||||
"operator": "read"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -645,16 +619,18 @@ query "foo" {
|
|||
```
|
||||
|
||||
```json
|
||||
"query_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}],
|
||||
"query" : [{
|
||||
"foo" : [{
|
||||
"policy" : "write"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"query_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"query": {
|
||||
"foo": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -752,19 +728,21 @@ service "admin" {
|
|||
```
|
||||
|
||||
```json
|
||||
"service_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}],
|
||||
"service" : [{
|
||||
"app" : [{
|
||||
"policy" : "write"
|
||||
}],
|
||||
"admin" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"service": {
|
||||
"app": {
|
||||
"policy": "write"
|
||||
},
|
||||
"admin": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -790,10 +768,10 @@ to use for registration events:
|
|||
tokens on the same agent. Examples of what this looks like are available for
|
||||
both [services](/docs/discovery/services) and
|
||||
[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
|
||||
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.
|
||||
|
||||
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
|
||||
|
@ -815,12 +793,14 @@ service "app" {
|
|||
```
|
||||
|
||||
```json
|
||||
"service" : [{
|
||||
"app" : [{
|
||||
"policy" : "write"
|
||||
}],
|
||||
"intentions" : "read"
|
||||
}]
|
||||
{
|
||||
"service": {
|
||||
"app": {
|
||||
"policy": "write",
|
||||
"intentions": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
@ -851,19 +831,21 @@ session "admin" {
|
|||
```
|
||||
|
||||
```json
|
||||
"session_prefix" : [{
|
||||
"" : [{
|
||||
"policy" : "read"
|
||||
}]
|
||||
}],
|
||||
"session" : [{
|
||||
"app" : [{
|
||||
"policy" : "write"
|
||||
}],
|
||||
"admin" : [{
|
||||
"policy" : "deny"
|
||||
}]
|
||||
}]
|
||||
{
|
||||
"session_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"session": {
|
||||
"app": {
|
||||
"policy": "write"
|
||||
},
|
||||
"admin": {
|
||||
"policy": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
|
|
@ -38,12 +38,12 @@ Specify the value of the `SecretID` attribute with the `token` parameter when co
|
|||
<CodeBlockConfig lineNumbers highlight="6">
|
||||
|
||||
```hcl
|
||||
"service" = {
|
||||
"id" = "redis"
|
||||
"name" = "redis"
|
||||
service = {
|
||||
id = "redis"
|
||||
name = "redis"
|
||||
...
|
||||
"namespace" = "foo"
|
||||
"token" = "233b604b-b92e-48c8-a253-5f11514e4b50"
|
||||
namespace = "foo"
|
||||
token = "233b604b-b92e-48c8-a253-5f11514e4b50"
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -86,8 +86,8 @@ In the following example, the agent is configured to use a default token:
|
|||
<CodeTabs>
|
||||
|
||||
```hcl
|
||||
"tokens" = {
|
||||
"default" = "233b604b-b92e-48c8-a253-5f11514e4b50"
|
||||
tokens = {
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
@ -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 |
|
||||
| `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` |
|
||||
| `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` |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `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 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` |
|
||||
| `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
|
||||
|
||||
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
|
||||
|
||||
|
@ -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`:
|
||||
|
||||
<CodeBlockConfig heading="Example agent policy permitting internal operations">
|
||||
|
||||
```hcl
|
||||
node "mynode" {
|
||||
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.
|
||||
|
||||
<!-- 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
|
||||
|
||||
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
|
||||
|
||||
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 `SecretID` attribute will be set to the value of the configuration entry.
|
||||
|
||||
|
|
|
@ -69,7 +69,7 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat
|
|||
|
||||
## 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.
|
||||
|
||||
|
@ -80,9 +80,9 @@ Refer to the following topics for additional information about service identitie
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
|
@ -76,6 +76,11 @@ module.exports = [
|
|||
destination: '/docs/security/acl/acl-legacy',
|
||||
permanent: true,
|
||||
},
|
||||
{
|
||||
source: '/api-docs/acl/acl',
|
||||
destination: '/api-docs/acl',
|
||||
permanent: true,
|
||||
},
|
||||
{
|
||||
source: '/api-docs/acl-legacy',
|
||||
destination: '/api-docs/acl/legacy',
|
||||
|
|
Loading…
Reference in New Issue