mirror of https://github.com/status-im/consul.git
Clarify purpose of example ACL rules and policies
This commit is contained in:
parent
ab9c7d2dd4
commit
34b2f5daea
|
@ -453,7 +453,8 @@ 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>
|
||||
|
||||
|
|
|
@ -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">
|
||||
|
||||
|
@ -68,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">
|
||||
|
||||
|
@ -183,9 +191,9 @@ agent_prefix "bar" {
|
|||
</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
|
||||
|
@ -276,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">
|
||||
|
||||
|
@ -563,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
|
||||
|
||||
|
@ -755,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
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
|
Loading…
Reference in New Issue