From 09b9b4d3adcce7fa47cf8eabf9ade47eac5a813d Mon Sep 17 00:00:00 2001
From: Preetha <460133+preetapan@users.noreply.github.com>
Date: Fri, 14 Jan 2022 18:32:44 -0600
Subject: [PATCH] Add new page on multi DC ACLs (#12020)

New docs page that details the steps needed to configure ACLS and replication in federated datacenters.
---
 .../acl/acl-federated-datacenters.mdx         | 238 ++++++++++++++++++
 website/data/docs-nav-data.json               |   4 +
 2 files changed, 242 insertions(+)
 create mode 100644 website/content/docs/security/acl/acl-federated-datacenters.mdx

diff --git a/website/content/docs/security/acl/acl-federated-datacenters.mdx b/website/content/docs/security/acl/acl-federated-datacenters.mdx
new file mode 100644
index 0000000000..1c5b637921
--- /dev/null
+++ b/website/content/docs/security/acl/acl-federated-datacenters.mdx
@@ -0,0 +1,238 @@
+---
+layout: docs
+page_title: ACL in Federated Datacenters
+description: >-
+  This topic describes the specific ACL bootstrapping policies that are necessary when ACLs are enabled for federated, multi-datacenter deployments.
+---
+
+# ACLs in Federated Datacenters
+
+This topic describes how to set up Consul's access control list (ACL) system
+in cluster deployments that span multiple data centers. This documentation is applicable
+to new clusters rather than existing clusters.
+
+# Requirements
+
+Consul versions 1.4.0 and later
+
+## Configure ACLs in the Primary Datacenter
+
+In a [federated Consul deployment](/docs/k8s/installation/multi-cluster), one of the datacenters is marked as the primary datacenter.
+The `acl` configuration block should be added to the primary datacenter server's configuration file
+as shown in the following example.
+
+See the [ACL Config Stanza](/docs/agent/options#acl) for more detailed descriptions of each option.
+
+-> **Versions before 1.11.0:** The `initial_management` token was called the `master` token in versions
+prior to 1.11.0
+
+<CodeTabs heading="ACL Configuration in Primary">
+
+```hcl
+bootstrap_expect =  3
+primary_datacenter =  "PRIMARY_DATACENTER_VALUE"
+acl = {
+ enabled =  true
+ default_policy = "deny"
+ down_policy = "deny"
+ enable_token_persistence = true
+ enable_token_replication = true
+ tokens = {
+   initial_management =  "ACL_MANAGEMENT_TOKEN"
+   agent = "YOUR_ACL_AGENT_TOKEN"
+  }
+}
+
+```
+
+```json
+{
+  "bootstrap_expect": N,
+  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
+  "acl": {
+    "enabled": true,
+    "default_policy": "deny",
+    "down_policy": "deny",
+    "enable_token_persistence": true,
+    "enable_token_replication": true,
+    "tokens": {
+      "initial_management": "ACL_MANAGEMENT_TOKEN",
+      "agent": "ACL_AGENT_TOKEN"
+    }
+  }
+}
+```
+
+</CodeTabs>
+
+~> **Warning:** Note that most enterprise deployments have security requirements that prevent specifying tokens in configuration files.
+The `enable_token_persistence` flag is also set in the configuration example so that the token is stored to disk in the agent's
+[data directory](/docs/agent/options#_data_dir). Any future changes to the token that are made through the [API](/api/agent#update-acl-tokens) will
+be persisted to the same location, and the value in the config file will be ignored.
+
+The ACL agent token can also be set using the [`consul acl set-agent-token`](/commands/acl/set-agent-token) CLI as shown below.
+
+```shell-session
+$ consul acl set-agent-token agent "<agent token here>"
+```
+
+## Configure Servers in Secondary Datacenters
+
+Servers in secondary data centers must be configured to point to the primary data center
+as shown in the following example. Secondary data centers also need the ACL replication token
+provided to them.
+
+### Create the replication token for ACL Management
+
+Replication tokens are needed for ACL token replication and
+to create both [configuration entries](/docs/agent/config-entries) and [auth methods](/docs/acl/auth-methods)
+in connected secondary datacenters.
+
+Replication tokens require the following permissions:
+
+- `acl = "write"`: The permission allows you to replicate tokens.
+- `operator = "write"`: This permission enables the `proxy-default` configuration entries to be replicated and enables CA certificate signing in the secondary datacenter.
+- `policy = "read"` and `intentions = "read"` in the `service_prefix` field: These permissions enable `service-default` configuration entries, CA, and intention data to be replicated for all services.
+
+<CodeTabs heading="Replication Token Policy">
+
+<CodeBlockConfig filename="replication-policy.hcl">
+
+```hcl
+acl = "write"
+operator = "write"
+service_prefix "" {
+  policy = "read"
+  intentions = "read"
+}
+```
+
+</CodeBlockConfig>
+</CodeTabs>
+
+Create a replication policy with the following command:
+
+```shell-session
+$ consul acl policy create -name replication -rules @replication-policy.hcl
+```
+
+Use your newly created policy to create the replication token.
+
+```shell-session
+$ consul acl token create -description "replication token" -policy-name replication
+```
+
+### Configure the replication token in Secondary Datacenters
+
+Add the replication token generated above, to the ACL stanza in secondary datacenters.
+
+<CodeTabs heading = "ACL Configuration in Secondaries">
+
+```hcl
+primary_datacenter = "PRIMARY_DATACENTER_NAME"
+acl = {
+   enabled = true
+   default_policy =  "deny"
+   down_policy =  "deny"
+   tokens = {
+      agent =  "ACL_AGENT_TOKEN"
+      replication = "ACL_REPLICATION_TOKEN"
+   }
+}
+```
+
+```json
+{
+  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
+  "acl": {
+    "enabled": true,
+    "default_policy": "deny",
+    "down_policy": "deny",
+    "tokens": {
+      "agent": "ACL_AGENT_TOKEN",
+      "replication": "ACL_REPLICATION_TOKEN"
+    }
+  }
+}
+```
+
+</CodeTabs>
+
+~> **Warning:** When enabling ACL token replication in secondary datacenters,
+global tokens already present in the secondary datacenter will be lost. For
+production environments, consider configuring ACL replication in your initial
+datacenter bootstrapping process.
+
+~> **Warning:** If you are using [Consul Enterprise](/docs/enterprise) and
+the [Admin Partitions](https://www.consul.io/docs/enterprise/admin-partitions)
+feature, only ACL tokens in the default partition are replicated to other datacenters.
+
+## WAN Join Servers
+
+This step is needed for new federated cluster deployments in order for
+servers in each federated datacenter to discover each other.
+
+Run the following command from one of the server nodes.
+
+```shell-session
+$ consul join -token="ACL_MANAGEMENT_TOKEN" -wan [server 1, server 2, ...]
+```
+
+## Configure Clients in Secondary Datacenters
+
+When ACLs are enabled, client agents need a special token known as the [`agent token`](/docs/security/acl/acl-system#acl-agent-token) to perform internal operations. Agent tokens need to have the right policies for node related actions, including
+registering itself in the catalog, updating node level health checks, and performing [anti-entropy](/docs/architecture/anti-entropy) syncing.
+
+### Generate Agent ACL Token
+
+[ACL Node Identities](/docs/security/acl/acl-system#acl-node-identities) were introduced
+in Consul 1.8.1 and enable easily creating agent tokens with appropriately scoped policies.
+
+To generate the ACL token using node identity, run the following command:
+
+```shell-session
+$ consul acl token create -node-identity=<NODE_NAME>:<DATACENTER>
+```
+
+### Configure clients to use the ACL agent token
+
+Update the client agents to include the token value from the previous step. Replace
+the `ACL_AGENT_TOKEN` value below with the secret ID value from the command output.
+
+<CodeTabs heading = "ACL Configuration in Client Agents">
+
+```hcl
+primary_datacenter = "PRIMARY_DATACENTER_NAME"
+acl = {
+   enabled = true
+   default_policy =  "deny"
+   down_policy =  "deny"
+   tokens = {
+      agent =  "ACL_AGENT_TOKEN"
+   }
+}
+```
+
+```json
+{
+  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
+  "acl": {
+    "enabled": true,
+    "default_policy": "deny",
+    "down_policy": "deny",
+    "tokens": {
+      "agent": "ACL_AGENT_TOKEN"
+    }
+  }
+}
+```
+
+</CodeTabs>
+
+Note that client agents have to be restarted for ACL related configuration changes to take effect.
+
+## Summary
+
+After completing the above steps, a federated Consul cluster can be used with ACLs. Refer to
+[ACL Replication Guide](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters?in=consul/security-operations)
+for more on this topic.
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index fcfe7f9073..94e18d047c 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -822,6 +822,10 @@
             "title": "Token Migration",
             "path": "security/acl/acl-migrate-tokens"
           },
+          {
+            "title": "ACLs in Federated Datacenters",
+            "path": "security/acl/acl-federated-datacenters"
+          },
           {
             "title": "Auth Methods",
             "routes": [