@ -105,10 +105,8 @@ In the following diagram, the servers in each data center participate in a WAN g
</Tab>
</Tabs>
### Cluster peering (beta)
### Cluster peering
You can create peering connections between two or more independent clusters so that services deployed to different datacenters or admin partitions can communicate. An [admin partition](/docs/enterprise/admin-partitions) is a feature in Consul Enterprise that enables you to define isolated network regions that use the same Consul servers. In the cluster peering model, you create a token in one of the datacenters or partitions and configure another datacenter or partition to present the token to establish the connection.
-> **Cluster peering is currently in beta:** Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support.
Refer to [What is Cluster Peering?](/docs/connect/cluster-peering) for additional information.
Refer to [What is Cluster Peering?](/docs/connect/cluster-peering) for additional information.
~> **Cluster peering is currently in beta:** Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support.<br /><br />Cluster peering is not currently available in the HCP Consul offering.
A peering token enables cluster peering between different datacenters. Once you generate a peering token, you can use it to establish a connection between clusters. Then you can export services and create intentions so that peered clusters can call those services.
## Create a peering connection
Cluster peering is not enabled by default on Consul servers. To peer clusters, you must first configure all Consul servers so that `peering` is `enabled` and the gRPC port(8502) accepts traffic from the peering cluster (e.g., `client_addr="0.0.0.0"`). For additional information, refer to [Configuration Files](/docs/agent/config/config-files).
Cluster peering is enabled by default on Consul servers as of v1.14. For additional information, including options to disable cluster peering, refer to [Configuration Files](/docs/agent/config/config-files).
After enabling peering for all Consul servers, complete the following steps in order:
The process to create a peering connection is a sequence with multiple steps:
1. Create a peering token
1. Establish a connection between clusters
1. Export services between clusters
1. Authorize services for peers
You can generate peering tokens and initiate connections on any available agent using either the API or the Consul UI. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect.
You can generate peering tokens and initiate connections on any available agent using either the API, CLI, or the Consul UI. If you use the API or CLI, we recommend performing these operations through a client agent in the partition you want to connect.
The UI does not currently support exporting services between clusters or authorizing services for peers.
~> **Cluster peering is currently in beta**: Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. <br/><br/>Cluster peering is not currently available in the HCP Consul offering.
You can create peering connections between two or more independent clusters so that services deployed to different partitions or datacenters can communicate.
## Overview
@ -43,23 +41,11 @@ Regardless of whether you connect your clusters through WAN federation or cluste
| Forwards service requests for service discovery | ✅ | ❌ |
| Shares key/value stores | ✅ | ❌ |
## Beta release features and constraints
The cluster peering beta release includes the following features and functionality:
- **Consul v1.14 beta only**: Dynamic traffic control with a service resolver config entry can target failover and redirects to service instances in a peered cluster.
- Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering.
- Mesh gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers).
- You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI.
- You can configure [transparent proxies](/docs/connect/transparent-proxy) for peered services.
- You can use the [`peering` rule for ACL enforcement](/docs/security/acl/acl-rules#peering) of peering APIs.
## Important Cluster Peering Constraints
Not all features and functionality are available in the beta release. In particular, consider the following technical constraints:
Consider the following technical constraints:
- Mesh gateways for _server to server traffic_ are not available.
- Services with node, instance, and check definitions totaling more than 50MB cannot be exported to a peer.
- The `service-splitter` and `service-router` configuration entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. Refer to [L7 traffic management between peers](/docs/connect/cluster-peering/create-manage-peering#L7-traffic) for more information.
- Two admin partitions in the same datacenter cannot be peered. Use [`exported-services`](/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) directly.
- The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions).
- Accessing key/value stores across peers is not supported.
- Because non-Enterprise Consul instances are restricted to the `default` namespace, Consul Enterprise instances cannot export services from outside of the `default` namespace to non-Enterprise peers.
- Cross-cluster mesh gateways are supported in `remote` mode only.
~> **Cluster peering is currently in beta:** Functionality associated
with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in
beta may have performance issues, scaling issues, and limited support.<br/><br/>Cluster peering is not currently available in the HCP Consul offering.
To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions (CRDs) for each side of the peering.
The following CRDs are used to create and manage a peering connection:
@ -26,9 +22,9 @@ As of Consul v1.14, you can also [implement service failovers and redirects to c
You must implement the following requirements to create and use cluster peering connections with Kubernetes:
- Consul v1.13.1 or later
- Consul v1.14.0 or later
- At least two Kubernetes clusters
- The installation must be running on Consul on Kubernetes version 0.47.1 or later
- The installation must be running on Consul on Kubernetes version 1.0.0 or later
### Prepare for installation
@ -53,7 +49,7 @@ Complete the following procedure after you have provisioned a Kubernetes cluster
```yaml
global:
name: consul
image: "hashicorp/consul:1.13.1"
image: "hashicorp/consul:1.14.0"
peering:
enabled: true
connectInject:
@ -88,7 +84,7 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu
~> **Cluster peering is currently in beta**: Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support.
Mesh gateways are required for you to route service mesh traffic between different Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible.
Unlike mesh gateways for datacenters and partitions, mesh gateways between peers terminate mTLS sessions to decrypt data to HTTP services and then re-encrypt traffic to send to services. Data must be decrypted in order to evaluate and apply dynamic routing rules at the destination cluster, which reduces coupling between peers.
Dan Stough
2 years ago
committed by