diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 166770bbaf48..fb761e8676f7 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -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. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index f43a65007c8b..3fbd30b7166c 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -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 diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index ed08cf39b4ff..283f9f56d934 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -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. + + + +```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" + } + } +} + +``` + + + - + 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. + + + +```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" + } + } + } + } + } + } +} +``` + + + - -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. + + +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. -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. + + +```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" + } + } + } + } + } + } +} +``` + + + + + For additional information, refer to [Health HTTP Endpoint](/api-docs/health). diff --git a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx index 4b6f05d87031..efb0dd2495f4 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx @@ -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. + + + +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. + + + +```hcl +peering = "read" +``` + +```json +{ + "peering": "read" +} +``` + + + + + + + +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. + + + +```hcl +partition_prefix "" { + peering = "read" +} +``` + +```json +{ + "partition_prefix": { + "": { + "peering": "read" + } + } +} +``` + + + + + ### Modes diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx index e46afe0d2dd4..409705d6b81a 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx @@ -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. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx index 207c8c0e7246..4adeecaf1ad8 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -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 diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx index ed566f320783..32370c8e34f1 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx @@ -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. diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 3898e04889ee..21c68d23ab7b 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -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 diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index b24ca71e2fbf..273d134ff9ef 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -22,7 +22,7 @@ The following table provides an overview of the resources you can use to create | `key`
`key_prefix`   | Controls access to key/value store operations in the [KV API](/api-docs/kv).
Can also use the `list` access level when setting the policy disposition.
Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul).
See [Key/Value Rules](#key-value-rules) for details. | Yes | | `keyring`       | Controls access to keyring operations in the [Keyring API](/api-docs/operator/keyring).
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`
`namespace_prefix` | Controls access to one or more namespaces.
See [Namespace Rules](#namespace-rules) for details. | Yes | | `node`
`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)
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.
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.