Cluster Peering - HTTP API

The functionality described here is available only in Consul version 1.13.0 and later.

Generate a Peering Token

This endpoint generates a peering token.

Method	Path	Produces
`POST`	`/peering/token`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`peering:write`

JSON Request Body Schema

PeerName (string: <required>) - The name assigned to the peer cluster. The PeerName is used to reference the peer cluster in service discovery queries and configuration entries such as service-intentions. This field must be a valid DNS hostname label.

Partition (string: "") - Enterprise The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

ServerExternalAddresses ([]string: <optional>) - The addresses for the cluster that generates the peering token. Addresses take the form {host or IP}:port. You can specify one or more load balancers or external IPs that route external traffic to this cluster's Consul servers.
Meta (map<string|string>: <optional>) - Specifies KV metadata to associate with the peering. This parameter is not required and does not directly impact the cluster peering process.

Sample Payload

{
  "PeerName": "cluster-02",
  "Meta": {
    "env": "production"
  }
}

Sample Request

$ curl --request POST \
   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/peering/token

Sample Response

{
    "PeeringToken": "eyJDQSI6bnVsbCwiU2V..."
}

Establish a Peering Connection

This endpoint establishes a peering connection with a given peering token.

Method	Path	Produces
`POST`	`/peering/establish`	`application/json`

This endpoint returns no data. Success or failure is indicated by the status code returned.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`peering:write`

JSON Request Body Schema

PeerName (string: <required>) - The name assigned to the peer cluster. The PeerName is used to reference the peer cluster in service discovery queries and configuration entries such as service-intentions. This field must be a valid DNS hostname label.

Partition (string: "") - Enterprise The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

PeeringToken (string: <required>) - The peering token fetched from the peer cluster.
Meta (map<string|string>: <optional>) - Specifies KV metadata to associate with the peering. This parameter is not required and does not directly impact the cluster peering process.

Sample Payload

{
  "PeerName": "cluster-01",
  "PeeringToken": "eyJDQSI6bnVsbCwiU2V...",
  "Meta": {
    "env": "production"
  }
}

Sample Request

$ curl --request POST \
   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/peering/establish

Sample Response

{}

Read a Peering Connection

This endpoint returns information about a peering connection for the specified peer name.

Method	Path	Produces
`GET`	`/peering/:name`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`consistent`	`none`	`peering:read`

Path Parameters

name (string: <required>) - Specifies the peering to read.

Query Parameters

partition (string: "") Enterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/peering/cluster-02

Sample Response

{
    "ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12",
    "Name": "cluster-02",
    "State": "INITIAL",
    "PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05",
    "PeerServerName": "server.dc1.consul",
    "PeerServerAddresses": [
        "10.0.0.1:8300"
    ],
    "StreamStatus": {
        "ImportedServices": [
                  "db",
            ],
        "ExportedServices": [
              "backend",
              "frontend",
              "web"
        ],
        "LastHeartbeat": "2023-12-13T06:31:28.227392Z",
        "LastReceive": "2023-12-13T06:31:28.227392Z",
        "LastSend": "2023-12-05T11:02:57.528676Z"
    },
    "CreateIndex": 89,
    "ModifyIndex": 89,
    "Remote": {
        "Partition": "",
        "Datacenter": "east"
    }
}

Delete a Peering Connection

Call this endpoint to delete a peering connection. Consul deletes all data imported from the peer in the background. The peering connection is removed after all associated data has been deleted. Operators can still read the peering connections while the data is being removed. A DeletedAt field will be populated with the timestamp of when the peering was marked for deletion.

Method	Path	Produces
`DELETE`	`/peering/:name`	N/A

This endpoint returns no data. Success or failure is indicated by the status code returned.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`peering:write`

Path Parameters

name (string: <required>) - Specifies the name of the peering to delete.

Query Parameters

partition (string: "") Enterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request DELETE \
   --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/peering/cluster-02

Sample Read Output After Deletion Prior to Removal

{
    "ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12",
    "Name": "cluster-02",
    "State": "TERMINATED",
    "PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05",
    "PeerServerName": "server.dc1.consul",
    "PeerServerAddresses": [
        "10.0.0.1:8300"
    ],
    "DeletedAt": "2022-12-14T23:00:00Z",
    "CreateIndex": 89,
    "ModifyIndex": 89
}

List all Peerings

This endpoint lists all the peerings.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

Method	Path	Produces
`GET`	`/peerings`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`consistent`	`background refresh`	`peering:read`

Query Parameters

partition (string: "") Enterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
   http://127.0.0.1:8500/v1/peerings

Sample Response

[
    {
        "ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12",
        "Name": "cluster-02",
        "State": "ACTIVE",
        "Partition": "default",
        "PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05",
        "PeerServerName": "server.dc1.consul",
        "PeerServerAddresses": [
            "10.0.0.1:8300"
        ],
        "StreamStatus": {
            "ImportedServices": [
                  "db",
            ],
            "ExportedServices": [
                  "backend",
                  "frontend",
                  "web"
            ],
            "LastHeartbeat": "2023-12-13T06:31:28.227392Z",
            "LastReceive": "2023-12-13T06:31:28.227392Z",
            "LastSend": "2023-12-05T11:02:57.528676Z"
        },
        "CreateIndex": 89,
        "ModifyIndex": 89,
        "Remote": {
            "Partition": "",
            "Datacenter": "east"
        }
    },
    {
        "ID": "1460ada9-26d2-f30d-3359-2968aa7dc47d",
        "Name": "cluster-03",
        "State": "INITIAL",
        "Partition": "default",
        "Meta": {
            "env": "production"
        },
        "StreamStatus": {
            "ImportedServices": null,
            "ExportedServices": [
                  "backend",
                  "frontend",
            ],
            "LastHeartbeat": "2023-12-13T06:31:28.227392Z",
            "LastReceive": "2023-12-13T06:31:28.227392Z",
            "LastSend": "2023-12-05T11:02:57.528676Z"
        },
        "CreateIndex": 109,
        "ModifyIndex": 119,
        "Remote": {
            "Partition": "",
            "Datacenter": "east"
        }
    }
]