mirror of https://github.com/hashicorp/consul
Add new page on multi DC ACLs (#12020)
New docs page that details the steps needed to configure ACLS and replication in federated datacenters.pull/12108/head
Preetha
3 years ago
committed by
GitHub
parent
a883aa7f8e
commit
09b9b4d3ad
@ -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.
|
||||||
Loading…
Reference in new issue