Skip to content

Commit

Permalink
Overview updates
Browse files Browse the repository at this point in the history
  • Loading branch information
boruszak committed Feb 13, 2023
1 parent 7d258eb commit af8c762
Show file tree
Hide file tree
Showing 3 changed files with 35 additions and 14 deletions.
33 changes: 27 additions & 6 deletions website/content/docs/connect/cluster-peering/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,15 @@ description: >-

# Cluster Peering Overview

This topic provides an overview of cluster peering, which creates a connection between two or more independent clusters so that services deployed to different partitions or datacenters can communicate.
This topic provides an overview of cluster peering, which is a process that connects two or more independent clusters so that services deployed to different partitions or datacenters can communicate.

Cluster peering enables connections between different clouds or runtime environments when general interconnectivity between all services in all clusters is not feasible. The process to establish a cluster peering connection consists of the following steps:
Cluster peering is enabled in Consul by default. Establishing a cluster peering connection is a process that consists of the following steps:

1. Create a peering token in one cluster.
1. Use the peering token to establish peering with a second cluster.
1. Export services between clusters.
1. Create intentions to authorize services for peers.

The `exported-services` configuration entry enables services registered in two different [admin partitions](/docs/enterprise/admin-partitions) running in the same datacenter to communicate. Cluster peering combines an `exported-services` configuration entry with a shared peering token and a mesh gateway, enabling services to communicate securely with upstreams registered in different datacenters. Although deployments require an Enterprise license to use multiple admin partitions in a single datacenter, cluster peering is not restricted to Enterprise users because every datacenter automatically includes a `default` partition.

You can generate peering tokens and initiate connections on any available agent using either the API, CLI, or the Consul UI. The UI does not support exporting services between clusters or authorizing services for peers. If you use the HTTP API, refer to the [`/peering` endpoint reference](/consul/api-docs/peering). If you use the CLI, refer to the [`peering` command reference](/consul/commands/peering).

You can find specific cluster peering configuration and usage information in the following topics:
Expand All @@ -31,7 +29,30 @@ You can find specific cluster peering configuration and usage information in the

> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](/consul/tutorials/developer-mesh/cluster-peering-aws).
## Cluster peering and WAN federation comparison
## Background

Consul supports cluster peering connections between _[admin partitions](/consul/docs/enterprise/admin-partitions) in different datacenters_. Deployments without an Enterprise license can still use cluster peering because every datacenter automatically includes a default partition. Meanwhile, _admin partitions in the same datacenter_ do not require cluster peering connections because you can export services between them without generating or exchanging a peering token.

The following diagram describes Consul's cluster peering architecture. The `default` partition in the first datacenter has a cluster peering connection with the `web` partition in the second datacenter.

![Diagram of cluster peering with admin partitions](/img/cluster-peering-diagram.png)

Cluster peering leverages several components of Consul's architecture to enforce secure communication between services:

- Peering token
- Mesh gateway
- Exported services
- Service intentions

A _peering token_ contains an embedded secret that you can share to securely establish communication between datacenters. Similar to the [gossip encryption key](/consul/docs/security/encryption#gossip-encryption) that is used to initiate LAN gossip when bootstrapping a datacenter, sharing this token between datacenters enables server agents to recognize authorized requests.

A _mesh gateway_ encrypts outgoing traffic, decrypts incoming traffic, and directs traffic to healthy services. Consul's service mesh features must be enabled in order to use mesh gateways. Unlike the peering token, which is shared between datacenters, mesh gateways support the specific admin partitions they are deployed on.

An _exported service_ is a service with specific upstreams that are explicitly defined in an `exported-services` configuration entry. Exporting services enables services registered in two different [admin partitions](/docs/enterprise/admin-partitions) to communicate.

A _service intention_ establishes secure service-to-service communication in a service mesh. Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request.

### Cluster peering and WAN federation comparison

WAN federation and cluster peering are different ways to connect services through mesh gateways so that they can communicate across datacenters. WAN federation connects multiple datacenters to make them function as if they were a single cluster, while cluster peering treats each datacenter as a separate cluster. As a result, WAN federation requires a primary datacenter to maintain and replicate global states such as ACLs and configuration entries, but cluster peering does not.

Expand All @@ -51,7 +72,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste
| Shares key/value stores | ✅ | ❌ |
| Can replicate ACL tokens, policies, and roles | ✅ | ❌ |

## Technical Constraints
## Technical constraints

Consider the following technical constraints:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ description: >-
Generate a peering token to establish communication, export services, and authorize requests for cluster peering connections. Learn how to create, list, read, check, and delete peering connections.
---

# Establish Cluster Peering Connections
# Establish cluster peering connections

A peering token enables cluster peering between different datacenters. After 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.
This page details the process for establishing a cluster peering connection between services with Consul. Establishing a cluster peering connection consists of the following steps:

The process to create a peering connection is a sequence with multiple steps:
1. Create a peering token in one cluster.
1. Use the peering token to establish peering with a second cluster.
1. Export services between clusters.
1. Create intentions to authorize services for peers.

1. Create a peering token
1. Establish a connection between clusters
1. Export services between clusters
1. Authorize services for peers
Cluster peering cannot be establish until all four steps are complete.

## Requirements

Expand Down Expand Up @@ -135,7 +135,7 @@ If you need to re-establish a connection, you must generate a new peering token.

### Export services between clusters

After you establish a connection between the clusters, you need to create a configuration entry that defines the services that are available for other clusters. Consul uses this configuration entry to advertise service information and support service mesh connections across clusters.
After you establish a connection between the clusters, you need to create an `exported-services` configuration entry that defines the services that are available for other clusters. Consul uses this configuration entry to advertise service information and support service mesh connections across clusters.

First, create a configuration entry and specify the `Kind` as `"exported-services"`.

Expand Down
Binary file added website/public/img/cluster-peering-diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit af8c762

Please sign in to comment.