mirror of https://github.com/status-im/consul.git
docs: deprecate acl_datacenter and replace it with primary_datacenter
This commit is contained in:
Kyle Havlovitz
parent
c9217c958e
commit
46c829b879
|
|
@ -1047,6 +1047,7 @@ func (a *Agent) consulConfig() (*consul.Config, error) {
|
|||
// Copy the Connect CA bootstrap config
|
||||
if a.config.ConnectEnabled {
|
||||
base.ConnectEnabled = true
|
||||
base.ConnectReplicationToken = a.config.ConnectReplicationToken
|
||||
|
||||
// Allow config to specify cluster_id provided it's a valid UUID. This is
|
||||
// meant only for tests where a deterministic ID makes fixtures much simpler
|
||||
|
|
|
|||
|
|
@ -355,6 +355,9 @@ type Config struct {
|
|||
// CAConfig is used to apply the initial Connect CA configuration when
|
||||
// bootstrapping.
|
||||
CAConfig *structs.CAConfiguration
|
||||
|
||||
// ConnectReplicationToken is used to control Intention replication.
|
||||
ConnectReplicationToken string
|
||||
}
|
||||
|
||||
// CheckProtocolVersion validates the protocol version.
|
||||
|
|
|
|||
|
|
@ -377,7 +377,7 @@ $ curl \
|
|||
|
||||
- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
|
||||
replicated from, and will match the
|
||||
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configuration.
|
||||
[`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configuration.
|
||||
|
||||
- `ReplicatedIndex` is the last index that was successfully replicated. You can
|
||||
compare this to the `X-Consul-Index` header returned by the
|
||||
|
|
|
|||
|
|
@ -497,10 +497,10 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
|
||||
#### Configuration Key Reference
|
||||
|
||||
* <a name="acl_datacenter"></a><a href="#acl_datacenter">`acl_datacenter`</a> - This designates
|
||||
the datacenter which is authoritative for ACL information. It must be provided to enable ACLs.
|
||||
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,
|
||||
* <a name="acl_datacenter"></a><a href="#acl_datacenter">`acl_datacenter`</a> - **This field is
|
||||
deprecated in Consul 1.3.0. See the [`primary_datacenter`](#primary_datacenter) field instead.**
|
||||
|
||||
This designates the datacenter which is authoritative for ACL information. It must be provided to enable ACLs. 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 Guide](/docs/guides/acl.html) for more details.
|
||||
|
||||
|
|
@ -508,12 +508,12 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
"allow" or "deny"; defaults to "allow". The default policy controls the behavior of a token when
|
||||
there is no matching rule. In "allow" mode, ACLs are a blacklist: any operation not specifically
|
||||
prohibited is allowed. In "deny" mode, ACLs are a whitelist: any operation not
|
||||
specifically allowed is blocked. *Note*: this will not take effect until you've set `acl_datacenter`
|
||||
specifically allowed is blocked. *Note*: this will not take effect until you've set `primary_datacenter`
|
||||
to enable ACL support.
|
||||
|
||||
* <a name="acl_down_policy"></a><a href="#acl_down_policy">`acl_down_policy`</a> - Either
|
||||
"allow", "deny", "extend-cache" or "async-cache"; "extend-cache" is the default. In the case that the
|
||||
policy for a token cannot be read from the [`acl_datacenter`](#acl_datacenter) or leader
|
||||
policy for a token cannot be read from the [`primary_datacenter`](#primary_datacenter) or leader
|
||||
node, the down policy is applied. In "allow" mode, all actions are permitted, "deny" restricts
|
||||
all operations, and "extend-cache" allows any cached ACLs to be used, ignoring their TTL
|
||||
values. If a non-cached ACL is used, "extend-cache" acts like "deny".
|
||||
|
|
@ -546,7 +546,7 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
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
|
||||
for servers in the [`primary_datacenter`](#primary_datacenter). This token will be created with management-level
|
||||
permissions if it does not exist. It allows operators to bootstrap the ACL system
|
||||
with a token ID that is well-known.
|
||||
|
||||
|
|
@ -558,7 +558,7 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
the same as the other tokens, but isn't strictly necessary.
|
||||
|
||||
* <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.
|
||||
Only used for servers outside the [`primary_datacenter`](#primary_datacenter) running Consul 0.7 or later.
|
||||
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. In Consul 0.9.1
|
||||
and later you can enable ACL replication using [`enable_acl_replication`](#enable_acl_replication)
|
||||
|
|
@ -756,6 +756,8 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
|
||||
* <a name="connect_proxy_defaults"></a><a href="#connect_proxy_defaults">`proxy_defaults`</a> This object configures the default proxy settings for [service definitions with managed proxies](/docs/agent/services.html). It accepts the fields `exec_mode`, `daemon_command`, and `config`. These are used as default values for the respective fields in the service definition.
|
||||
|
||||
* <a name="replication_token"></a><a href="#replication_token">`replication_token`</a> When provided, this will enable Connect replication using this token to retrieve and replicate the Intentions to the non-authoritative local datacenter.
|
||||
|
||||
* <a name="datacenter"></a><a href="#datacenter">`datacenter`</a> Equivalent to the
|
||||
[`-datacenter` command-line flag](#_datacenter).
|
||||
|
||||
|
|
@ -1122,6 +1124,12 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
|
|||
* <a name="protocol"></a><a href="#protocol">`protocol`</a> Equivalent to the
|
||||
[`-protocol` command-line flag](#_protocol).
|
||||
|
||||
* <a name="primary_datacenter"></a><a href="#primary_datacenter">`primary_datacenter`</a> - This
|
||||
designates the datacenter which is authoritative for ACL information, intentions and is the root
|
||||
Certificate Authority for Connect. It must be provided to enable ACLs. All servers and datacenters
|
||||
must agree on the primary 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 Guide](/docs/guides/acl.html) for more details.
|
||||
|
||||
* <a name="raft_protocol"></a><a href="#raft_protocol">`raft_protocol`</a> Equivalent to the
|
||||
[`-raft-protocol` command-line flag](#_raft_protocol).
|
||||
|
||||
|
|
|
|||
|
|
@ -85,8 +85,8 @@ Constructing rules from these policies is covered in detail in the
|
|||
|
||||
#### ACL Datacenter
|
||||
|
||||
All nodes (clients and servers) must be configured with an
|
||||
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) which enables ACL
|
||||
All nodes (clients and servers) must be configured with a
|
||||
[`primary_datacenter`](/docs/agent/options.html#primary_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,
|
||||
|
|
@ -115,7 +115,7 @@ as to whether they are set on servers, clients, or 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 |
|
||||
| [`primary_datacenter`](/docs/agent/options.html#primary_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 do when the ACL datacenter is offline |
|
||||
| [`acl_ttl`](/docs/agent/options.html#acl_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs |
|
||||
|
|
@ -200,7 +200,7 @@ Here's the corresponding JSON configuration file:
|
|||
|
||||
```json
|
||||
{
|
||||
"acl_datacenter": "dc1",
|
||||
"primary_datacenter": "dc1",
|
||||
"acl_master_token": "b1gs33cr3t",
|
||||
"acl_default_policy": "deny",
|
||||
"acl_down_policy": "extend-cache"
|
||||
|
|
@ -273,7 +273,7 @@ configuration and restart the servers once more to apply it:
|
|||
|
||||
```json
|
||||
{
|
||||
"acl_datacenter": "dc1",
|
||||
"primary_datacenter": "dc1",
|
||||
"acl_master_token": "b1gs33cr3t",
|
||||
"acl_default_policy": "deny",
|
||||
"acl_down_policy": "extend-cache",
|
||||
|
|
@ -310,7 +310,7 @@ with a configuration file that enables ACLs:
|
|||
|
||||
```json
|
||||
{
|
||||
"acl_datacenter": "dc1",
|
||||
"primary_datacenter": "dc1",
|
||||
"acl_down_policy": "extend-cache",
|
||||
"acl_agent_token": "fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1"
|
||||
}
|
||||
|
|
@ -1029,7 +1029,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 [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) or networking
|
||||
of the [`primary_datacenter`](/docs/agent/options.html#primary_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)
|
||||
|
|
@ -1082,10 +1082,10 @@ 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
|
||||
`primary_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`
|
||||
3. Rolling restart the agents in other datacenters and change their `primary_datacenter`
|
||||
configuration to the target datacenter.
|
||||
|
||||
<a name="version_8_acls"></a>
|
||||
|
|
@ -1133,11 +1133,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 [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configured
|
||||
Consul clients must have [`primary_datacenter`](/docs/agent/options.html#primary_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
|
||||
start enforcing ACLs automatically. If an agent has an `acl_daprimary_datacentertacenter` 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
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ The following can be used to manage network areas:
|
|||
|
||||
Networks areas can be used alongside the Consul's [Basic Federation](/docs/guides/datacenters.html)
|
||||
model and the WAN gossip pool. This helps ease migration, and clusters like the
|
||||
[ACL datacenter](/docs/agent/options.html#acl_datacenter) are more easily managed via
|
||||
[primary datacenter](/docs/agent/options.html#primary_datacenter) are more easily managed via
|
||||
the WAN because they need to be available to all Consul datacenters.
|
||||
|
||||
A peer datacenter can connected via the WAN gossip pool and a network area at the
|
||||
|
|
|
|||
Loading…
Reference in New Issue