docs(peering): peering GA ACL updates (#15366)
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Freddy <freddygv@users.noreply.github.com>
This commit is contained in:
Dan Stough
GitHub
parent
25376f5f06
commit
62023c7062
|
|
@ -198,6 +198,19 @@ Then, add the configuration entry to your cluster.
|
|||
$ consul config write peering-intentions.hcl
|
||||
```
|
||||
|
||||
### Authorize Service Reads with ACLs
|
||||
|
||||
If ACLs are enabled on a Consul cluster, sidecar proxies that access exported services as an upstream must have an ACL token that grants read access.
|
||||
Read access to all imported services is granted using either of the following rules associated with an ACL token:
|
||||
- `service:write` permissions for any service in the sidecar's partition.
|
||||
- `service:read` and `node:read` for all services and nodes, respectively, in sidecar's namespace and partition.
|
||||
For Consul Enterprise, access is granted to all imported services in the service's partition.
|
||||
These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities).
|
||||
|
||||
Example rule files can be found in [Reading Servers](/docs/connect/config-entries/exported-services#reading-services) in the `exported-services` config entry documentation.
|
||||
|
||||
Refer to [ACLs System Overview](/docs/security/acl) for more information on ACLs and their setup.
|
||||
|
||||
## Manage peering connections
|
||||
|
||||
After you establish a peering connection, you can get a list of all active peering connections, read a specific peering connection's information, check peering connection health, and delete peering connections.
|
||||
|
|
|
|||
|
|
@ -40,6 +40,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste
|
|||
| Gossip protocol: Requires LAN gossip only | ❌ | ✅ |
|
||||
| Forwards service requests for service discovery | ✅ | ❌ |
|
||||
| Shares key/value stores | ✅ | ❌ |
|
||||
| Can replicate ACL tokens, policies, and roles | ✅ | ❌ |
|
||||
|
||||
## Important Cluster Peering Constraints
|
||||
|
||||
|
|
|
|||
|
|
@ -661,20 +661,236 @@ The following example queries the `finance` peer for the imported `payments` ser
|
|||
```shell-session
|
||||
$ curl 'localhost:8500/v1/health/service/payments?peer=finance'
|
||||
```
|
||||
An ACL token with either of the following permissions is required in the cluster where the query is made:
|
||||
- `service:write` permissions for any service.
|
||||
- `service:read` and `node:read` for all services and nodes, respectively.
|
||||
|
||||
If the call in the previous example is made from a service named `web`, then the request requires either:
|
||||
- A token with `service:write` permissions to `web`.
|
||||
- A token with `service:read` and `node:read` to all names in the datacenter.
|
||||
|
||||
<CodeTabs heading="Example ACL rules for reading imported services in Consul OSS">
|
||||
|
||||
```hcl
|
||||
service "web" {
|
||||
policy = "write"
|
||||
}
|
||||
|
||||
# OR
|
||||
|
||||
service_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"service": {
|
||||
"web": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
## OR
|
||||
|
||||
{
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"node_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="Consul Enterprise">
|
||||
<Tab heading="Consul Enterprise (Partitions)">
|
||||
|
||||
The following example queries the `finance` partition for the imported `payments` service:
|
||||
|
||||
```shell-session
|
||||
$ curl 'localhost:8500/v1/health/service/payments?partition=finance'
|
||||
```
|
||||
|
||||
An ACL token with either of the following permissions is required in the cluster where the query is made:
|
||||
- `service:write` permissions for any service in the partition where the query is made.
|
||||
- `service:read` and `node:read` for all services and nodes, respectively, in any namespace and the exact partition where the query is made.
|
||||
|
||||
If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires either:
|
||||
- A token with `service:write` permissions to `web` in the `frontend` partition.
|
||||
- A token with `service:read` and `node:read` to all names in the `frontend` partition, for any namespace.
|
||||
|
||||
<CodeTabs heading="Example ACL rules for reading imported services from a partition in Consul Enterprise">
|
||||
|
||||
```hcl
|
||||
partition "frontend" {
|
||||
namespace "dev" { # This could be any namespace
|
||||
service "web" {
|
||||
policy = "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# OR
|
||||
|
||||
partition "frontend" {
|
||||
namespace "dev" { # This could be any namespace
|
||||
service_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"partition": {
|
||||
"frontend": {
|
||||
"namespace": {
|
||||
## The following could be any namespace
|
||||
"dev": {
|
||||
"service": {
|
||||
"web": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
## OR
|
||||
|
||||
{
|
||||
"partition": {
|
||||
"frontend": {
|
||||
"namespace": {
|
||||
## The following could be any namespace
|
||||
"dev": {
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"node_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="Consul Enterprise (Peers)">
|
||||
|
||||
The following example queries the `finance` peer for the imported `payments` service:
|
||||
|
||||
```shell-session
|
||||
$ curl 'localhost:8500/v1/health/service/payments?peer=finance'
|
||||
```
|
||||
|
||||
An ACL token with either of the following permissions is required in the cluster where the query is made:
|
||||
- `service:write` permissions for any service in the partition where the query is made.
|
||||
- `service:read` and `node:read` for all services and nodes, respectively, in any namespace and the exact partition where the query is made.
|
||||
|
||||
If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires either:
|
||||
- A token with `service:write` permissions to `web` in the `frontend` partition.
|
||||
- A token with `service:read` and `node:read` to all names in the `frontend` partition, for any namespace.
|
||||
|
||||
<CodeTabs heading="Example ACL rules for reading imported services from a peer in Consul Enterprise">
|
||||
|
||||
```hcl
|
||||
partition "frontend" {
|
||||
namespace "dev" { # This could be any namespace
|
||||
service "web" {
|
||||
policy = "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# OR
|
||||
|
||||
partition "frontend" {
|
||||
namespace "dev" { # This could be any namespace
|
||||
service_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"partition": {
|
||||
"frontend": {
|
||||
"namespace": {
|
||||
## The following could be any namespace
|
||||
"dev": {
|
||||
"service": {
|
||||
"web": {
|
||||
"policy": "write"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
## OR
|
||||
|
||||
{
|
||||
"partition": {
|
||||
"frontend": {
|
||||
"namespace": {
|
||||
## The following could be any namespace
|
||||
"dev": {
|
||||
"service_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
},
|
||||
"node_prefix": {
|
||||
"": {
|
||||
"policy": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
An ACL token with `service:write` permissions is required for the cluster the query is made from. If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires a token with `write` permissions to `web` in the `frontend` partition.
|
||||
|
||||
Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports.
|
||||
|
||||
For additional information, refer to [Health HTTP Endpoint](/api-docs/health).
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Mesh Gateways for Peering Control Plane Traffic
|
||||
page_title: Enabling Peering Control Plane Traffic
|
||||
description: >-
|
||||
Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable traffic across clusters in different datacenters or admin partitions that have an established peering connection.
|
||||
---
|
||||
|
||||
# Mesh Gateways for Peering Control Plane Traffic
|
||||
# Enabling Peering Control Plane Traffic
|
||||
|
||||
In addition to [service-to-service traffic routing](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers), mesh gateways can optionally be used to route control-plane traffic between peers.
|
||||
This includes the initial secret handshake and the bi-directional stream replicating peering data.
|
||||
|
|
@ -38,8 +38,55 @@ For Consul Enterprise clusters, mesh gateways must be registered in the "default
|
|||
|
||||
### ACL configuration
|
||||
|
||||
- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the "default" Enterprise admin partition or OSS datacenter to the gateway's service definition.
|
||||
These permissions authorize the token to route communications for other Consul service mesh services.
|
||||
<Tabs>
|
||||
<Tab heading="Consul OSS">
|
||||
|
||||
In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings.
|
||||
This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered datacenter.
|
||||
|
||||
<CodeTabs heading="Example ACL rules for Mesh Gateway Peering Control Plane Traffic in Consul OSS">
|
||||
|
||||
```hcl
|
||||
peering = "read"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"peering": "read"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="Consul Enterprise">
|
||||
|
||||
In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions.
|
||||
This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered partition.
|
||||
|
||||
<CodeTabs heading="Example ACL rules for Mesh Gateway Peering Control Plane Traffic in Consul Enterprise">
|
||||
|
||||
```hcl
|
||||
partition_prefix "" {
|
||||
peering = "read"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"partition_prefix": {
|
||||
"": {
|
||||
"peering": "read"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Modes
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Mesh Gateways between Admin Partitions
|
||||
page_title: Enabling Service-to-service Traffic Across Admin Partitions
|
||||
description: >-
|
||||
Mesh gateways are specialized proxies that route data between services that cannot communicate directly with upstreams. Learn how to enable service-to-service traffic across admin partitions and review example configuration entries.
|
||||
---
|
||||
|
||||
# Mesh Gateways between Admin Partitions
|
||||
# Enabling Service-to-service Traffic Across Admin Partitions
|
||||
|
||||
-> **Consul Enterprise 1.11.0+:** Admin partitions are supported in Consul Enterprise versions 1.11.0 and newer.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Mesh Gateways between Peered Clusters
|
||||
page_title: Enabling Service-to-service Traffic Across Peered Clusters
|
||||
description: >-
|
||||
Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable service-to-service traffic across clusters in different datacenters or admin partitions that have an established peering connection.
|
||||
---
|
||||
|
||||
# Mesh Gateways between Peered Clusters
|
||||
# Enabling Service-to-service Traffic Across Peered Clusters
|
||||
|
||||
Mesh gateways are required for you to route service mesh traffic between peered Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible.
|
||||
|
||||
|
|
@ -47,7 +47,11 @@ Alternatively, you can also use the CLI to spin up and register a gateway in Con
|
|||
|
||||
### ACL configuration
|
||||
|
||||
- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services.
|
||||
If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition.
|
||||
These permissions authorize the token to route communications for other Consul service mesh services.
|
||||
|
||||
You must also grant `mesh:write` to mesh gateways routing peering traffic in the data plane.
|
||||
This permission allows a leaf certificate to be issued for mesh gateways to terminate TLS sessions for HTTP requests.
|
||||
|
||||
### Modes
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Mesh Gateways between WAN-Federated Datacenters
|
||||
page_title: Enabling Service-to-service Traffic Across WAN Federated Datacenters
|
||||
description: >-
|
||||
Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable service-to-service traffic across wan-federated datacenters and review example configuration entries.
|
||||
---
|
||||
|
||||
# Mesh Gateways between WAN-Federated Datacenters
|
||||
# Enabling Service-to-service Traffic Across WAN Federated Datacenters
|
||||
|
||||
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Mesh Gateways for WAN Federation Control Plane Traffic
|
||||
page_title: Enabling WAN Federation Control Plane Traffic
|
||||
description: >-
|
||||
You can use mesh gateways to simplify the networking requirements for WAN federated Consul datacenters. Mesh gateways reduce cross-datacenter connection paths, ports, and communication protocols.
|
||||
---
|
||||
|
||||
# Mesh Gateways for WAN Federation Control Plane Traffic
|
||||
# Enabling WAN Federation Control Plane Traffic
|
||||
|
||||
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and higher
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ The following table provides an overview of the resources you can use to create
|
|||
| `key`<br/>`key_prefix` | Controls access to key/value store operations in the [KV API](/api-docs/kv). <br/>Can also use the `list` access level when setting the policy disposition. <br/>Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul). <br/>See [Key/Value Rules](#key-value-rules) for details. | Yes |
|
||||
| `keyring` | Controls access to keyring operations in the [Keyring API](/api-docs/operator/keyring). <br/>See [Keyring Rules](#keyring-rules) for details. | No |
|
||||
| `mesh` | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No |
|
||||
| `peering` | Controls access to cluster peerings in the [Cluster Peering API](/api-docs/peering). For more details, refer to [Peering Rules](#peering-rules). | No |
|
||||
| `peering` | Controls access to cluster peerings in the [Cluster Peering API](/api-docs/peering). For more details, refer to [Peering Rules](#peering-rules). | No |
|
||||
| `namespace`<br/>`namespace_prefix` | <EnterpriseAlert inline /> Controls access to one or more namespaces. <br/>See [Namespace Rules](#namespace-rules) for details. | Yes |
|
||||
| `node`<br/>`node_prefix` | Controls access to node-level operations in the [Catalog API](/api-docs/catalog), [Health API](/api-docs/health), [Prepared Query API](/api-docs/query), [Network Coordinate API](/api-docs/coordinate), and [Agent API](/api-docs/agent) <br/>See [Node Rules](#node-rules) for details. | Yes |
|
||||
| `operator` | Controls access to cluster-level operations available in the [Operator API](/api-docs/operator) excluding keyring API endpoints. <br/>See [Operator Rules](#operator-rules) for details. | No |
|
||||
|
|
@ -589,6 +589,20 @@ These actions may required an ACL token to complete. Use the following methods t
|
|||
Refer to the [services](/docs/discovery/services) and [checks](/docs/discovery/checks) documentation for examples.
|
||||
Tokens may also be passed to the [HTTP API](/api-docs) for operations that require them.
|
||||
|
||||
### Reading Imported Nodes
|
||||
|
||||
Nodes rules affect read access to nodes with services exported by [`exported-services` configuration entries](/docs/connect/config-entries/exported-services#reading-services), including nodes imported from [cluster peerings](/docs/connect/cluster-peering) or [admin partitions](/docs/enterprise/admin-partitions) (Enterprise-only).
|
||||
Read access to all imported nodes is granted when either of the following rule sets are attached to a token:
|
||||
- `service:write` is granted to any service.
|
||||
- `node:read` is granted to all nodes.
|
||||
|
||||
For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace.
|
||||
|
||||
You may need similarly scoped [Service Rules](#reading-imported-services) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`).
|
||||
These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities).
|
||||
|
||||
Refer to [Reading Services](/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint.
|
||||
|
||||
## Operator Rules
|
||||
|
||||
The `operator` resource controls access to cluster-level operations in the
|
||||
|
|
@ -814,6 +828,22 @@ In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured wit
|
|||
[`enable_local_script_checks`](/docs/agent/config/config-files#enable_local_script_checks)
|
||||
set to `true` in order to enable script checks.
|
||||
|
||||
### Reading Imported Services
|
||||
|
||||
Service rules affect read access to services exported by [`exported-services` configuration entries](/docs/connect/config-entries/exported-services#reading-services), including services exported between [cluster peerings](/docs/connect/cluster-peering) or [admin partitions](/docs/enterprise/admin-partitions) (Enterprise-only).
|
||||
Read access to all imported services is granted when either of the following rule sets are attached to a token:
|
||||
- `service:write` is granted to any service.
|
||||
- `service:read` is granted to all services.
|
||||
|
||||
For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace.
|
||||
|
||||
You may need similarly scoped [Node Rules](#reading-imported-nodes) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`).
|
||||
These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities).
|
||||
|
||||
Refer to [Reading Services](/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint.
|
||||
|
||||
### Intentions
|
||||
|
||||
Service rules are also used to grant read or write access to intentions. The
|
||||
following policy provides read-write access to the "app" service, and explicitly
|
||||
grants `intentions:read` access to view intentions associated with the "app" service.
|
||||
|
|
|
|||
Loading…
Reference in New Issue