From 3a44d4612672fc83c0beab10a90e4a995a7736c3 Mon Sep 17 00:00:00 2001
From: James Phillips <slackpad@gmail.com>
Date: Wed, 14 Dec 2016 20:32:44 -0800
Subject: [PATCH] Adds some basic documentation about the new ACL changes.

---
 .../source/docs/internals/acl.html.markdown   | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/website/source/docs/internals/acl.html.markdown b/website/source/docs/internals/acl.html.markdown
index b156a3f7cb..e113f9dfc5 100644
--- a/website/source/docs/internals/acl.html.markdown
+++ b/website/source/docs/internals/acl.html.markdown
@@ -531,3 +531,83 @@ These differences are outlined in the table below:
     <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.
+  <br>
+  <br>
+  For clients, this token must at least have `node` ACL policy `write` access to the node
+  name it will register as. For servers, this must have `node` ACL policy `write` access to
+  all nodes that are expected to join the cluster, as well as `service` ACL policy `write`
+  access to the `consul` service, which will be registered automatically on its behalf.
+
+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 *do not* need to have the [`acl_master_token`](/docs/agent/options.html#acl_agent_master_token)
+or the [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configured. They will
+contact the Consul servers to determine if ACLs are enabled. 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.
+
+#### 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`.