Establish cluster peering connections on HCP Consul

This page describes how to establish cluster peering connections on HCP Consul. When you use HCP Consul to create and establish cluster peering connections, information about the connections become visible in HCP Consul Central. Refer to HCP Consul Central overview for more information.

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. Establishing cluster peering connections through HCP Consul simplifies this process by using HCP Consul Central to automate this part of the cluster peering workflow.

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

1. Create a cluster peering connection using HCP Consul Central
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

In addition, if you want to establish cluster peering connections between HCP-managed and self-managed clusters, or if you want to use HCP Consul Central to create and manage cluster peering connections between two self-managed clusters, you must link self-managed clusters to HCP before you begin the cluster peering process.

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 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 in HCP Consul Central. Wait for the status of your cluster peering connection to change to Active. It can take 5 to 10 minutes for the cluster peering connection process to complete.

For information about what each status means, refer to connection status.

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. HCP Consul Central 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. This step mirrors the process for establishing cluster peering connections without HCP Consul.

If the peer you want to export services from is a HashiCorp-managed cluster, or if you use self-managed Consul with VMs, follow the steps to export services with a configuration entry.

If you use Kubernetes for your self-managed cluster, follow the steps to export services with a CRD.

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 HashiCorp-managed cluster, or if you use self-managed Consul with VMs, follow the steps to create service intentions with a configuration entry.

If you use Kubernetes for your self-managed cluster, follow the steps to create service intentions with a CRD.

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 Consul's cluster peering allowlist supports three IP address ranges on the allowlist at one time.

You can also view active cluster peering connections with HCP Consul Central.