From b64bda880843afaaf44591c3200f921626716849 Mon Sep 17 00:00:00 2001 From: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> Date: Tue, 7 May 2019 14:27:30 -0500 Subject: [PATCH] [docs] ACL Legacy Docs (#5625) * updating the acl legacy doc * Updatine ACLs based on PR #5002 --- website/source/api/acl/legacy.html.md | 6 +++++ website/source/docs/acl/acl-legacy.html.md | 28 +++++++++++++--------- website/source/layouts/docs.erb | 2 +- 3 files changed, 24 insertions(+), 12 deletions(-) diff --git a/website/source/api/acl/legacy.html.md b/website/source/api/acl/legacy.html.md index 8c3cd3643c..2b8c62132d 100644 --- a/website/source/api/acl/legacy.html.md +++ b/website/source/api/acl/legacy.html.md @@ -292,3 +292,9 @@ $ curl \ } ] ``` + + +## Check ACL Replication + +The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl.html#check-acl-replication) to learn more about this endpoint. + diff --git a/website/source/docs/acl/acl-legacy.html.md b/website/source/docs/acl/acl-legacy.html.md index 22ba65103e..b1dcb6ddc7 100644 --- a/website/source/docs/acl/acl-legacy.html.md +++ b/website/source/docs/acl/acl-legacy.html.md @@ -1,11 +1,13 @@ --- layout: "docs" -page_title: "ACL System (Legacy)" +page_title: "ACL System (Legacy Mode)" sidebar_current: "docs-acl-legacy" 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 in Legacy Mode + -> **1.3.0 and earlier:** This guide only applies in Consul versions 1.3.0 and before. If you are using the 1.4.0 or later please use the updated guide [here](/docs/acl/acl-system.html) @@ -85,6 +87,10 @@ and [Policies](/api/acl/policies.html). # Legacy ACL System +~> **Warning**: In this document we use the deprecated + configuration parameter `acl_datacenter`. In Consul 1.4 and newer the + parameter has been updated to [`primary_datacenter`](https://www.consul.io/docs/agent/options.html#primary_datacenter). + 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 @@ -163,7 +169,7 @@ Constructing rules from these policies is covered in detail in the #### ACL Datacenter All nodes (clients and servers) must be configured with a -[`primary_datacenter`](/docs/agent/options.html#primary_datacenter) which enables ACL +[`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, @@ -192,7 +198,7 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | -------------------- | ------- | ------- | ------- | -| [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | +| [`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_legacy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode | | [`acl_down_policy`](/docs/agent/options.html#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | | [`acl_ttl`](/docs/agent/options.html#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | @@ -277,7 +283,7 @@ Here's the corresponding JSON configuration file: ```json { - "primary_datacenter": "dc1", + "acl_datacenter": "dc1", "acl_master_token": "b1gs33cr3t", "acl_default_policy": "deny", "acl_down_policy": "extend-cache" @@ -350,7 +356,7 @@ configuration and restart the servers once more to apply it: ```json { - "primary_datacenter": "dc1", + "acl_datacenter": "dc1", "acl_master_token": "b1gs33cr3t", "acl_default_policy": "deny", "acl_down_policy": "extend-cache", @@ -387,7 +393,7 @@ with a configuration file that enables ACLs: ```json { - "primary_datacenter": "dc1", + "acl_datacenter": "dc1", "acl_down_policy": "extend-cache", "acl_agent_token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1" } @@ -1109,7 +1115,7 @@ name that starts with "admin". #### Outages and ACL Replication The Consul ACL system is designed with flexible rules to accommodate for an outage -of the [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) or networking +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) @@ -1162,10 +1168,10 @@ using the [ACL replication status](/api/acl/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 -`primary_datacenter` servers to itself. This will automatically turn off +`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 `primary_datacenter` +3. Rolling restart the agents in other datacenters and change their `acl_datacenter` configuration to the target datacenter. @@ -1213,11 +1219,11 @@ Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/opti 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 [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configured +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 `primary_datacenter` defined, operators 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 diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 43e2d0ef14..8b959e00d5 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -445,7 +445,7 @@ ACL Rules > - Legacy ACLs + Legacy Mode > Token Migration