Establish cluster peering connections

This page describes how to establish cluster peering connections. When you create and establish cluster peering connections with the dedicated UI workflow, information about the connections become visible in the HCP platform.

Introduction

In traditional self-managed deployments, the process to establish a cluster peering connection between clusters requires access to the Consul CLI to create and pass peering tokens to other clusters.

You can use the HCP UI to peer HCP Consul Dedicated clusters in the same HCP project.

The overall process for establishing a cluster peering connection consists of the following steps:

1. Create a cluster peering connection
2. Check peering connection status
3. Export services between clusters

After you establish a cluster peering connection, you can use the UI to view the connection's status, a list of exported services, and available imported services. You can also secure cluster access using the IP allowlist.

Requirements

• Consul v1.14.2 or later
• Two or more clusters with compatible cluster tiers

Create a cluster peering connection

1. From the Consul overview, click Cluster peering.
2. Click Create cluster peering connection.
3. Use the dropdown menus to select a cluster and an admin partition to use for cluster peering.
4. Repeat the process by selecting the cluster ID and admin partition of the desired peer.
5. Click Create.

If the cluster you select is a publicly available self-managed Community or Enterprise cluster, you have the option to turn on Include server address and enter that cluster's public IP. For more information about using public IPs, refer to cluster peering topologies.

Check peering connection status

After you create the cluster peering connection, it becomes visible. Wait for the status of your cluster peering connection to change to Active.

Export services between clusters

After you create a cluster peering connection and its status is Active, you can export services to make them available to peers. The HCP UI does not support exporting services. You must define the services you want to export and the peers you want to give access to, then write the configuration to your Consul deployment.

If the peer you want to export services from is a HCP Consul Dedicated cluster, follow the steps to export services with a configuration entry.

For more information about the fields you can configure when exporting services, refer to exported services configuration entry in the Consul documentation.

Authorize services with intentions and ACLs

HCP uses a global "deny all" intention by default in order to keep service-to-service communication secure. After you export services between peers, you must configure service intentions on each cluster that authorize services to communicate with each other.

If the peer you want to set service intentions on is a HCP Consul Dedicated cluster, follow the steps to create service intentions with a configuration entry.

For more information about the fields you can configure when defining service intentions, refer to service intentions configuration entry in the Consul documentation.

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, the permissions apply to all imported services in the service's partition. These permissions are satisfied when using a service identity.

Refer to Reading servers in the exported-services configuration entry documentation for example rules.

For additional information about how to configure and use ACLs, refer to ACLs system overview.

Next steps

After establishing a cluster peering connection, you can further secure your deployment by configuring an IP allowlist to limit cluster access. HCP's cluster peering allowlist supports three IP address ranges on the allowlist at one time.