Merge pull request #2874 from hashicorp/acl-guide
Updates the ACL guide.
This commit is contained in:
James Phillips
GitHub
commit
0de8f13a97
|
|
@ -38,7 +38,7 @@ The table below shows this endpoint's support for
|
|||
are: `client` and `management`.
|
||||
|
||||
- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the
|
||||
`Rules` property is [documented here](/docs/internals/acl.html).
|
||||
`Rules` property is documented in the [ACL Guide](/docs/guides/acl.html).
|
||||
|
||||
### Sample Payload
|
||||
|
||||
|
|
@ -271,8 +271,8 @@ This endpoint returns the status of the ACL replication process in the
|
|||
datacenter. This is intended to be used by operators, or by automation checking
|
||||
the health of ACL replication.
|
||||
|
||||
Please see the [ACL replication](/docs/internals/acl.html#replication) section
|
||||
of the internals guide for more details.
|
||||
Please see the [ACL Guide](/docs/guides/acl.html#replication) replication
|
||||
section for more details.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
|
|
|
|||
|
|
@ -28,9 +28,9 @@ warning when this policy changes. We expect to reach API stability by Consul
|
|||
Several endpoints in Consul use or require ACL tokens to operate. An agent
|
||||
can be configured to use a default token in requests using the `acl_token`
|
||||
configuration option. However, the token can also be specified per-request
|
||||
by using the `X-Consul-Token` request header or the `token` querystring
|
||||
by using the `X-Consul-Token` request header or the `token` query string
|
||||
parameter. The request header takes precedence over the default token, and
|
||||
the querystring parameter takes precedence over everything.
|
||||
the query string parameter takes precedence over everything.
|
||||
|
||||
## Authentication
|
||||
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ operations manually, please see the documentation for the
|
|||
[`consul operator`](/docs/commands/operator.html) command.
|
||||
|
||||
If ACLs are enabled then a token with operator privileges may be required in
|
||||
order to use this interface. See the [ACL](/docs/internals/acl.html#operator)
|
||||
internals guide for more information.
|
||||
order to use this interface. See the [ACL Guide](/docs/guides/acl.html#operator)
|
||||
for more information.
|
||||
|
||||
See the [Outage Recovery](/docs/guides/outage.html) guide for some examples of
|
||||
how these capabilities are used.
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ service. This is particularly useful in combination with Consul's
|
|||
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than
|
||||
would be possible given the limited entry points exposed by DNS.
|
||||
|
||||
See the [Prepared Query ACLs](/docs/internals/acl.html#prepared_query_acls)
|
||||
internals guide for more details about how prepared query policies work.
|
||||
See the [ACL Guide](/docs/guides/acl.html#prepared_query_acls)
|
||||
prepared query section for more details about how prepared query policies work.
|
||||
|
||||
### Prepared Query Templates
|
||||
|
||||
|
|
|
|||
|
|
@ -433,7 +433,7 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
All servers and datacenters must agree on the ACL datacenter. Setting it on the servers is all
|
||||
you need for cluster-level enforcement, but for the APIs to forward properly from the clients,
|
||||
it must be set on them too. In Consul 0.8 and later, this also enables agent-level enforcement
|
||||
of ACLs. Please see the [ACL internals guide](/docs/internals/acl.html) for more details.
|
||||
of ACLs. Please see the [ACL Guide](/docs/guides/acl.html) for more details.
|
||||
|
||||
* <a name="acl_default_policy"></a><a href="#acl_default_policy">`acl_default_policy`</a> - Either
|
||||
"allow" or "deny"; defaults to "allow". The default policy controls the behavior of a token when
|
||||
|
|
@ -465,10 +465,10 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
|
||||
* <a name="acl_enforce_version_8"></a><a href="#acl_enforce_version_8">`acl_enforce_version_8`</a> -
|
||||
Used for clients and servers to determine if enforcement should occur for new ACL policies being
|
||||
previewed before Consul 0.8. Added in Consul 0.7.2, this will default to false in versions of
|
||||
Consul prior to 0.8, and will default to true in Consul 0.8 and later. This helps ease the
|
||||
previewed before Consul 0.8. Added in Consul 0.7.2, this defaults to false in versions of
|
||||
Consul prior to 0.8, and defaults to true in Consul 0.8 and later. This helps ease the
|
||||
transition to the new ACL features by allowing policies to be in place before enforcement begins.
|
||||
Please see the [ACL internals guide](/docs/internals/acl.html) for more details.
|
||||
Please see the [ACL Guide](/docs/guides/acl.html#version_8_acls) for more details.
|
||||
|
||||
* <a name="acl_master_token"></a><a href="#acl_master_token">`acl_master_token`</a> - Only used
|
||||
for servers in the [`acl_datacenter`](#acl_datacenter). This token will be created with management-level
|
||||
|
|
@ -484,14 +484,13 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
|
||||
* <a name="acl_replication_token"></a><a href="#acl_replication_token">`acl_replication_token`</a> -
|
||||
Only used for servers outside the [`acl_datacenter`](#acl_datacenter) running Consul 0.7 or later.
|
||||
When provided, this will enable [ACL replication](/docs/internals/acl.html#replication) using this
|
||||
When provided, this will enable [ACL replication](/docs/guides/acl.html#replication) using this
|
||||
token to retrieve and replicate the ACLs to the non-authoritative local datacenter.
|
||||
<br><br>
|
||||
If there's a partition or other outage affecting the authoritative datacenter, and the
|
||||
[`acl_down_policy`](/docs/agent/options.html#acl_down_policy) is set to "extend-cache", tokens not
|
||||
in the cache can be resolved during the outage using the replicated set of ACLs. Please see the
|
||||
[ACL replication](/docs/internals/acl.html#replication) section of the internals guide for more
|
||||
details.
|
||||
[ACL Guide](/docs/guides/acl.html#replication) replication section for more details.
|
||||
|
||||
* <a name="acl_token"></a><a href="#acl_token">`acl_token`</a> - When provided, the agent will use this
|
||||
token when making requests to the Consul servers. Clients can override this token on a per-request
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ as interacting with the Raft subsystem. This was added in Consul 0.7.
|
|||
If ACLs are enabled then a token with operator privileges may be required in
|
||||
order to use this command. Requests are forwarded internally to the leader
|
||||
if required, so this can be run from any Consul node in a cluster. See the
|
||||
[ACL](/docs/internals/acl.html#operator) internals guide for more information.
|
||||
[ACL Guide](/docs/guides/acl.html#operator) for more information.
|
||||
|
||||
See the [Outage Recovery](/docs/guides/outage.html) guide for some examples of how
|
||||
this command is used. For an API to perform these operations programatically,
|
||||
|
|
|
|||
703
website/source/docs/guides/acl.html.markdown
Normal file
703
website/source/docs/guides/acl.html.markdown
Normal file
|
|
@ -0,0 +1,703 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "ACL System"
|
||||
sidebar_current: "docs-guides-acl"
|
||||
description: |-
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.
|
||||
---
|
||||
|
||||
# ACL System
|
||||
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control
|
||||
access to data and APIs. The ACL is
|
||||
[Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying
|
||||
on tokens to which fine grained rules can be applied. It is very similar to
|
||||
[AWS IAM](http://aws.amazon.com/iam/) in many ways.
|
||||
|
||||
## ACL System Overview
|
||||
|
||||
The ACL system is designed to be easy to use, fast to enforce, and flexible to new policies,
|
||||
all while providing administrative insight.
|
||||
|
||||
#### ACL Tokens
|
||||
|
||||
The ACL system is based on tokens, which are managed by Consul operators via Consul's
|
||||
[ACL API](/api/acl.html), or systems like
|
||||
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul/index.html).
|
||||
|
||||
Every token has an ID, name, type, and rule set. The ID is a randomly generated
|
||||
UUID, making it unfeasible to guess. The name is opaque to Consul and human readable.
|
||||
The type is either "client" (meaning the token cannot modify ACL rules) or "management"
|
||||
(meaning the token is allowed to perform all actions).
|
||||
|
||||
The token ID is passed along with each RPC request to the servers. Consul's
|
||||
[HTTP endpoints](http://localhost:4567/api/index.html) can accept tokens via the `token`
|
||||
query string parameter, or the `X-Consul-Token` request header. Consul's
|
||||
[CLI commands](http://localhost:4567/docs/commands/index.html) can accept tokens via the
|
||||
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable.
|
||||
|
||||
If no token is provided, the rules associated with a special, configurable anonymous
|
||||
token are automatically applied. The anonymous token is managed using the
|
||||
[ACL API](/api/acl.html) like any other ACL token, but using `anonymous` for the ID.
|
||||
|
||||
#### ACL Rules and Scope
|
||||
|
||||
Tokens are bound to a set of rules that control which Consul resources the token
|
||||
has access to. Policies can be defined in either a whitelist or blacklist mode
|
||||
depending on the configuration of
|
||||
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy). If the default
|
||||
policy is to "deny all" actions, then token rules can be set to whitelist specific
|
||||
actions. In the inverse, the "allow all" default behavior is a blacklist where rules
|
||||
are used to prohibit actions. By default, Consul will allow all actions.
|
||||
|
||||
The following table summarizes the ACL policies that are availabile for constructing
|
||||
rules:
|
||||
|
||||
| Policy | Scope |
|
||||
| ------------------------ | ----- |
|
||||
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
|
||||
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
|
||||
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
|
||||
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
|
||||
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
|
||||
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
|
||||
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html)
|
||||
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), and [Agent API](/api/agent.html) |
|
||||
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
|
||||
|
||||
Since Consul snapshots actually contain ACL tokens, the
|
||||
[Snapshot API](/api/snapshot.html) requires a management token for snapshot operations
|
||||
and does not use a special policy.
|
||||
|
||||
The following resources are not covered by ACL policies:
|
||||
|
||||
1. The [Status API](api/status.html) is used by servers when bootstrapping and exposes
|
||||
basic IP and port information about the servers, and does not allow modification
|
||||
of any state.
|
||||
|
||||
2. The datacenter listing operation of the
|
||||
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known
|
||||
Consul datacenters, and does not allow modification of any state.
|
||||
|
||||
Constructing rules from these policies is covered in detail in the
|
||||
[Rule Specification](#rule-specification) section below.
|
||||
|
||||
#### ACL Datacenter
|
||||
|
||||
All nodes (clients and servers) must be configured with an
|
||||
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) which enables ACL
|
||||
enforcement but also specifies the authoritative datacenter. Consul relies on
|
||||
[RPC forwarding](/docs/internals/architecture.html) to support multi-datacenter
|
||||
configurations. However, because requests can be made across datacenter boundaries,
|
||||
ACL tokens must be valid globally. To avoid consistency issues, a single datacenter
|
||||
is considered authoritative and stores the canonical set of tokens.
|
||||
|
||||
When a request is made to an agent in a non-authoritative datacenter, it must be
|
||||
resolved into the appropriate policy. This is done by reading the token from the
|
||||
authoritative server and caching the result for a configurable
|
||||
[`acl_ttl`](/docs/agent/options.html#acl_ttl). The implication of caching is that
|
||||
the cache TTL is an upper bound on the staleness of policy that is enforced. It is
|
||||
possible to set a zero TTL, but this has adverse performance impacts, as every
|
||||
request requires refreshing the policy via an RPC call.
|
||||
|
||||
#### Enabling ACLs
|
||||
|
||||
Enabling ACLs is done by setting up the following configuration options. These are
|
||||
marked as to whether they are set on servers, clients, both.
|
||||
|
||||
| Configuration Option | Servers | Clients | Purpose |
|
||||
| -------------------- | ------- | ------- | ------- |
|
||||
| [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
|
||||
| [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
|
||||
| [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to when the ACL datacenter is offline |
|
||||
| [`acl_ttl`](/docs/agent/options.html#acl_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs |
|
||||
|
||||
There are some additional configuration items related to [ACL replication](#replication) and
|
||||
[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections
|
||||
below.
|
||||
|
||||
A number of special tokens can also be configured which allow for bootstrapping the ACL
|
||||
system, or accessing Consul in special situations:
|
||||
|
||||
| Special Token | Servers | Clients | Purpose |
|
||||
| ------------- | ------- | ------- | ------- |
|
||||
| [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations |
|
||||
| [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations with the [Catalog API](/api/catalog.html); this needs to have at least `node` policy access so the agent can self update its registration information |
|
||||
| [`acl_master_token`](/docs/agent/options.html#acl_master_token) | `REQUIRED` | `N/A` | Special token used to bootstrap th ACL system, see details below. |
|
||||
| [`acl_token`](/docs/agent/options.html#acl_token) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
|
||||
|
||||
Bootstrapping the ACL system is done by providing an initial [`acl_master_token`
|
||||
configuration](/docs/agent/options.html#acl_master_token) which will be created
|
||||
as a "management" type token if it does not exist. The [`acl_master_token`
|
||||
](/docs/agent/options.html#acl_master_token) is only installed when a server acquires
|
||||
cluster leadership. If you would like to install or change the
|
||||
[`acl_master_token`](/docs/agent/options.html#acl_master_token), set the new value for
|
||||
[`acl_master_token`](/docs/agent/options.html#acl_master_token) in the configuration
|
||||
for all servers. Once this is done, restart the current leader to force a leader election.
|
||||
|
||||
Once the ACL system is bootstrapped, ACL tokens can be managed through the
|
||||
[ACL API](/api/acl.html).
|
||||
|
||||
## Rule Specification
|
||||
|
||||
A core part of the ACL system is the rule language which is used to describe the policy
|
||||
that must be enforced. Most of the ACL rules are prefix-based, allowing operators to
|
||||
define different namespaces within Consul's resource areas like the catalog and key/value
|
||||
store, in order to delegate responsibility for these namespaces. Policies can have several
|
||||
dispositions:
|
||||
|
||||
* `read`: allow the resource to be read but not modified
|
||||
* `write`: allow the resource to be read and modified
|
||||
* `deny`: do not allow the resource to be read or modified
|
||||
|
||||
With prefix-based rules, the most specific prefix match determines the action. This
|
||||
allows for flexible rules like an empty prefix to allow read-only access to all
|
||||
resources, along with some specific prefixes that allow write access or that are
|
||||
denied all access.
|
||||
|
||||
We make use of the
|
||||
[HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/) to specify
|
||||
rules. This language is human readable and interoperable with JSON making it easy to
|
||||
machine-generate. Rules can make use of one or more policies.
|
||||
|
||||
Specification in the HCL format looks like:
|
||||
|
||||
```text
|
||||
# These control access to the key/value store.
|
||||
key "" {
|
||||
policy = "read"
|
||||
}
|
||||
key "foo/" {
|
||||
policy = "write"
|
||||
}
|
||||
key "foo/private/" {
|
||||
policy = "deny"
|
||||
}
|
||||
|
||||
# This controls access to cluster-wide Consul operator information.
|
||||
operator = "read"
|
||||
```
|
||||
|
||||
This is equivalent to the following JSON input:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"key": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
},
|
||||
"foo/": {
|
||||
"policy": "write"
|
||||
},
|
||||
"foo/private": {
|
||||
"policy": "deny"
|
||||
}
|
||||
},
|
||||
"operator": "read"
|
||||
}
|
||||
```
|
||||
|
||||
The [ACL API](/api/acl.html) allows either HCL or JSON to be used to define the content
|
||||
of the rules section.
|
||||
|
||||
Here's a sample request using the HCL form:
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data \
|
||||
'{
|
||||
"Name": "my-app-token",
|
||||
"Type": "client",
|
||||
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
|
||||
}' https://consul.rocks/v1/acl/create?token=<acl master token>
|
||||
```
|
||||
|
||||
Here's an equivalent request using the JSON form:
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request PUT \
|
||||
--data \
|
||||
'{
|
||||
"Name": "my-app-token",
|
||||
"Type": "client",
|
||||
"Rules": "{\"key\":{\"\":{\"policy\":\"read\"},\"foo/\":{\"policy\":\"write\"},\"foo/private\":{\"policy\":\"deny\"}},\"operator\":\"read\"}"
|
||||
}' https://consul.rocks/v1/acl/create?token=<acl master token>
|
||||
```
|
||||
|
||||
On success, the token ID is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
||||
}
|
||||
```
|
||||
|
||||
This token ID can then be passed into Consul's HTTP APIs via the `token`
|
||||
query string parameter, or the `X-Consul-Token` request header, or Consul's
|
||||
CLI commands via the `token` argument, or the `CONSUL_HTTP_TOKEN` environment
|
||||
variable.
|
||||
|
||||
#### Agent Rules
|
||||
|
||||
The `agent` policy controls access to the utility operations in the [Agent API](/api/agent.html),
|
||||
such as join and leave. All of the catalog-related operations are covered by the [`node`](#node-rules)
|
||||
and [`service`](#service-rules) policies instead.
|
||||
|
||||
Agent rules look like this:
|
||||
|
||||
```text
|
||||
agent "" {
|
||||
policy = "read"
|
||||
}
|
||||
agent "foo" {
|
||||
policy = "write"
|
||||
}
|
||||
agent "bar" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
Agent rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to any node name with the empty prefix, allow
|
||||
read-write access to any node name that starts with "foo", and deny all access to any node name that
|
||||
starts with "bar".
|
||||
|
||||
Since [Agent API](/api/agent.html) 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
|
||||
configured with [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) to allow
|
||||
write access to these operations even if no ACL resolution capability is available.
|
||||
|
||||
#### Event Rules
|
||||
|
||||
The `event` policy controls access to event operations in the [Event API](/api/event.html), such as
|
||||
firing events and listing events.
|
||||
|
||||
Event rules look like this:
|
||||
|
||||
```text
|
||||
event "" {
|
||||
policy = "read"
|
||||
}
|
||||
event "deploy" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
Event rules are keyed by the event name prefix they apply to, using the longest prefix match rule.
|
||||
In the example above, the rules allow read-only access to any event, and firing of any event that
|
||||
starts with "deploy".
|
||||
|
||||
The [`consul exec`](/docs/commands/exec.html) command uses events with the "_rexec" prefix during
|
||||
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
|
||||
give agents a token with access to this event prefix, in addition to configuring
|
||||
[`disable_remote_exec`](/docs/agent/options.html#disable_remote_exec) to `false`.
|
||||
|
||||
#### Key/Value Rules
|
||||
|
||||
The `key` policy controls access to key/value store operations in the [KV API](/api/kv.html]. Key
|
||||
rules look like this:
|
||||
|
||||
```text
|
||||
key "" {
|
||||
policy = "read"
|
||||
}
|
||||
key "foo" {
|
||||
policy = "write"
|
||||
}
|
||||
key "bar" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
Key rules are keyed by the key name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to any key name with the empty prefix, allow
|
||||
read-write access to any key name that starts with "foo", and deny all access to any key name that
|
||||
starts with "bar".
|
||||
|
||||
#### Keyring Rules
|
||||
|
||||
The `keyring` policy controls access to keyring operations in the
|
||||
[Keyring API](/api/operator/keyring.html).
|
||||
|
||||
Keyring rules look like this:
|
||||
|
||||
```text
|
||||
keyring = "write"
|
||||
```
|
||||
|
||||
There's only one keyring policy allowed per rule set, and its value is set to one of the policy
|
||||
dispositions. In the example above, the keyring may be read and updated.
|
||||
|
||||
#### Node Rules
|
||||
|
||||
The `node` policy controls node-level registration and read access to the [Catalog API](/api/catalog.html),
|
||||
service discovery with the [Health API](/api/health.html), and filters results in [Agent API](/api/agent.html)
|
||||
operations like fetching the list of cluster members.
|
||||
|
||||
Node rules look like this:
|
||||
|
||||
```text
|
||||
node "" {
|
||||
policy = "read"
|
||||
}
|
||||
node "app" {
|
||||
policy = "write"
|
||||
}
|
||||
node "admin" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
Node rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to any node name with the empty prefix, allow
|
||||
read-write access to any node name that starts with "app", and deny all access to any node name that
|
||||
starts with "admin".
|
||||
|
||||
Agents need to be configured with an [`acl_agent_token`](/docs/agent/options.html#acl_agent_token)
|
||||
with at least "write" privileges to their own node name in order to register their information with
|
||||
the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent
|
||||
will print an error to the console when it tries to sync its state with the catalog.
|
||||
|
||||
Consul's DNS interface is also affected by restrictions on node rules. If the
|
||||
[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a
|
||||
given node, then the DNS interface will return no records when queried for it.
|
||||
|
||||
When reading from the catalog or retrieving information from the health endpoints, node rules are
|
||||
used to filter the results of the query. This allows for configurations where a token has access
|
||||
to a given service name, but only on an allowed subset of node names.
|
||||
|
||||
Node rules come into play when using the [Agent API](/api/agent.html) to register node-level
|
||||
checks. The agent will check tokens locally as a check is registered, and Consul also performs
|
||||
periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an
|
||||
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
|
||||
to use for registration events:
|
||||
|
||||
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration
|
||||
directive. This allows a single token to be configured globally and used
|
||||
during all check registration operations.
|
||||
2. Providing 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. Examples of what this looks like are
|
||||
available for both [services](/docs/agent/services.html) and
|
||||
[checks](/docs/agent/checks.html). Tokens may also be passed to the
|
||||
[HTTP API](/api/index.html) for operations that require them.
|
||||
|
||||
#### Operator Rules
|
||||
|
||||
The `operator` policy controls access to cluster-level operations in the
|
||||
[Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html).
|
||||
|
||||
Operator rules look like this:
|
||||
|
||||
```text
|
||||
operator = "read"
|
||||
```
|
||||
|
||||
There's only one operator policy allowed per rule set, and its value is set to one of the policy
|
||||
dispositions. In the example above, the token could be used to query the operator endpoints for
|
||||
diagnostic purposes but not make any changes.
|
||||
|
||||
#### Prepared Query Rules
|
||||
|
||||
The `query` policy controls access to create, update, and delete prepared queries in the
|
||||
[Prepared Query API](/api/query.html). Executing queries is subject to `node` and `service`
|
||||
policies, as will be explained below.
|
||||
|
||||
Query rules look like this:
|
||||
|
||||
```text
|
||||
query "" {
|
||||
policy = "read"
|
||||
}
|
||||
query "foo" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
Query rules are keyed by the query name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to any query name with the empty prefix, and allow
|
||||
read-write access to any query name that starts with "foo". This allows control of the query namespace
|
||||
to be delegated based on ACLs.
|
||||
|
||||
There are a few variations when using ACLs with prepared queries, each of which uses ACLs in one of two
|
||||
ways: open, protected by unguessable IDs or closed, managed by ACL policies. These variations are covered
|
||||
here, with examples:
|
||||
|
||||
* Static queries with no `Name` defined are not controlled by any ACL policies.
|
||||
These types of queries are meant to be ephemeral and not shared to untrusted
|
||||
clients, and they are only reachable if the prepared query ID is known. Since
|
||||
these IDs are generated using the same random ID scheme as ACL Tokens, it is
|
||||
infeasible to guess them. When listing all prepared queries, only a management
|
||||
token will be able to see these types, though clients can read instances for
|
||||
which they have an ID. An example use for this type is a query built by a
|
||||
startup script, tied to a session, and written to a configuration file for a
|
||||
process to use via DNS.
|
||||
|
||||
* Static queries with a `Name` defined are controlled by the `query` ACL policy.
|
||||
Clients are required to have an ACL token with a prefix sufficient to cover
|
||||
the name they are trying to manage, with a longest prefix match providing a
|
||||
way to define more specific policies. Clients can list or read queries for
|
||||
which they have "read" access based on their prefix, and similar they can
|
||||
update any queries for which they have "write" access. An example use for
|
||||
this type is a query with a well-known name (eg. `prod-master-customer-db`)
|
||||
that is used and known by many clients to provide geo-failover behavior for
|
||||
a database.
|
||||
|
||||
* [Template queries](/api/query.html#templates)
|
||||
queries work like static queries with a `Name` defined, except that a catch-all
|
||||
template with an empty `Name` requires an ACL token that can write to any query
|
||||
prefix.
|
||||
|
||||
When prepared queries are executed via DNS lookups or HTTP requests, the ACL
|
||||
checks are run against the service being queried, similar to how ACLs work with
|
||||
other service lookups. There are several ways the ACL token is selected for this
|
||||
check:
|
||||
|
||||
* If an ACL Token was captured when the prepared query was defined, it will be
|
||||
used to perform the service lookup. This allows queries to be executed by
|
||||
clients with lesser or even no ACL Token, so this should be used with care.
|
||||
|
||||
* If no ACL Token was captured, then the client's ACL Token will be used to
|
||||
perform the service lookup.
|
||||
|
||||
* If no ACL Token was captured and the client has no ACL Token, then the
|
||||
anonymous token will be used to perform the service lookup.
|
||||
|
||||
In the common case, the ACL Token of the invoker is used
|
||||
to test the ability to look up a service. If a `Token` was specified when the
|
||||
prepared query was created, the behavior changes and now the captured
|
||||
ACL Token set by the definer of the query is used when looking up a service.
|
||||
|
||||
Capturing ACL Tokens is analogous to
|
||||
[PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html)
|
||||
`SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL
|
||||
Token is similar to the complementary `SECURITY INVOKER` attribute.
|
||||
|
||||
Prepared queries were originally introduced in Consul 0.6.0, and ACL behavior remained
|
||||
unchanged through version 0.6.3, but was then changed to allow better management of the
|
||||
prepared query namespace.
|
||||
|
||||
These differences are outlined in the table below:
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Operation</th>
|
||||
<th>Version <= 0.6.3 </th>
|
||||
<th>Version > 0.6.3 </th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Create static query without `Name`</td>
|
||||
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
|
||||
<td>No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Create static query with `Name`</td>
|
||||
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
|
||||
<td>The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Manage static query without `Name`</td>
|
||||
<td>The ACL Token used to create the query, or a management token must be supplied in order to perform these operations.</td>
|
||||
<td>Any client with the ID of the query can perform these operations.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Manage static query with a `Name`</td>
|
||||
<td>The ACL token used to create the query, or a management token must be supplied in order to perform these operations.</td>
|
||||
<td>Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>List queries</td>
|
||||
<td>A management token is required to list any queries.</td>
|
||||
<td>The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Execute query</td>
|
||||
<td>Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored.</td>
|
||||
<td>The captured token, client's token, or anonymous token is used to filter the results, as described above.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
#### Service Rules
|
||||
|
||||
The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog.html)
|
||||
and service discovery with the [Health API](/api/health.html).
|
||||
|
||||
Service rules look like this:
|
||||
|
||||
```text
|
||||
service "" {
|
||||
policy = "read"
|
||||
}
|
||||
service "app" {
|
||||
policy = "write"
|
||||
}
|
||||
service "admin" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
Service rules are keyed by the service name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to any service name with the empty prefix, allow
|
||||
read-write access to any service name that starts with "app", and deny all access to any service name that
|
||||
starts with "admin".
|
||||
|
||||
Consul's DNS interface is affected by restrictions on service rules. If the
|
||||
[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a
|
||||
given service, then the DNS interface will return no records when queried for it.
|
||||
|
||||
When reading from the catalog or retrieving information from the health endpoints, service rules are
|
||||
used to filter the results of the query.
|
||||
|
||||
Service rules come into play when using the [Agent API](/api/agent.html) to register services or
|
||||
checks. The agent will check tokens locally as a service or check is registered, and Consul also
|
||||
performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an
|
||||
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
|
||||
to use for registration events:
|
||||
|
||||
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration
|
||||
directive. This allows a single token to be configured globally and used
|
||||
during all service and check registration operations.
|
||||
2. Providing 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. Examples of what this looks like are
|
||||
available for both [services](/docs/agent/services.html) and
|
||||
[checks](/docs/agent/checks.html). Tokens may also be passed to the
|
||||
[HTTP API](/api/index.html) for operations that require them.
|
||||
|
||||
#### Session Rules
|
||||
|
||||
The `session` policy controls access to [Session API](/api/session.html)] operations.
|
||||
|
||||
Session rules look like this:
|
||||
|
||||
```text
|
||||
session "" {
|
||||
policy = "read"
|
||||
}
|
||||
session "app" {
|
||||
policy = "write"
|
||||
}
|
||||
session "admin" {
|
||||
policy = "deny"
|
||||
}
|
||||
```
|
||||
|
||||
Session rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In
|
||||
the example above, the rules allow read-only access to sessions on node name with the empty prefix, allow
|
||||
creating sessions on any node name that starts with "app", and deny all access to any sessions on a node
|
||||
name that starts with "admin".
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
<a name="replication"></a>
|
||||
#### Outages and ACL Replication
|
||||
|
||||
The Consul ACL system is designed with flexible rules to accommodate for an outage
|
||||
of the [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) or networking
|
||||
issues preventing access to it. In this case, it may be impossible for
|
||||
agents in non-authoritative datacenters to resolve tokens. Consul provides
|
||||
a number of configurable [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
choices to tune behavior. It is possible to deny or permit all actions or to ignore
|
||||
cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs
|
||||
for any previously resolved tokens and to deny any uncached tokens.
|
||||
|
||||
Consul 0.7 added an ACL Replication capability that can allow non-authoritative
|
||||
datacenter agents to resolve even uncached tokens. This is enabled by setting an
|
||||
[`acl_replication_token`](/docs/agent/options.html#acl_replication_token) in the
|
||||
configuration on the servers in the non-authoritative datacenters. With replication
|
||||
enabled, the servers will maintain a replica of the authoritative datacenter's full
|
||||
set of ACLs on the non-authoritative servers. The ACL replication token needs to be
|
||||
a valid ACL token with management privileges, it can also be the same as the master
|
||||
ACL token.
|
||||
|
||||
Replication occurs with a background process that looks for new ACLs approximately
|
||||
every 30 seconds. Replicated changes are written at a rate that's throttled to
|
||||
100 updates/second, so it may take several minutes to perform the initial sync of
|
||||
a large set of ACLs.
|
||||
|
||||
If there's a partition or other outage affecting the authoritative datacenter,
|
||||
and the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
is set to "extend-cache", tokens will be resolved during the outage using the
|
||||
replicated set of ACLs. An [ACL replication status](/api/acl.html#acl_replication_status)
|
||||
endpoint is available to monitor the health of the replication process.
|
||||
|
||||
Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options.html#acl_ttl)
|
||||
setting of the non-authoritative datacenter, so these entries may persist in the
|
||||
cache for up to the TTL, even after the authoritative datacenter comes back online.
|
||||
|
||||
ACL replication can also be used to migrate ACLs from one datacenter to another
|
||||
using a process like this:
|
||||
|
||||
1. Enable ACL replication in all datacenters to allow continuation of service
|
||||
during the migration, and to populate the target datacenter. Verify replication
|
||||
is healthy and caught up to the current ACL index in the target datacenter
|
||||
using the [ACL replication status](/api/acl.html#acl_replication_status)
|
||||
endpoint.
|
||||
2. Turn down the old authoritative datacenter servers.
|
||||
3. Rolling restart the agents in the target datacenter and change the
|
||||
`acl_datacenter` servers to itself. This will automatically turn off
|
||||
replication and will enable the datacenter to start acting as the authoritative
|
||||
datacenter, using its replicated ACLs from before.
|
||||
3. Rolling restart the agents in other datacenters and change their `acl_datacenter`
|
||||
configuration to the target datacenter.
|
||||
|
||||
<a name="version_8_acls"></a>
|
||||
#### Complete ACL Coverage in Consul 0.8
|
||||
|
||||
Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consul
|
||||
agents for the first time. To ease the transition to Consul 0.8 for existing ACL
|
||||
users, there's a configuration option to disable these new features. To disable
|
||||
support for these new ACLs, set the
|
||||
[`acl_enforce_version_8`](/docs/agent/options.html#acl_enforce_version_8) configuration
|
||||
option to `false` on Consul clients and servers.
|
||||
|
||||
Here's a summary of the new features:
|
||||
|
||||
* Agents now check [`node`](#node-rules) and [`service`](#service-rules) ACL policies
|
||||
for catalog-related operations in `/v1/agent` endpoints, such as service and check
|
||||
registration and health check updates.
|
||||
* Agents enforce a new [`agent`](#agent-rules) ACL policy for utility operations in
|
||||
`/v1/agent` endpoints, such as joins and leaves.
|
||||
* A new [`node`](#node-rules) ACL policy is enforced throughout Consul, providing a
|
||||
mechanism to restrict registration and discovery of nodes by name. This also applies
|
||||
to service discovery, so provides an additional dimension for controlling access to
|
||||
services.
|
||||
* A new [`session`](#session-rules) ACL policy controls the ability to create session
|
||||
objects by node name.
|
||||
* Anonymous prepared queries (non-templates without a `Name`) now require a valid
|
||||
session, which ties their creation to the new [`session`](#session-rules) ACL policy.
|
||||
* The existing [`event`](#event-rules) ACL policy has been applied to the
|
||||
`/v1/event/list` endpoint.
|
||||
|
||||
Two new configuration options are used once version 8 ACLs are enabled:
|
||||
|
||||
* [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) is used as
|
||||
a special access token that has `agent` ACL policy `write` privileges on each agent where
|
||||
it is configured. This token should only be used by operators during outages when Consul
|
||||
servers aren't available to resolve ACL tokens. Applications should use regular ACL
|
||||
tokens during normal operation.
|
||||
* [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is used internally by
|
||||
Consul agents to perform operations to the service catalog when registering themselves
|
||||
or sending network coordinates to the servers. This token must at least have `node` ACL
|
||||
policy `write` access to the node name it will register as in order to register any
|
||||
node-level information like metadata or tagged addresses.
|
||||
|
||||
Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
now applies to Consul clients as well as Consul servers. This will determine what the
|
||||
client will do in the event that the servers are down.
|
||||
|
||||
Consul clients must have [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configured
|
||||
in order to enable agent-level ACL features. If this is set, the agents will contact the Consul
|
||||
servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not
|
||||
enabled, they will check at most every 2 minutes to see if they have become enabled, and will
|
||||
start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will
|
||||
need to use the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) to
|
||||
perform agent-level operations if the Consul servers aren't present (such as for a manual join
|
||||
to the cluster), unless the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) on the
|
||||
agent is set to "allow".
|
||||
|
||||
Non-server agents do not need to have the
|
||||
[`acl_master_token`](/docs/agent/options.html#acl_agent_master_token) configured; it is not
|
||||
used by agents in any way.
|
||||
|
|
@ -14,7 +14,7 @@ guidance to do them safely.
|
|||
|
||||
The following guides are available:
|
||||
|
||||
* [Atlas Integration](/docs/guides/atlas.html) - This guide covers how to integrate [Atlas](https://atlas.hashicorp.com) with Consul.
|
||||
* [ACLs](/docs/guides/acl.html) - This guide covers Consul's Access Control List (ACL) capability, which can be used to control access to Consul resources.
|
||||
|
||||
* [Autopilot](/docs/guides/autopilot.html) - This guide covers Autopilot, which provides automatic operator-friendly management of Consul servers.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,619 +8,5 @@ description: |-
|
|||
|
||||
# ACL System
|
||||
|
||||
Consul provides an optional Access Control List (ACL) system which can be used to control
|
||||
access to data and APIs. The ACL is
|
||||
[Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying
|
||||
on tokens to which fine grained rules can be applied. It is very similar to
|
||||
[AWS IAM](http://aws.amazon.com/iam/) in many ways.
|
||||
|
||||
## Scope
|
||||
|
||||
When the ACL system was launched in Consul 0.4, it was only possible to specify
|
||||
policies for the KV store. In Consul 0.5, ACL policies were extended to service
|
||||
registrations. In Consul 0.6, ACL's were further extended to restrict service
|
||||
discovery mechanisms, user events, and encryption keyring operations.
|
||||
|
||||
## ACL Design
|
||||
|
||||
The ACL system is designed to be easy to use, fast to enforce, and flexible to new
|
||||
policies, all while providing administrative insight.
|
||||
|
||||
Every token has an ID, name, type, and rule set. The ID is a randomly generated
|
||||
UUID, making it unfeasible to guess. The name is opaque to Consul and human readable.
|
||||
The type is either "client" (meaning the token cannot modify ACL rules) or "management"
|
||||
(meaning the token is allowed to perform all actions).
|
||||
|
||||
The token ID is passed along with each RPC request to the servers. Agents
|
||||
can be configured with an [`acl_token`](/docs/agent/options.html#acl_token) property
|
||||
to provide a default token, but the token can also be specified by a client on a
|
||||
[per-request basis](/api/index.html). ACLs were added in Consul 0.4, meaning
|
||||
prior versions do not provide a token. This is handled by the special "anonymous"
|
||||
token. If no token is provided, the rules associated with the anonymous token are
|
||||
automatically applied: this allows policy to be enforced on legacy clients.
|
||||
|
||||
ACLs can also act in either a whitelist or blacklist mode depending
|
||||
on the configuration of
|
||||
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy). If the
|
||||
default policy is to deny all actions, then token rules can be set to whitelist
|
||||
specific actions. In the inverse, the allow all default behavior is a blacklist
|
||||
where rules are used to prohibit actions. By default, Consul will allow all
|
||||
actions.
|
||||
|
||||
#### ACL Datacenter
|
||||
|
||||
Enforcement is always done by the server nodes. All servers must be configured
|
||||
to provide an [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) which
|
||||
enables ACL enforcement but also specifies the authoritative datacenter. Consul
|
||||
relies on [RPC forwarding](/docs/internals/architecture.html) to support
|
||||
Multi-Datacenter configurations. However, because requests can be made
|
||||
across datacenter boundaries, ACL tokens must be valid globally. To avoid
|
||||
consistency issues, a single datacenter is considered authoritative and stores
|
||||
the canonical set of tokens.
|
||||
|
||||
When a request is made to a server in a non-authoritative datacenter server, it
|
||||
must be resolved into the appropriate policy. This is done by reading the token
|
||||
from the authoritative server and caching the result for a configurable
|
||||
[`acl_ttl`](/docs/agent/options.html#acl_ttl). The implication
|
||||
of caching is that the cache TTL is an upper bound on the staleness of policy
|
||||
that is enforced. It is possible to set a zero TTL, but this has adverse
|
||||
performance impacts, as every request requires refreshing the policy via a
|
||||
cross-datacenter WAN RPC call.
|
||||
|
||||
#### Outages and ACL Replication
|
||||
|
||||
The Consul ACL system is designed with flexible rules to accommodate for an outage
|
||||
of the [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) or networking
|
||||
issues preventing access to it. In this case, it may be impossible for
|
||||
servers in non-authoritative datacenters to resolve tokens. Consul provides
|
||||
a number of configurable [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
choices to tune behavior. It is possible to deny or permit all actions or to ignore
|
||||
cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs
|
||||
for any previously resolved tokens and to deny any uncached tokens.
|
||||
|
||||
<a name="replication"></a>
|
||||
Consul 0.7 added an ACL Replication capability that can allow non-authoritative
|
||||
datacenter servers to resolve even uncached tokens. This is enabled by setting an
|
||||
[`acl_replication_token`](/docs/agent/options.html#acl_replication_token) in the
|
||||
configuration on the servers in the non-authoritative datacenters. With replication
|
||||
enabled, the servers will maintain a replica of the authoritative datacenter's full
|
||||
set of ACLs on the non-authoritative servers. The ACL replication token needs to be
|
||||
a valid ACL token with management privileges, it can also be the same as the master
|
||||
ACL token.
|
||||
|
||||
Replication occurs with a background process that looks for new ACLs approximately
|
||||
every 30 seconds. Replicated changes are written at a rate that's throttled to
|
||||
100 updates/second, so it may take several minutes to perform the initial sync of
|
||||
a large set of ACLs.
|
||||
|
||||
If there's a partition or other outage affecting the authoritative datacenter,
|
||||
and the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
is set to "extend-cache", tokens will be resolved during the outage using the
|
||||
replicated set of ACLs. An [ACL replication status](/api/acl.html#acl_replication_status)
|
||||
endpoint is available to monitor the health of the replication process.
|
||||
|
||||
Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options.html#acl_ttl)
|
||||
setting of the non-authoritative datacenter, so these entries may persist in the
|
||||
cache for up to the TTL, even after the authoritative datacenter comes back online.
|
||||
|
||||
ACL replication can also be used to migrate ACLs from one datacenter to another
|
||||
using a process like this:
|
||||
|
||||
1. Enable ACL replication in all datacenters to allow continuation of service
|
||||
during the migration, and to populate the target datacenter. Verify replication
|
||||
is healthy and caught up to the current ACL index in the target datacenter
|
||||
using the [ACL replication status](/api/acl.html#acl_replication_status)
|
||||
endpoint.
|
||||
2. Turn down the old authoritative datacenter servers.
|
||||
3. Rolling restart the servers in the target datacenter and change the
|
||||
`acl_datacenter` configuration to itself. This will automatically turn off
|
||||
replication and will enable the datacenter to start acting as the authoritative
|
||||
datacenter, using its replicated ACLs from before.
|
||||
3. Rolling restart the servers in other datacenters and change their `acl_datacenter`
|
||||
configuration to the target datacenter.
|
||||
|
||||
#### Bootstrapping ACLs
|
||||
|
||||
Bootstrapping the ACL system is done by providing an initial [`acl_master_token`
|
||||
configuration](/docs/agent/options.html#acl_master_token) which will be created
|
||||
as a "management" type token if it does not exist. The [`acl_master_token`
|
||||
](/docs/agent/options.html#acl_master_token) is only installed when a server acquires
|
||||
cluster leadership. If you would like to install or change the
|
||||
[`acl_master_token`](/docs/agent/options.html#acl_master_token), set the new value for
|
||||
[`acl_master_token`](/docs/agent/options.html#acl_master_token) in the configuration
|
||||
for all servers. Once this is done, restart the current leader to force a leader election.
|
||||
|
||||
## Rule Specification
|
||||
|
||||
A core part of the ACL system is a rule language which is used to describe the policy
|
||||
that must be enforced.
|
||||
|
||||
Key policies are defined by coupling a prefix with a policy. The rules are enforced
|
||||
using a longest-prefix match policy: Consul picks the most specific policy possible. The
|
||||
policy is either "read", "write", or "deny". A "write" policy implies "read", and there is no
|
||||
way to specify write-only. If there is no applicable rule, the
|
||||
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is applied.
|
||||
|
||||
Service policies are defined by coupling a service name and a policy. The rules are
|
||||
enforced using an longest-prefix match policy (this was an exact match in 0.5, but changed
|
||||
in 0.5.1). The default rule, applied to any service that doesn't have a matching policy,
|
||||
is provided using the empty string. A service policy is either "read", "write", or "deny".
|
||||
A "write" policy implies "read", and there is no way to specify write-only. If there is no
|
||||
applicable rule, the [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is
|
||||
applied. The "read" policy in a service ACL rule allows restricting access to
|
||||
the discovery of that service prefix. More information about service discovery
|
||||
and ACLs can be found [below](#discovery_acls).
|
||||
|
||||
The policy for the "consul" service is always "write" as it is managed internally by Consul.
|
||||
|
||||
User event policies are defined by coupling an event name prefix with a policy.
|
||||
The rules are enforced using a longest-prefix match policy. The default rule,
|
||||
applied to any user event without a matching policy, is provided by an empty
|
||||
string. An event policy is one of "read", "write", or "deny". Currently, only
|
||||
the "write" level is enforced during event firing. Events can always be read.
|
||||
|
||||
Prepared query policies control access to create, update, and delete prepared
|
||||
queries. Service policies are used when executing prepared queries. See
|
||||
[below](#prepared_query_acls) for more details.
|
||||
|
||||
We make use of
|
||||
the [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/)
|
||||
to specify policy. This language is human readable and interoperable
|
||||
with JSON making it easy to machine-generate.
|
||||
|
||||
Specification in the HCL format looks like:
|
||||
|
||||
```javascript
|
||||
# Default all keys to read-only
|
||||
key "" {
|
||||
policy = "read"
|
||||
}
|
||||
key "foo/" {
|
||||
policy = "write"
|
||||
}
|
||||
key "foo/private/" {
|
||||
# Deny access to the dir "foo/private"
|
||||
policy = "deny"
|
||||
}
|
||||
|
||||
# Default all services to allow registration. Also permits all
|
||||
# services to be discovered.
|
||||
service "" {
|
||||
policy = "write"
|
||||
}
|
||||
|
||||
# Deny registration access to services prefixed "secure-".
|
||||
# Discovery of the service is still allowed in read mode.
|
||||
service "secure-" {
|
||||
policy = "read"
|
||||
}
|
||||
|
||||
# Allow firing any user event by default.
|
||||
event "" {
|
||||
policy = "write"
|
||||
}
|
||||
|
||||
# Deny firing events prefixed with "destroy-".
|
||||
event "destroy-" {
|
||||
policy = "deny"
|
||||
}
|
||||
|
||||
# Default prepared queries to read-only.
|
||||
query "" {
|
||||
policy = "read"
|
||||
}
|
||||
|
||||
# Read-only mode for the encryption keyring by default (list only)
|
||||
keyring = "read"
|
||||
|
||||
# Read-only mode for Consul operator interfaces (list only)
|
||||
operator = "read"
|
||||
```
|
||||
|
||||
This is equivalent to the following JSON input:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"key": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
},
|
||||
"foo/": {
|
||||
"policy": "write"
|
||||
},
|
||||
"foo/private": {
|
||||
"policy": "deny"
|
||||
}
|
||||
},
|
||||
"service": {
|
||||
"": {
|
||||
"policy": "write"
|
||||
},
|
||||
"secure-": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"event": {
|
||||
"": {
|
||||
"policy": "write"
|
||||
},
|
||||
"destroy-": {
|
||||
"policy": "deny"
|
||||
}
|
||||
},
|
||||
"query": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"keyring": "read",
|
||||
"operator": "read"
|
||||
}
|
||||
```
|
||||
|
||||
## Building ACL Policies
|
||||
|
||||
#### Blacklist Mode and `consul exec`
|
||||
|
||||
If you set [`acl_default_policy`](/docs/agent/options.html#acl_default_policy)
|
||||
to `deny`, the `anonymous` token won't have permission to read the default
|
||||
`_rexec` prefix; therefore, Consul agents using the `anonymous` token
|
||||
won't be able to perform [`consul exec`](/docs/commands/exec.html) actions.
|
||||
|
||||
Here's why: the agents need read/write permission to the `_rexec` prefix for
|
||||
[`consul exec`](/docs/commands/exec.html) to work properly. They use that prefix
|
||||
as the transport for most data.
|
||||
|
||||
You can enable [`consul exec`](/docs/commands/exec.html) from agents that are not
|
||||
configured with a token by allowing the `anonymous` token to access that prefix.
|
||||
This can be done by giving this rule to the `anonymous` token:
|
||||
|
||||
```javascript
|
||||
key "_rexec/" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, you can, of course, add an explicit
|
||||
[`acl_token`](/docs/agent/options.html#acl_token) to each agent, giving it access
|
||||
to that prefix.
|
||||
|
||||
#### Blacklist Mode and Service Discovery
|
||||
|
||||
If your [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is
|
||||
set to `deny`, the `anonymous` token will be unable to read any service
|
||||
information. This will cause the service discovery mechanisms in the REST API
|
||||
and the DNS interface to return no results for any service queries. This is
|
||||
because internally the API's and DNS interface consume the RPC interface, which
|
||||
will filter results for services the token has no access to.
|
||||
|
||||
You can allow all services to be discovered, mimicing the behavior of pre-0.6.0
|
||||
releases, by configuring this ACL rule for the `anonymous` token:
|
||||
|
||||
```
|
||||
service "" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
The above will allow access for reading service information only. This
|
||||
level of access allows discovering other services in the system, but is not
|
||||
enough to allow the agent to sync its services and checks into the global
|
||||
catalog during [anti-entropy](/docs/internals/anti-entropy.html).
|
||||
|
||||
The most secure way of handling service registration and discovery is to run
|
||||
Consul 0.6+ and issue tokens with explicit access for the services or service
|
||||
prefixes which are expected to run on each agent.
|
||||
|
||||
#### Blacklist mode and Events
|
||||
|
||||
Similar to the above, if your
|
||||
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is set to
|
||||
`deny`, the `anonymous` token will have no access to allow firing user events.
|
||||
This deviates from pre-0.6.0 builds, where user events were completely
|
||||
unrestricted.
|
||||
|
||||
Events have their own first-class expression in the ACL syntax. To restore
|
||||
access to user events from arbitrary agents, configure an ACL rule like the
|
||||
following for the `anonymous` token:
|
||||
|
||||
```
|
||||
event "" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
As always, the more secure way to handle user events is to explicitly grant
|
||||
access to each API token based on the events they should be able to fire.
|
||||
|
||||
#### Blacklist Mode and Prepared Queries
|
||||
|
||||
After Consul 0.6.3, significant changes were made to ACLs for prepared queries,
|
||||
including a new `query` ACL policy. See [Prepared Query ACLs](#prepared_query_acls) below for more details.
|
||||
|
||||
<a name="keyring"></a>
|
||||
#### Blacklist Mode and Keyring Operations
|
||||
|
||||
Consul 0.6 and later supports securing the encryption keyring operations using
|
||||
ACL's. Encryption is an optional component of the gossip layer. More information
|
||||
about Consul's keyring operations can be found on the [keyring
|
||||
command](/docs/commands/keyring.html) documentation page.
|
||||
|
||||
If your [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is
|
||||
set to `deny`, then the `anonymous` token will not have access to read or write
|
||||
to the encryption keyring. The keyring policy is yet another first-class citizen
|
||||
in the ACL syntax. You can configure the anonymous token to have free reign over
|
||||
the keyring using a policy like the following:
|
||||
|
||||
```
|
||||
keyring = "write"
|
||||
```
|
||||
|
||||
Encryption keyring operations are sensitive and should be properly secured. It
|
||||
is recommended that instead of configuring a wide-open policy like above, a
|
||||
per-token policy is applied to maximize security.
|
||||
|
||||
<a name="operator"></a>
|
||||
#### Blacklist Mode and Consul Operator Actions
|
||||
|
||||
Consul 0.7 added special Consul operator actions which are protected by a new
|
||||
`operator` ACL policy. The operator actions cover:
|
||||
|
||||
* [Operator HTTP endpoint](/api/operator.html)
|
||||
* [Operator CLI command](/docs/commands/operator.html)
|
||||
|
||||
If your [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is
|
||||
set to `deny`, then the `anonymous` token will not have access to Consul operator
|
||||
actions. Granting `read` access allows reading information for diagnostic purposes
|
||||
without making any changes to state. Granting `write` access allows reading
|
||||
information and changing state. Here's an example policy:
|
||||
|
||||
```
|
||||
operator = "write"
|
||||
```
|
||||
|
||||
~> Grant `write` access to operator actions with extreme caution, as improper use
|
||||
could lead to a Consul outage and even loss of data.
|
||||
|
||||
#### Services and Checks with ACLs
|
||||
|
||||
Consul allows configuring ACL policies which may control access to service and
|
||||
check registration. In order to successfully register a service or check with
|
||||
these types of policies in place, a token with sufficient privileges must be
|
||||
provided to perform the registration into the global catalog. Consul also
|
||||
performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which
|
||||
may require an ACL token to complete. To accommodate this, Consul provides two
|
||||
methods of configuring ACL tokens to use for registration events:
|
||||
|
||||
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration
|
||||
directive. This allows a single token to be configured globally and used
|
||||
during all service and check registration operations.
|
||||
2. Providing 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. Examples of what this looks like are
|
||||
available for both [services](/docs/agent/services.html) and
|
||||
[checks](/docs/agent/checks.html). Tokens may also be passed to the
|
||||
[HTTP API](/api/index.html) for operations that require them.
|
||||
|
||||
<a name="discovery_acls"></a>
|
||||
#### Restricting service discovery with ACLs
|
||||
|
||||
In Consul 0.6, the ACL system was extended to support restricting read access to
|
||||
service registrations. This allows tighter access control and limits the ability
|
||||
of a compromised token to discover other services running in a cluster.
|
||||
|
||||
The ACL system permits a user to discover services using the REST API or UI if
|
||||
the token used during requests has "read"-level access or greater. Consul will
|
||||
filter out all services which the token has no access to in all API queries,
|
||||
making it appear as though the restricted services do not exist.
|
||||
|
||||
Consul's DNS interface is also affected by restrictions to service
|
||||
registrations. If the token used by the agent does not have access to a given
|
||||
service, then the DNS interface will return no records when queried for it.
|
||||
|
||||
<a name="prepared_query_acls"></a>
|
||||
## Prepared Query ACLs
|
||||
|
||||
As we've gotten feedback from Consul users, we've evolved how prepared queries
|
||||
use ACLs. In this section we first cover the current implementation, and then we
|
||||
follow that with details about what's changed between specific versions of Consul.
|
||||
|
||||
#### Managing Prepared Queries
|
||||
|
||||
Managing prepared queries includes creating, reading, updating, and deleting
|
||||
queries. There are a few variations, each of which uses ACLs in one of two
|
||||
ways: open, protected by unguessable IDs or closed, managed by ACL policies.
|
||||
These variations are covered here, with examples:
|
||||
|
||||
* Static queries with no `Name` defined are not controlled by any ACL policies.
|
||||
These types of queries are meant to be ephemeral and not shared to untrusted
|
||||
clients, and they are only reachable if the prepared query ID is known. Since
|
||||
these IDs are generated using the same random ID scheme as ACL Tokens, it is
|
||||
infeasible to guess them. When listing all prepared queries, only a management
|
||||
token will be able to see these types, though clients can read instances for
|
||||
which they have an ID. An example use for this type is a query built by a
|
||||
startup script, tied to a session, and written to a configuration file for a
|
||||
process to use via DNS.
|
||||
|
||||
* Static queries with a `Name` defined are controlled by the
|
||||
[`query`](/docs/internals/acl.html#prepared_query_acls) ACL policy.
|
||||
Clients are required to have an ACL token with a prefix sufficient to cover
|
||||
the name they are trying to manage, with a longest prefix match providing a
|
||||
way to define more specific policies. Clients can list or read queries for
|
||||
which they have "read" access based on their prefix, and similar they can
|
||||
update any queries for which they have "write" access. An example use for
|
||||
this type is a query with a well-known name (eg. `prod-master-customer-db`)
|
||||
that is used and known by many clients to provide geo-failover behavior for
|
||||
a database.
|
||||
|
||||
* [Template queries](https://www.consul.io/api/query.html#templates)
|
||||
queries work like static queries with a `Name` defined, except that a catch-all
|
||||
template with an empty `Name` requires an ACL token that can write to any query
|
||||
prefix.
|
||||
|
||||
#### Executing Pepared Queries
|
||||
|
||||
When prepared queries are executed via DNS lookups or HTTP requests, the ACL
|
||||
checks are run against the service being queried, similar to how ACLs work with
|
||||
other service lookups. There are several ways the ACL token is selected for this
|
||||
check:
|
||||
|
||||
* If an ACL Token was captured when the prepared query was defined, it will be
|
||||
used to perform the service lookup. This allows queries to be executed by
|
||||
clients with lesser or even no ACL Token, so this should be used with care.
|
||||
|
||||
* If no ACL Token was captured, then the client's ACL Token will be used to
|
||||
perform the service lookup.
|
||||
|
||||
* If no ACL Token was captured and the client has no ACL Token, then the
|
||||
anonymous token will be used to perform the service lookup.
|
||||
|
||||
In the common case, the ACL Token of the invoker is used
|
||||
to test the ability to look up a service. If a `Token` was specified when the
|
||||
prepared query was created, the behavior changes and now the captured
|
||||
ACL Token set by the definer of the query is used when looking up a service.
|
||||
|
||||
Capturing ACL Tokens is analogous to
|
||||
[PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html)
|
||||
`SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL
|
||||
Token is similar to the complementary `SECURITY INVOKER` attribute.
|
||||
|
||||
<a name="prepared_query_acl_changes"></a>
|
||||
#### ACL Implementation Changes for Prepared Queries
|
||||
|
||||
Prepared queries were originally introduced in Consul 0.6.0, and ACL behavior remained
|
||||
unchanged through version 0.6.3, but was then changed to allow better management of the
|
||||
prepared query namespace.
|
||||
|
||||
These differences are outlined in the table below:
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Operation</th>
|
||||
<th>Version <= 0.6.3 </th>
|
||||
<th>Version > 0.6.3 </th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Create static query without `Name`</td>
|
||||
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
|
||||
<td>No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Create static query with `Name`</td>
|
||||
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
|
||||
<td>The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Manage static query without `Name`</td>
|
||||
<td>The ACL Token used to create the query, or a management token must be supplied in order to perform these operations.</td>
|
||||
<td>Any client with the ID of the query can perform these operations.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Manage static query with a `Name`</td>
|
||||
<td>The ACL token used to create the query, or a management token must be supplied in order to perform these operations.</td>
|
||||
<td>Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>List queries</td>
|
||||
<td>A management token is required to list any queries.</td>
|
||||
<td>The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Execute query</td>
|
||||
<td>Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored.</td>
|
||||
<td>The captured token, client's token, or anonymous token is used to filter the results, as described above.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<a name="version_8_acls"></a>
|
||||
## ACL Changes Coming in Consul 0.8
|
||||
|
||||
Consul 0.8 will feature complete ACL coverage for all of Consul. To ease the
|
||||
transition to the new policies, a beta version of complete ACL support is
|
||||
available starting in Consul 0.7.2.
|
||||
|
||||
Here's a summary of the upcoming changes:
|
||||
|
||||
* Agents now check `node` and `service` ACL policies for catalog-related operations
|
||||
in `/v1/agent` endpoints, such as service and check registration and health check
|
||||
updates.
|
||||
* Agents enforce a new `agent` ACL policy for utility operations in `/v1/agent`
|
||||
endpoints, such as joins and leaves.
|
||||
* A new `node` ACL policy is enforced throughout Consul, providing a mechanism to
|
||||
restrict registration and discovery of nodes by name. This also applies to
|
||||
service discovery, so provides an additional dimension for controlling access to
|
||||
services.
|
||||
* A new `session` ACL policy controls the ability to create session objects by node
|
||||
name.
|
||||
* Anonymous prepared queries (non-templates without a `Name`) now require a valid
|
||||
session, which ties their creation to the new `session` ACL policy.
|
||||
* The existing `event` ACL policy has been applied to the `/v1/event/list` endpoint.
|
||||
|
||||
#### New Configuration Options
|
||||
|
||||
To enable beta support for complete ACL coverage, set the
|
||||
[`acl_enforce_version_8`](/docs/agent/options.html#acl_enforce_version_8) configuration
|
||||
option to `true` on Consul clients and servers.
|
||||
|
||||
Two new configuration options are used once complete ACLs are enabled:
|
||||
|
||||
* [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) is used as
|
||||
a special access token that has `agent` ACL policy `write` privileges on each agent where
|
||||
it is configured. This token should only be used by operators during outages when Consul
|
||||
servers aren't available to resolve ACL tokens. Applications should use regular ACL
|
||||
tokens during normal operation.
|
||||
* [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is used internally by
|
||||
Consul agents to perform operations to the service catalog when registering themselves
|
||||
or sending network coordinates to the servers. This token must at least have `node` ACL
|
||||
policy `write` access to the node name it will register as in order to register any
|
||||
node-level information like metadata or tagged addresses.
|
||||
|
||||
Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
|
||||
now applies to Consul clients as well as Consul servers. This will determine what the
|
||||
client will do in the event that the servers are down.
|
||||
|
||||
Consul clients must have [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configured
|
||||
in order to enable agent-level ACL features. If this is set, the agents will contact the Consul
|
||||
servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not
|
||||
enabled, they will check at most every 2 minutes to see if they have become enabled, and will
|
||||
start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will
|
||||
need to use the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) to
|
||||
perform agent-level operations if the Consul servers aren't present (such as for a manual join
|
||||
to the cluster), unless the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) on the
|
||||
agent is set to "allow".
|
||||
|
||||
Non-server agents do not need to have the [`acl_master_token`](/docs/agent/options.html#acl_agent_master_token)
|
||||
configured; it is not used by agents in any way.
|
||||
|
||||
#### New ACL Policies
|
||||
|
||||
The new `agent` ACL policy looks like this:
|
||||
|
||||
```
|
||||
agent "<node name prefix>" {
|
||||
policy = "<read|write|deny>"
|
||||
}
|
||||
```
|
||||
|
||||
This affects utility-related agent endpoints, such as `/v1/agent/self` and `/v1/agent/join`.
|
||||
|
||||
The new `node` ACL policy looks like this:
|
||||
|
||||
```
|
||||
node "<node name prefix>" {
|
||||
policy = "<read|write|deny>"
|
||||
}
|
||||
````
|
||||
|
||||
This affects node registration, node discovery, service discovery, and endpoints like
|
||||
`/v1/agent/members`.
|
||||
|
||||
The new `session` ACL policy looks like this:
|
||||
|
||||
```
|
||||
session "<node name prefix>" {
|
||||
policy = "<read|write|deny>"
|
||||
}
|
||||
```
|
||||
|
||||
This affects all the of `/v1/session` endpoints.
|
||||
This has been moved into the [ACL Guide](/docs/guides/acl.html#complete-acl-coverage-in-consul-0-8), please update your link.
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ and update any scripts that passed a custom `-rpc-addr` to the following command
|
|||
|
||||
#### Version 8 ACLs Are Now Opt-Out
|
||||
|
||||
The [`acl_enforce_version_8`](/docs/agent/options.html#acl_enforce_version_8) configuration now defaults to `true` to enable [full version 8 ACL support](/docs/internals/acl.html#version_8_acls) by default. If you are upgrading an existing cluster with ACLs enabled, you will need to set this to `false` during the upgrade on **both Consul agents and Consul servers**. Version 8 ACLs were also changed so that [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) must be set on agents in order to enable the agent-side enforcement of ACLs. This makes for a smoother experience in clusters where ACLs aren't enabled at all, but where the agents would have to wait to contact a Consul server before learning that.
|
||||
The [`acl_enforce_version_8`](/docs/agent/options.html#acl_enforce_version_8) configuration now defaults to `true` to enable [full version 8 ACL support](/docs/guides/acl.html#version_8_acls) by default. If you are upgrading an existing cluster with ACLs enabled, you will need to set this to `false` during the upgrade on **both Consul agents and Consul servers**. Version 8 ACLs were also changed so that [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) must be set on agents in order to enable the agent-side enforcement of ACLs. This makes for a smoother experience in clusters where ACLs aren't enabled at all, but where the agents would have to wait to contact a Consul server before learning that.
|
||||
|
||||
#### Remote Exec Is Now Opt-In
|
||||
|
||||
|
|
@ -199,9 +199,8 @@ require any ACL to manage them, and prepared queries with a `Name` defined are
|
|||
now governed by a new `query` ACL policy that will need to be configured
|
||||
after the upgrade.
|
||||
|
||||
See the [Prepared Query ACLs](/docs/internals/acl.html#prepared_query_acls)
|
||||
internals guide for more details about the new behavior and how it compares to
|
||||
previous versions of Consul.
|
||||
See the [ACL Guide](/docs/guides/acl.html#prepared_query_acls) for more details
|
||||
about the new behavior and how it compares to previous versions of Consul.
|
||||
|
||||
## Consul 0.6
|
||||
|
||||
|
|
|
|||
|
|
@ -38,9 +38,6 @@
|
|||
<li<%= sidebar_current("docs-internals-sessions") %>>
|
||||
<a href="/docs/internals/sessions.html">Sessions</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-internals-acl") %>>
|
||||
<a href="/docs/internals/acl.html">ACLs</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-internals-anti-entropy") %>>
|
||||
<a href="/docs/internals/anti-entropy.html">Anti-Entropy</a>
|
||||
</li>
|
||||
|
|
@ -207,8 +204,8 @@
|
|||
<li<%= sidebar_current("docs-guides") %>>
|
||||
<a href="/docs/guides/index.html">Guides</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-guides-atlas") %>>
|
||||
<a href="/docs/guides/atlas.html">Atlas Integration</a>
|
||||
<li<%= sidebar_current("docs-guides-acl") %>>
|
||||
<a href="/docs/guides/acl.html">ACLs</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-servers") %>>
|
||||
<a href="/docs/guides/servers.html">Adding/Removing Servers</a>
|
||||
|
|
|
|||
Loading…
Reference in a new issue