Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Multi-datacenter

Consul Cluster Peering

Connect independent Consul clusters with cluster peering: generate and establish peering tokens, export services, write intentions for peers and compare with WAN federation.

WAN federation joins datacenters into one tightly coupled system with a primary datacenter, shared ACLs and unique names. That is too much when two teams, companies or environments want to share only a few services. Cluster peering (introduced in Consul 1.13) connects two independent clusters. Each keeps its own ACLs, configuration and administrators, and they choose which services to share.

The product cannot run on this site. Commands and entries are read-only; the runnable examples are stand-in models.

Federation versus peering

WAN federation Cluster peering
Relationship Datacenters form one system Independent clusters, loosely linked
Primary datacenter Required None
ACLs, config entries Replicated from the primary Separate on each side
Names Datacenter names must be unique across the federation Names only need to be unique per peer relationship
Sharing Everything is reachable (subject to ACLs and intentions) Only exported services are visible
Typical use One organization, several regions Teams, business units, partners, mergers

Peering is also the better fit when two clusters have overlapping IP ranges or different security owners, because traffic flows through mesh gateways and the clusters never join a shared gossip pool.

The peering workflow

Assume cluster-01 in a "dialer" role wants to consume services from cluster-02. The exchange of a one-time secret is the key step.

On the acceptor (the cluster that creates the token):

Terminal
consul peering generate-token -name cluster-01

The command prints a long base64 token. It encodes the acceptor's server addresses, a CA certificate and a secret. Move it to the other side through a secure channel.

On the dialer:

Terminal
consul peering establish -name cluster-02 -peering-token "<token>"

The local name of a peer is chosen by each side, so cluster-01 calls its peer cluster-02 and vice versa, and they need not match. Check the result:

Terminal
consul peering list
consul peering read -name cluster-02

The state moves from PENDING to ESTABLISHING to ACTIVE. Peering needs ACL permission peering = "write" (operator-level), and the servers need peering { enabled = true } (the default in current releases). Peering also requires service mesh to be enabled. A token is single-use for establishing; if it leaks before use, delete the peering and generate a new token.

The control connection between the clusters' servers can go directly or through mesh gateways. Set PeerThroughMeshGateways = true in the mesh config entry when the servers cannot reach each other:

HCL
Kind = "mesh"

Peering {
  PeerThroughMeshGateways = true
}

Exporting services

Peering alone shares nothing. The cluster that provides a service must list it in an exported-services config entry:

HCL
Kind = "exported-services"
Name = "default"

Services = [
  {
    Name = "payments"
    Consumers = [
      { Peer = "cluster-01" }
    ]
  }
]

Write it with consul config write exported.hcl on the exporting cluster. Consumers are named by the peer name as the exporter knows it. After exporting, the dialer sees payments in its imported services. The HTTP API reads them with ?peer=cluster-02 on the catalog and health endpoints.

Calling a peered service

From inside the mesh, add the peer to an upstream:

HCL
upstreams = [
  {
    destination_name = "payments"
    destination_peer = "cluster-02"
    local_bind_port  = 9191
  }
]

The sidecar sends the request through the local mesh gateway to the remote cluster's gateway and on to a healthy payments sidecar there. The app still calls localhost:9191.

For DNS, the virtual name for a peered service includes the peer (payments.virtual.cluster-02.consul) when transparent proxy and virtual IPs are in use. Mesh upstreams are the more common route.

Python Stand-in: which exported services can a peer see?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Intentions across peers

Each cluster controls access with its own intentions. The exporting cluster names the remote peer in the source:

HCL
Kind = "service-intentions"
Name = "payments"

Sources = [
  {
    Name   = "checkout"
    Peer   = "cluster-01"
    Action = "allow"
  }
]

Without a matching allow (and with default deny), calls from the peer are refused. Wildcards behave as before, so a wildcard source applies only within the local cluster unless a Peer is stated. Exporting a service is the first gate; intentions are the second.

Python Stand-in: export gate plus intention gate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Operating peerings

  • Rotate or revoke: consul peering delete -name cluster-02 removes the relationship and imported data; the other side's peering goes to a terminated state.
  • Failover: a service-resolver can fail over to a peer with Failover = { "*" = { Targets = [{ Peer = "cluster-02" }] } }, so a service can fall back to the other cluster's copy.
  • Security: peering traffic is mTLS between the two clusters' CAs, established by the token exchange. Treat the token like a password until used.
  • Limits: each cluster can have many peers, but an imported service is read-only on the importing side; you cannot register services into the peer.
  • Monitoring: watch the peering status and consul.peering.* telemetry for health.

Choosing between them

Use WAN federation when one team owns all datacenters and wants shared ACLs and configuration. Use cluster peering when ownership differs, when you want a minimal blast radius, or when clusters are federated across clouds and partners. They can be combined: a federation of datacenters in one organization peered with another organization's cluster.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does cluster peering not require?

    Peering connects independent clusters; there is no primary, and ACLs are not shared.
  2. 2. Which command creates the secret the other cluster uses to peer?

    generate-token on the accepting cluster prints a token that the dialer passes to consul peering establish.
  3. 3. After peering is established, what does the importing cluster see?

    Exports are explicit, so nothing is shared by default.
  4. 4. How does an upstream reach a peered service?

    Set destination_peer along with destination_name; the sidecar handles the rest.
  5. 5. Which is a good reason to prefer peering over federation?

    Peering keeps clusters independent and shares only what is exported.

Summary

  • Peering links independent clusters with a token exchange (generate-token, establish); no primary datacenter or shared ACLs.
  • Services must be exported with exported-services, and each side's intentions still decide access (Peer in sources).
  • Upstreams use destination_peer; resolvers can fail over to a peer.
  • Prefer federation inside one organization and peering across ownership boundaries.

Next: Raft, Quorum and Autopilot