From 4fcfea8be26c06642e854eae7901b612f2091262 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 1 Aug 2022 10:30:36 -0500 Subject: [PATCH 01/27] Update "technical preview" to "beta" --- .../cluster-peering/create-manage-peering.mdx | 2 +- .../docs/connect/cluster-peering/index.mdx | 4 ++-- .../docs/connect/cluster-peering/k8s.mdx | 23 +++++++++---------- 3 files changed, 14 insertions(+), 15 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 72b872151d..689ae65368 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -7,7 +7,7 @@ description: >- # Create and Manage Peering Connections -~> **Cluster peering is currently in technical preview:** Functionality associated with cluster peering is subject to change. You should never use the technical preview release in secure environments or production scenarios. Features in technical preview may have performance issues, scaling issues, and limited support. +~> **Cluster peering is currently in beta:** Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. A peering token enables cluster peering between different datacenters. Once you generate a peering token, you can use it to establish a connection between clusters. Then you can export services and authorize other clusters to call those services. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 4601e19470..7393b448e8 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -7,7 +7,7 @@ description: >- # What is Cluster Peering? -~> **Cluster peering is currently in technical preview**: Functionality associated with cluster peering is subject to change. You should never use the technical preview release in secure environments or production scenarios. Features in technical preview may have performance issues, scaling issues, and limited support. +~> **Cluster peering is currently in beta**: Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. You can create peering connections between two or more independent clusters so that services deployed to different partitions or datacenters can communicate. @@ -39,7 +39,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste Not all features and functionality are available in the technical preview release. In particular, consider the following technical constraints: - Consul ACLs must be disabled or the ACL `default_policy` must be set to `allow`. -- Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. +- Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. - Services exported to peered clusters must be configured to use the TCP protcol (not HTTP, HTTP 2 and gRPC). - Support for dynamic routing such as splits, custom routes, or redirects is not available. - The `consul intention CLI` command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 529b583fbd..78ca8c2e98 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -7,10 +7,9 @@ description: >- # Cluster Peering on Kubernetes -~> **Cluster peering is currently in technical preview:** Functionality associated -with cluster peering is subject to change. You should never use the technical -preview release in secure environments or production scenarios. Features in -technical preview may have performance issues, scaling issues, and limited support. +~> **Cluster peering is currently in beta:** Functionality associated +with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in +beta may have performance issues, scaling issues, and limited support. To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions for each side of the peering. @@ -21,11 +20,11 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a ## Prerequisites -You must implement the following requirements to create and use cluster peering connections with Kubernetes: +You must implement the following requirements to create and use cluster peering connections with Kubernetes: - Consul 1.13 Alpha 2 or later -- At least two Kubernetes clusters -- The Kubernetes clusters must be running in a flat network -- The network must be running on Consul on Kubernetes v.0.45 or later +- At least two Kubernetes clusters +- The Kubernetes clusters must be running in a flat network +- The network must be running on Consul on Kubernetes v.0.45 or later ### Helm chart configuration @@ -40,7 +39,7 @@ To establish cluster peering through Kubernetes, deploy clusters with the follow enabled: true connectInject: enabled: true - controller: + controller: enabled: true meshGateway: enabled: true @@ -48,10 +47,10 @@ To establish cluster peering through Kubernetes, deploy clusters with the follow ``` - -Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. -```shell-session +Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. + +```shell-session $ export HELM_RELEASE_NAME=cluster-name ``` From aa53c3bcabc48d868a9a6c8122d153af6e341e25 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 1 Aug 2022 10:31:02 -0500 Subject: [PATCH 02/27] Nav correction --- website/data/docs-nav-data.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ae5624a0d9..15a87d7408 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -280,7 +280,7 @@ "title": "Cluster Peering", "routes": [ { - "title": "What is Cluster Peering", + "title": "What is Cluster Peering?", "path": "connect/cluster-peering" }, { From 6aaf6743965da8aa5f6778ea363c8a0d141c6c51 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 1 Aug 2022 10:43:38 -0500 Subject: [PATCH 03/27] Beta release constraints updated --- .../docs/connect/cluster-peering/index.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 7393b448e8..f943a2d935 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -31,20 +31,17 @@ Regardless of whether you connect your clusters through WAN federation or cluste | Connects clusters across datacenters | ✅ | ✅ | | Shares support queries and service endpoints | ✅ | ✅ | | Connects clusters owned by different operators | ❌ | ✅ | -| Functions without declaring primary datacenter | ❌ | ✅ | +| Functions without declaring primary datacenter | ❌ | ✅ | | Shares key/value stores | ✅ | ❌ | | Uses gossip protocol | ✅ | ❌ | -## Technical preview constraints -Not all features and functionality are available in the technical preview release. In particular, consider the following technical constraints: +## Beta release constraints +Not all features and functionality are available in the beta release. In particular, consider the following technical constraints: -- Consul ACLs must be disabled or the ACL `default_policy` must be set to `allow`. - Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. -- Services exported to peered clusters must be configured to use the TCP protcol (not HTTP, HTTP 2 and gRPC). -- Support for dynamic routing such as splits, custom routes, or redirects is not available. +- Dynamic routing features such as splits, custom routes, and redirects cannot target services in a peered cluster. +- Configuring service failover across peers is not supported for service mesh. +- Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - The `consul intention CLI` command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). -- [L7 permissions](/docs/connect/l7-traffic) are not supported. -- Configuring service failover across peers is not supported. - Accessing key/value stores across peers is not supported. -- Consul datacenters that are already federated stay federated. - Non-enterprise Consul instances cannot sync services with namespaces outside of the `default` namespace. From 3ada8ac95baf0f9c92aec646cb390ad0bac1d211 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 1 Aug 2022 14:28:50 -0500 Subject: [PATCH 04/27] Updated functionality + task instructions --- .../cluster-peering/create-manage-peering.mdx | 159 ++++++++++++++++-- .../docs/connect/cluster-peering/index.mdx | 9 +- .../docs/connect/cluster-peering/k8s.mdx | 30 ++-- 3 files changed, 168 insertions(+), 30 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 689ae65368..9438c6ec29 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -9,21 +9,25 @@ description: >- ~> **Cluster peering is currently in beta:** Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. -A peering token enables cluster peering between different datacenters. Once you generate a peering token, you can use it to establish a connection between clusters. Then you can export services and authorize other clusters to call those services. +A peering token enables cluster peering between different datacenters. Once 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. + +## Create a peering connection To peer clusters, you must complete the following steps in order: 1. Create a peering token 1. Establish a connection between clusters -1. Export service endpoints -1. Authorize connections between peers +1. Export services +1. Authorize services for peers -## Create a peering token +### Create a peering token -You can generate peering tokens and initiate connections using the Consul API on any available agent. However, we recommend performing these operations through a client agent in the partition you want to connect. +You can generate peering tokens and initiate connections on any available agent using either the Consul UI or the API. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. To begin the cluster peering process, generate a peering token in one of your clusters. The other cluster uses this token to establish the peering connection. + + In `cluster-01`, issue a request for a peering token using the [HTTP API](/api-docs/peering). ```shell-session @@ -44,21 +48,38 @@ Create a JSON file that contains the first cluster's name and the peering token. ``` + -## Establish a connection between clusters + -Next, use `peering_token.json` to establish a secure connection between the clusters. In the client agents of "cluster-02," establish the peering connection using the HTTP API. This endpoint does not generate an output unless there is an error. + + + +### Establish a connection between clusters + +Next, use the peering token to establish a secure connection between the clusters. + + + +In the client agents of "cluster-02," use `peering_token.json` to establish the peering connection. This endpoint does not generate an output unless there is an error. ```shell-session $ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish ``` When you connect server agents through cluster peering, they peer their default partitions. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/api-docs/peering). + -## Export service endpoints + + + + +### Export services 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. + + First, create a configuration entry and specify the `Kind` as `"exported-services"`. @@ -91,11 +112,19 @@ $ consul config write peering-config.hcl ``` Before you proceed, wait for the clusters to sync and make services available to their peers. You can issue an endpoint query to [check the peered cluster status](#check-peered-cluster-status). + -## Authorize connections from peers + + + + + +### Authorize services for peers Before you can call services from peered clusters, you must set service intentions that authorize those clusters to use specific services. Consul prevents services from being exported to unauthorized clusters. + + First, create a configuration entry and specify the `Kind` as `"service-intentions"`. Declare the service on "cluster-02" that can access the service in "cluster-01." The following example sets service intentions so that "frontend-service" can access "backend-service." @@ -122,24 +151,128 @@ Then, add the configuration entry to your cluster. ```shell-session $ consul config write peering-intentions.hcl ``` + -## Check peered cluster status + -To confirm that you peered your clusters, you can [query the `/health/service` endpoint](/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. + + + +## Manage peering connections + +### List all peering connections + +After you establish a peering connection, you can get a list of all active peering connections. + + + + +After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the info as a series of JSON objects: + +```shell-session +$ curl http://127.0.0.1:8500/v1/peerings + +[ + { + "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" + ], + "CreateIndex": 89, + "ModifyIndex": 89 + }, + { + "ID": "1460ada9-26d2-f30d-3359-2968aa7dc47d", + "Name": "cluster-03", + "State": "INITIAL", + "Partition": "default", + "Meta": { + "env": "production" + }, + "CreateIndex": 109, + "ModifyIndex": 119 + }, +] +``` + + + + + + + +### Read a peering connection + +You can get information about individual peering connections between clusters. + + + + +After you establish a peering connection, [query the `/peering/:name` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection info for "cluster-02" and returns the info as a JSON object: + +```shell-session +$ curl http://127.0.0.1:8500/v1/peering/cluster-02 + +{ + "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" + ], + "CreateIndex": 89, + "ModifyIndex": 89 +} +``` + + + + + + + +### Check peering connection health + +After you establish a peering connection, you can check the status of your peering connection to perform health checks. + + + +To confirm that the peering connection between your clusters remains healthy, [query the `/health/service` endpoint](/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. ```shell-session $ curl \ "http://127.0.0.1:8500/v1/health/service/?peer=cluster-01" ``` -A successful query will include service information in the output. +A successful query includes service information in the output. + -## Remove peering connections + + + + + +### Delete peering connections After you create a peering connection between clusters in different datacenters, you can disconnect the peered clusters. Deleting a peering connection stops data replication to the peer and deletes imported data, including services and CA certificates. + + In "cluster-01," request the deletion via the HTTP API. ```shell-session $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 ``` + + + + + + diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index f943a2d935..7eaa06fdc6 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -14,9 +14,10 @@ You can create peering connections between two or more independent clusters so t ## Overview Cluster peering allows Consul clusters in different datacenters to communicate with each other. The cluster peering process consists of the following steps: -1. Create a peering token to share with other clusters -1. Establish a connection between clusters -1. Make services available to other clusters +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 set up service mesh between clusters. For detailed instructions on setting up cluster peering with the Consul CLI, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). @@ -35,7 +36,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste | Shares key/value stores | ✅ | ❌ | | Uses gossip protocol | ✅ | ❌ | -## Beta release constraints +## Beta release features and constraints Not all features and functionality are available in the beta release. In particular, consider the following technical constraints: - Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 78ca8c2e98..c704c78761 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -21,10 +21,10 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a ## Prerequisites You must implement the following requirements to create and use cluster peering connections with Kubernetes: -- Consul 1.13 Alpha 2 or later +- Consul v1.13 or later - At least two Kubernetes clusters - The Kubernetes clusters must be running in a flat network -- The network must be running on Consul on Kubernetes v.0.45 or later +- The network must be running on Consul on Kubernetes v0.45 or later ### Helm chart configuration @@ -34,7 +34,7 @@ To establish cluster peering through Kubernetes, deploy clusters with the follow ```yaml global: - image: "hashicorp/consul:1.13.0-alpha2" + image: "hashicorp/consul:1.13.0" peering: enabled: true connectInject: @@ -58,7 +58,7 @@ $ export HELM_RELEASE_NAME=cluster-name $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --version "0.45.0" --values values.yaml ``` -## Create a peering connection +## Create a peering token To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. @@ -93,6 +93,8 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl get secret peering-token --output yaml > peering-token.yml ``` +## Establish a peering connection between clusters + 1. Apply the peering token to the second cluster. ```shell-session @@ -124,7 +126,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl apply --filename dialer.yml ``` -## Deploy and export cluster services +## Export services between clusters 1. For the service in "cluster-02" that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) to your service's pods. This service is referred to as "backend-service" in the following steps. @@ -158,6 +160,14 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a +1. Apply the service file and the `ExportedServices` resource for the second cluster. + + ```shell-session + $ kubectl apply --filename backend-service.yml --filename exportedsvc.yml + ``` + +## Authorize services for peers + 1. Create service intentions for the second cluster. @@ -179,16 +189,10 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a -1. Apply the service file, the `ExportedServices` resource, and the intentions to the second cluster. +1. Apply the intentions to the second cluster. ```shell-session - $ kubectl apply --filename backend-service.yml --filename exportedsvc.yml --filename intention.yml - ``` - -1. To confirm that you peered your clusters, in `cluster-01`, query the `/health` HTTP endpoint. - - ```shell-session - $ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02" + $ kubectl apply --filename intention.yml ``` 1. For the services in `cluster-01` that you want to access the "backend-service," add the following annotations to the service file. From 0d62ad8923e6f05d859fc1c1b3ff6c297304819c Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 1 Aug 2022 14:43:10 -0500 Subject: [PATCH 05/27] Proofing updates & adjustments --- .../cluster-peering/create-manage-peering.mdx | 13 ++++++++----- .../content/docs/connect/cluster-peering/index.mdx | 4 ++-- .../content/docs/connect/cluster-peering/k8s.mdx | 2 +- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 9438c6ec29..c0631f2dc3 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -17,7 +17,7 @@ To peer clusters, you must complete the following steps in order: 1. Create a peering token 1. Establish a connection between clusters -1. Export services +1. Export services between clusters 1. Authorize services for peers ### Create a peering token @@ -28,7 +28,7 @@ To begin the cluster peering process, generate a peering token in one of your cl -In `cluster-01`, issue a request for a peering token using the [HTTP API](/api-docs/peering). +In `cluster-01`, issue a request for a peering token. ```shell-session $ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token @@ -74,7 +74,8 @@ When you connect server agents through cluster peering, they peer their default -### Export services + +### 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. @@ -160,9 +161,11 @@ $ consul config write peering-intentions.hcl ## Manage peering connections +After you establish a peering connection, you can get a list of all active peering connections, read a specific peering connection's info, check peering connection health, and delete peering connections. + ### List all peering connections -After you establish a peering connection, you can get a list of all active peering connections. +You can list all active peering connections in a cluster. @@ -265,7 +268,7 @@ After you create a peering connection between clusters in different datacenters, -In "cluster-01," request the deletion via the HTTP API. +In "cluster-01," request the deletion through the [`/peering/` endpoint](api-docs/peering#delete-a-peering-connection). ```shell-session $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 7eaa06fdc6..a50dd26992 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -17,9 +17,9 @@ Cluster peering allows Consul clusters in different datacenters to communicate w 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 set up service mesh between clusters. +1. Create intentions to authorize services for peers. -For detailed instructions on setting up cluster peering with the Consul CLI, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). +For detailed instructions on setting up cluster peering, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). ### Differences between WAN federation and cluster peering diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index c704c78761..8d3c510f86 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -21,7 +21,7 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a ## Prerequisites You must implement the following requirements to create and use cluster peering connections with Kubernetes: -- Consul v1.13 or later +- Consul v1.13.0 or later - At least two Kubernetes clusters - The Kubernetes clusters must be running in a flat network - The network must be running on Consul on Kubernetes v0.45 or later From c798db392dae55d07fc442fef455af77d5851d46 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 14:26:20 -0500 Subject: [PATCH 06/27] Initial new features commit --- website/content/docs/connect/cluster-peering/index.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index a50dd26992..0b6ee7af0f 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -37,6 +37,13 @@ Regardless of whether you connect your clusters through WAN federation or cluste | Uses gossip protocol | ✅ | ❌ | ## Beta release features and constraints + +The cluster peering beta adds the following features and functions: + +- You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI. +- You can configure [transparent proxies](/docs/connect/transparent-proxy) for peered services. +- You can use the [`peering` rule for ACL enforcement](/docs/security/acl/acl-rules#peering) of peering APIs. + Not all features and functionality are available in the beta release. In particular, consider the following technical constraints: - Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. From 8f45d8347f25339d19748994d43cd6d17acf07b6 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 15:09:00 -0500 Subject: [PATCH 07/27] New "Mesh Gateways for Peered Clusters" page --- .../service-to-service-traffic-peers.mdx | 51 +++++++++++++++++++ website/data/docs-nav-data.json | 4 ++ 2 files changed, 55 insertions(+) create mode 100644 website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx new file mode 100644 index 0000000000..c3e789745a --- /dev/null +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -0,0 +1,51 @@ +--- +layout: docs +page_title: Service-to-service Traffic Across Peered Clusters +description: >- + This topic describes how to configure mesh gateways to route a service's data to upstreams + in clusters that have a peering connection. +--- + +# Service-to-service Traffic Across Peered Clusters + +~> **Cluster peering is currently in beta**: Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. + +Mesh gateways are required for you to route service mesh traffic between different Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible. + +Unlike mesh gateways for datacenters and partitions, mesh gateways for cluster peering decrypts data to HTTP services within the mTLS session. Data must be decrypted in order to apply dynamic routing rules configured in the destination cluster. + +## Prerequisites + +To configure mesh gateways for cluster peering, make sure your Consul environment meets the following requirements: + +- Consul version 1.13.0 or newer. +- A local Consul agent is required to manage mesh gateway configuration. +- [Enable Consul service mesh](/docs/agent/config/config-files#connect-parameters) in all clusters. +- Use [Envoy proxies](/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. + +## Configuration + +Configure the following settings to register and use the mesh gateway as a service in Consul. + +### Gateway registration + +- Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. +- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. + +Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/commands/connect/envoy#mesh-gateways). + +### Sidecar registration + +- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_peer` must be configured to enable cross-cluster traffic. The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace. + +### Service exporting + +- Configure the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services). + +### ACL configuration + +- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services. + +### Modes + +In the current release, modes are not configurable for mesh gateways that connect peered clusters. All proxies connected to the gateway behave in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 15a87d7408..523d39cdef 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -263,6 +263,10 @@ { "title": "Enabling Service-to-service Traffic Across Admin Partitions", "path": "connect/gateways/mesh-gateway/service-to-service-traffic-partitions" + }, + { + "title": "Enabling Service-to-service Traffic Across Peered Clusters", + "path": "connect/gateways/mesh-gateway/service-to-service-traffic-peers" } ] }, From 0e349ad6aa6adf49cca4aef2197cf8ca813b8fcc Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 15:17:09 -0500 Subject: [PATCH 08/27] New features/functions list --- website/content/docs/connect/cluster-peering/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 0b6ee7af0f..f4c5e23bfc 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -40,13 +40,14 @@ Regardless of whether you connect your clusters through WAN federation or cluste The cluster peering beta adds the following features and functions: +- Mesh Gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). - You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI. - You can configure [transparent proxies](/docs/connect/transparent-proxy) for peered services. - You can use the [`peering` rule for ACL enforcement](/docs/security/acl/acl-rules#peering) of peering APIs. Not all features and functionality are available in the beta release. In particular, consider the following technical constraints: -- Mesh gateways for _server to server traffic_ are not available. However, mesh gateways for _service to service traffic_ between clusters are available. +- Mesh gateways for _server to server traffic_ are not available. - Dynamic routing features such as splits, custom routes, and redirects cannot target services in a peered cluster. - Configuring service failover across peers is not supported for service mesh. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. From 6c5d4df59032df935022c493504c1759ca228631 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 16:01:22 -0500 Subject: [PATCH 09/27] Proofing edits --- .../mesh-gateway/service-to-service-traffic-peers.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx index c3e789745a..1de6e019a2 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -36,11 +36,14 @@ Alternatively, you can also use the CLI to spin up and register a gateway in Con ### Sidecar registration -- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_peer` must be configured to enable cross-cluster traffic. The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace. +- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. +- The service `proxy.upstreams.destination_name` is always required. +- The `proxy.upstreams.destination_peer` must be configured to enable cross-cluster traffic. +- The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace. -### Service exporting +### Service exports -- Configure the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services). +- Include the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services). ### ACL configuration @@ -48,4 +51,4 @@ Alternatively, you can also use the CLI to spin up and register a gateway in Con ### Modes -In the current release, modes are not configurable for mesh gateways that connect peered clusters. All proxies connected to the gateway behave in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). +In the current release, modes are not configurable for mesh gateways that connect peered clusters. By default, all proxies connected to the gateway behave in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). From 8d676619b3e604f9d651ffafb0a7c829424bef92 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 16:20:43 -0500 Subject: [PATCH 10/27] Proofing edits --- .../connect/cluster-peering/create-manage-peering.mdx | 6 +++--- website/content/docs/connect/cluster-peering/index.mdx | 4 ++-- website/content/docs/connect/cluster-peering/k8s.mdx | 10 +++++----- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index c0631f2dc3..cdea85512c 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -61,7 +61,7 @@ Next, use the peering token to establish a secure connection between the cluster -In the client agents of "cluster-02," use `peering_token.json` to establish the peering connection. This endpoint does not generate an output unless there is an error. +In one of the client agents in "cluster-02," use `peering_token.json` to establish the peering connection. This endpoint does not generate an output unless there is an error. ```shell-session $ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish @@ -243,7 +243,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 ### Check peering connection health -After you establish a peering connection, you can check the status of your peering connection to perform health checks. +You can check the status of your peering connection to perform health checks. @@ -264,7 +264,7 @@ A successful query includes service information in the output. ### Delete peering connections -After you create a peering connection between clusters in different datacenters, you can disconnect the peered clusters. Deleting a peering connection stops data replication to the peer and deletes imported data, including services and CA certificates. +You can disconnect the peered clusters by deleting their connection. Deleting a peering connection stops data replication to the peer and deletes imported data, including services and CA certificates. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index f4c5e23bfc..0b3bb56b0f 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -38,7 +38,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste ## Beta release features and constraints -The cluster peering beta adds the following features and functions: +The cluster peering beta adds the following features and functionality: - Mesh Gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). - You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI. @@ -51,6 +51,6 @@ Not all features and functionality are available in the beta release. In particu - Dynamic routing features such as splits, custom routes, and redirects cannot target services in a peered cluster. - Configuring service failover across peers is not supported for service mesh. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. -- The `consul intention CLI` command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). +- The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). - Accessing key/value stores across peers is not supported. - Non-enterprise Consul instances cannot sync services with namespaces outside of the `default` namespace. diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 8d3c510f86..3a43d0c034 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -11,9 +11,9 @@ description: >- with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. -To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions for each side of the peering. +To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create Custom Resource Definitions (CRDs) for each side of the peering. -The following Custom Resource Definitions (CRDs) are used to create and manage a peering connection: +The following CRDs are used to create and manage a peering connection: - `PeeringAcceptor`: Generates a peering token and accepts an incoming peering connection. - `PeeringDialer`: Uses a peering token to make an outbound peering connection with the cluster that generated the token. @@ -21,10 +21,10 @@ The following Custom Resource Definitions (CRDs) are used to create and manage a ## Prerequisites You must implement the following requirements to create and use cluster peering connections with Kubernetes: -- Consul v1.13.0 or later +- Consul version 1.13.0 or later - At least two Kubernetes clusters - The Kubernetes clusters must be running in a flat network -- The network must be running on Consul on Kubernetes v0.45 or later +- The network must be running on Consul on Kubernetes version 0.45 or later ### Helm chart configuration @@ -128,7 +128,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a ## Export services between clusters -1. For the service in "cluster-02" that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) to your service's pods. This service is referred to as "backend-service" in the following steps. +1. For the service in "cluster-02" that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) to your service's pods. From 017a94c0b6dc87dd3b67f3fbb6c734c13b739243 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 2 Aug 2022 16:25:13 -0500 Subject: [PATCH 11/27] Minor edit --- website/content/docs/connect/cluster-peering/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 0b3bb56b0f..bfce6dbd03 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -38,7 +38,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste ## Beta release features and constraints -The cluster peering beta adds the following features and functionality: +The cluster peering beta includes the following features and functionality: - Mesh Gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). - You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI. From 3ec5d8a9b108e58bae2a87e5701031be5d1aac97 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 8 Aug 2022 15:09:12 -0500 Subject: [PATCH 12/27] Added info about Consul server config requirements --- .../connect/cluster-peering/create-manage-peering.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index cdea85512c..77e483e682 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -13,13 +13,19 @@ A peering token enables cluster peering between different datacenters. Once you ## Create a peering connection -To peer clusters, you must complete the following steps in order: +Cluster peering is not enabled by default on Consul servers. To peer clusters, you must first configure all Consul servers so that `peering` is `enabled`. For additional information, refer to [Configuration Files](/docs/agent/config/config-files). + +Then, complete the following steps in order: 1. Create a peering token 1. Establish a connection between clusters 1. Export services between clusters 1. Authorize services for peers +### Enable peering on all Consul servers + +Cluster peering is not enabled by default. To enable cluster peering, + ### Create a peering token You can generate peering tokens and initiate connections on any available agent using either the Consul UI or the API. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. From c972f0ea04b61c5c9e850eeeab673ed4efd47e14 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 8 Aug 2022 15:34:28 -0500 Subject: [PATCH 13/27] Add peering connection UI iinitial commit. --- .../cluster-peering/create-manage-peering.mdx | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 77e483e682..1240603b91 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -22,16 +22,14 @@ Then, complete the following steps in order: 1. Export services between clusters 1. Authorize services for peers -### Enable peering on all Consul servers - -Cluster peering is not enabled by default. To enable cluster peering, - ### Create a peering token -You can generate peering tokens and initiate connections on any available agent using either the Consul UI or the API. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. - To begin the cluster peering process, generate a peering token in one of your clusters. The other cluster uses this token to establish the peering connection. +Everytime you generate a peering token, a single-use establishment secret is embedded in the token. Because regenerating a peering token invalidates the previously generated secret, you must use the most recently created token to establish peering connections. + +You can generate peering tokens and initiate connections on any available agent using either the Consul UI or the API. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. + In `cluster-01`, issue a request for a peering token. @@ -58,6 +56,16 @@ Create a JSON file that contains the first cluster's name and the peering token. +1. In the Consul UI associated with `cluster-01`, click **Peers**. +1. Click **Add peer connection**. +1. In the **Name of peer** field, enter `cluster-02`. Then, click **Generate token**. +1. Copy the token. Be careful not to lose the token, as you cannot view the token again after leaving this screen. +1. Switch to the UI associated with `cluster 02`. Then, click **Peers** and then **Add peer connection**. +1. Click **Establish peering**. +1. In the **Name of peer** field, enter `cluster-01`. Then paste the token in the **Token** field. +1. Click **Add peer**. + +The From f0c916479b3b71d8f390957d8d30773103e2e41f Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 8 Aug 2022 16:32:38 -0500 Subject: [PATCH 14/27] UI instructions --- .../cluster-peering/create-manage-peering.mdx | 58 +++++++------------ 1 file changed, 21 insertions(+), 37 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 1240603b91..c1acacc7eb 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -22,16 +22,19 @@ Then, complete the following steps in order: 1. Export services between clusters 1. Authorize services for peers +You can generate peering tokens and initiate connections on any available agent using either the API or the Consul UI. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. + +The UI does not currently support exporting services between clusters or authorizing services for peers. + ### Create a peering token To begin the cluster peering process, generate a peering token in one of your clusters. The other cluster uses this token to establish the peering connection. Everytime you generate a peering token, a single-use establishment secret is embedded in the token. Because regenerating a peering token invalidates the previously generated secret, you must use the most recently created token to establish peering connections. -You can generate peering tokens and initiate connections on any available agent using either the Consul UI or the API. If you use the API, we recommend performing these operations through a client agent in the partition you want to connect. - + In `cluster-01`, issue a request for a peering token. ```shell-session @@ -56,16 +59,11 @@ Create a JSON file that contains the first cluster's name and the peering token. -1. In the Consul UI associated with `cluster-01`, click **Peers**. +1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. 1. Click **Add peer connection**. -1. In the **Name of peer** field, enter `cluster-02`. Then, click **Generate token**. -1. Copy the token. Be careful not to lose the token, as you cannot view the token again after leaving this screen. -1. Switch to the UI associated with `cluster 02`. Then, click **Peers** and then **Add peer connection**. -1. Click **Establish peering**. -1. In the **Name of peer** field, enter `cluster-01`. Then paste the token in the **Token** field. -1. Click **Add peer**. - -The +1. In the **Generate token** tab, enter `cluster-02` in the **Name of peer** field. +1. Click the **Generate token** button. +1. Copy the token before you proceed. Be careful not to lose the token, as you cannot view the token again after leaving this screen. If you lose your token, you must generate a new one. @@ -75,6 +73,7 @@ Next, use the peering token to establish a secure connection between the cluster + In one of the client agents in "cluster-02," use `peering_token.json` to establish the peering connection. This endpoint does not generate an output unless there is an error. ```shell-session @@ -86,6 +85,10 @@ When you connect server agents through cluster peering, they peer their default +1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**. +1. Click **Establish peering**. +1. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. +1. Click **Add peer**. @@ -93,8 +96,6 @@ When you connect server agents through cluster peering, they peer their default 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. - - First, create a configuration entry and specify the `Kind` as `"exported-services"`. @@ -127,19 +128,11 @@ $ consul config write peering-config.hcl ``` Before you proceed, wait for the clusters to sync and make services available to their peers. You can issue an endpoint query to [check the peered cluster status](#check-peered-cluster-status). - - - - - - ### Authorize services for peers Before you can call services from peered clusters, you must set service intentions that authorize those clusters to use specific services. Consul prevents services from being exported to unauthorized clusters. - - First, create a configuration entry and specify the `Kind` as `"service-intentions"`. Declare the service on "cluster-02" that can access the service in "cluster-01." The following example sets service intentions so that "frontend-service" can access "backend-service." @@ -166,12 +159,6 @@ Then, add the configuration entry to your cluster. ```shell-session $ consul config write peering-intentions.hcl ``` - - - - - - ## Manage peering connections @@ -220,6 +207,9 @@ $ curl http://127.0.0.1:8500/v1/peerings +In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in a datacenter. + +The name that appears in the list is the name of the cluster in a different datacenter with an established peering connection. @@ -252,6 +242,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 +In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in a datacenter. Click the name of a peered cluster to view additional details about the peering connection. @@ -259,9 +250,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 You can check the status of your peering connection to perform health checks. - - -To confirm that the peering connection between your clusters remains healthy, [query the `/health/service` endpoint](/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. +To confirm that the peering connection between your clusters remains healthy, query the [`health/service` endpoint](/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. ```shell-session $ curl \ @@ -269,12 +258,6 @@ $ curl \ ``` A successful query includes service information in the output. - - - - - - ### Delete peering connections @@ -282,7 +265,8 @@ You can disconnect the peered clusters by deleting their connection. Deleting a -In "cluster-01," request the deletion through the [`/peering/` endpoint](api-docs/peering#delete-a-peering-connection). + +In "cluster-01," request the deletion through the [`/peering/ endpoint`](/api-docs/peering#delete-a-peering-connection). ```shell-session $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 From 407147b2e6408204bf57904956fe2e9b7c48c831 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 8 Aug 2022 16:40:14 -0700 Subject: [PATCH 15/27] Fixed rendering --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index c1acacc7eb..5bf7f501a9 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -64,6 +64,7 @@ Create a JSON file that contains the first cluster's name and the peering token. 1. In the **Generate token** tab, enter `cluster-02` in the **Name of peer** field. 1. Click the **Generate token** button. 1. Copy the token before you proceed. Be careful not to lose the token, as you cannot view the token again after leaving this screen. If you lose your token, you must generate a new one. + @@ -89,6 +90,7 @@ When you connect server agents through cluster peering, they peer their default 1. Click **Establish peering**. 1. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. 1. Click **Add peer**. + From 7854b6edc9050c015c4125b4d757fd0d7c180482 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 9 Aug 2022 08:53:03 -0500 Subject: [PATCH 16/27] Delete peering UI instructions --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 5bf7f501a9..0efefb3b0d 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -244,7 +244,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 -In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in a datacenter. Click the name of a peered cluster to view additional details about the peering connection. +In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter. Click the name of a peered cluster to view additional details about the peering connection. @@ -277,5 +277,9 @@ $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 +In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter. + +Next to the name of the peer, click **More** (three horizontal dots) and then **Delete**. Click **Delete** to confirm and remove the peering connection. + From 2274f35c89ceb6001542da5b94551981a51cd1f8 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:01:27 -0500 Subject: [PATCH 17/27] Update website/content/docs/connect/cluster-peering/create-manage-peering.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 5bf7f501a9..b558813f41 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -15,7 +15,7 @@ A peering token enables cluster peering between different datacenters. Once you Cluster peering is not enabled by default on Consul servers. To peer clusters, you must first configure all Consul servers so that `peering` is `enabled`. For additional information, refer to [Configuration Files](/docs/agent/config/config-files). -Then, complete the following steps in order: +After enabling peering for all Consul servers, complete the following steps in order: 1. Create a peering token 1. Establish a connection between clusters From 31434093f17143a50a2b9da10d704a2a7ff929f5 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:01:42 -0500 Subject: [PATCH 18/27] Update website/content/docs/connect/cluster-peering/create-manage-peering.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index b558813f41..4192c9c810 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -30,7 +30,7 @@ The UI does not currently support exporting services between clusters or authori To begin the cluster peering process, generate a peering token in one of your clusters. The other cluster uses this token to establish the peering connection. -Everytime you generate a peering token, a single-use establishment secret is embedded in the token. Because regenerating a peering token invalidates the previously generated secret, you must use the most recently created token to establish peering connections. +Every time you generate a peering token, a single-use establishment secret is embedded in the token. Because regenerating a peering token invalidates the previously generated secret, you must use the most recently created token to establish peering connections. From 77e4a5f3c48b3c06af0cb71163c423d38fa79202 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:02:05 -0500 Subject: [PATCH 19/27] Update website/content/docs/connect/cluster-peering/create-manage-peering.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 4192c9c810..e0621e2965 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -164,7 +164,7 @@ $ consul config write peering-intentions.hcl ## Manage peering connections -After you establish a peering connection, you can get a list of all active peering connections, read a specific peering connection's info, check peering connection health, and delete peering connections. +After you establish a peering connection, you can get a list of all active peering connections, read a specific peering connection's information, check peering connection health, and delete peering connections. ### List all peering connections From 6840861a17dfaecf2229019c8dd7580763b16527 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:02:16 -0500 Subject: [PATCH 20/27] Update website/content/docs/connect/cluster-peering/create-manage-peering.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index e0621e2965..5cad250c9e 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -173,7 +173,7 @@ You can list all active peering connections in a cluster. -After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the info as a series of JSON objects: +After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects: ```shell-session $ curl http://127.0.0.1:8500/v1/peerings From b019ce6e622077ee4d8816498734d890d03f658a Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:02:33 -0500 Subject: [PATCH 21/27] Update website/content/docs/connect/cluster-peering/create-manage-peering.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 5cad250c9e..713b6eb347 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -222,7 +222,7 @@ You can get information about individual peering connections between clusters. -After you establish a peering connection, [query the `/peering/:name` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection info for "cluster-02" and returns the info as a JSON object: +After you establish a peering connection, [query the `/peering/:name` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object: ```shell-session $ curl http://127.0.0.1:8500/v1/peering/cluster-02 From 9c2d7fb2685828a2c0f075f8401b273530dfe9ea Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 9 Aug 2022 09:07:25 -0500 Subject: [PATCH 22/27] WAN Federation/Cluster Peering comparison table addition --- .../docs/connect/cluster-peering/index.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index bfce6dbd03..7b1c9c6842 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -27,14 +27,16 @@ WAN federation and cluster peering are different ways to connect clusters. The m Regardless of whether you connect your clusters through WAN federation or cluster peering, human and machine users can use either method to discover services in other clusters or dial them through the service mesh. -| | WAN Federation | Cluster Peering | -| :----------------------------------------------- | :------------: | :-------------: | -| Connects clusters across datacenters | ✅ | ✅ | -| Shares support queries and service endpoints | ✅ | ✅ | -| Connects clusters owned by different operators | ❌ | ✅ | -| Functions without declaring primary datacenter | ❌ | ✅ | -| Shares key/value stores | ✅ | ❌ | -| Uses gossip protocol | ✅ | ❌ | +| | WAN Federation | Cluster Peering | +| :------------------------------------------------- | :------------: | :-------------: | +| Connects clusters across datacenters | ✅ | ✅ | +| Shares support queries and service endpoints | ✅ | ✅ | +| Connects clusters owned by different operators | ❌ | ✅ | +| Functions without declaring primary datacenter | ❌ | ✅ | +| Replicates exported services for service discovery | ❌ | ✅ | +| Shares key/value stores | ✅ | ❌ | +| Uses gossip protocol | ✅ | ❌ | +| Forwards service requests for service discovery | ✅ | ❌ | ## Beta release features and constraints From c3bebf80ce2c71caa7f2a7a9aeaf9658c6d22823 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:10:34 -0500 Subject: [PATCH 23/27] Update website/content/docs/connect/cluster-peering/index.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/connect/cluster-peering/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index bfce6dbd03..6f522b708c 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -40,7 +40,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste The cluster peering beta includes the following features and functionality: -- Mesh Gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). +- Mesh gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). - You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI. - You can configure [transparent proxies](/docs/connect/transparent-proxy) for peered services. - You can use the [`peering` rule for ACL enforcement](/docs/security/acl/acl-rules#peering) of peering APIs. From fc010e3fe23e1d6060f7de380cd3c9e8f4085cc7 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 9 Aug 2022 09:25:45 -0500 Subject: [PATCH 24/27] Update website/content/docs/connect/cluster-peering/k8s.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/connect/cluster-peering/k8s.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 3a43d0c034..69b34e2e54 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -11,7 +11,7 @@ description: >- with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. -To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create Custom Resource Definitions (CRDs) for each side of the peering. +To establish a cluster peering connection on Kubernetes, you need to enable the feature in the Helm chart and create custom resource definitions (CRDs) for each side of the peering. The following CRDs are used to create and manage a peering connection: From 166c95e40f4d7d7e76d900ba7fd7f7260425226c Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 9 Aug 2022 09:42:01 -0500 Subject: [PATCH 25/27] Fixes according to Freddy's review/comments --- website/content/docs/connect/cluster-peering/index.mdx | 5 +++-- .../mesh-gateway/service-to-service-traffic-peers.mdx | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 7b1c9c6842..a04b458c34 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -34,9 +34,9 @@ Regardless of whether you connect your clusters through WAN federation or cluste | Connects clusters owned by different operators | ❌ | ✅ | | Functions without declaring primary datacenter | ❌ | ✅ | | Replicates exported services for service discovery | ❌ | ✅ | +| Forwards service requests for service discovery | ✅ | ❌ | | Shares key/value stores | ✅ | ❌ | | Uses gossip protocol | ✅ | ❌ | -| Forwards service requests for service discovery | ✅ | ❌ | ## Beta release features and constraints @@ -50,9 +50,10 @@ The cluster peering beta includes the following features and functionality: Not all features and functionality are available in the beta release. In particular, consider the following technical constraints: - Mesh gateways for _server to server traffic_ are not available. +- Services with node, instance, and check definitions totaling more than 4MB cannot be exported to a peer. - Dynamic routing features such as splits, custom routes, and redirects cannot target services in a peered cluster. - Configuring service failover across peers is not supported for service mesh. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). - Accessing key/value stores across peers is not supported. -- Non-enterprise Consul instances cannot sync services with namespaces outside of the `default` namespace. +- Because non-Enterprise Consul instances are restricted to the `default` namespace, Consul Enterprise instances cannot export services from outside of the `default` namespace to non-Enterprise peers. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx index 1de6e019a2..34cba6306b 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -12,7 +12,7 @@ description: >- Mesh gateways are required for you to route service mesh traffic between different Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible. -Unlike mesh gateways for datacenters and partitions, mesh gateways for cluster peering decrypts data to HTTP services within the mTLS session. Data must be decrypted in order to apply dynamic routing rules configured in the destination cluster. +Unlike mesh gateways for datacenters and partitions, mesh gateways for cluster peering decrypt data to HTTP services within the mTLS session. Data must be decrypted in order to evaluate and apply dynamic routing rules at the destination cluster, which reduces coupling between peers. ## Prerequisites @@ -21,6 +21,7 @@ To configure mesh gateways for cluster peering, make sure your Consul environmen - Consul version 1.13.0 or newer. - A local Consul agent is required to manage mesh gateway configuration. - [Enable Consul service mesh](/docs/agent/config/config-files#connect-parameters) in all clusters. +- [Enable `peering`](/docs/agent/config/config-files) on all Consul servers. - Use [Envoy proxies](/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. ## Configuration From fa462915c9e1f09116998da1e1eba428f4d837dc Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 9 Aug 2022 09:42:22 -0500 Subject: [PATCH 26/27] Addt'l fixes --- .../gateways/mesh-gateway/service-to-service-traffic-peers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx index 34cba6306b..0163730ba4 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -52,4 +52,4 @@ Alternatively, you can also use the CLI to spin up and register a gateway in Con ### Modes -In the current release, modes are not configurable for mesh gateways that connect peered clusters. By default, all proxies connected to the gateway behave in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). +Modes are not configurable for mesh gateways that connect peered clusters. By default, all proxies connecting to peered clusters use mesh gateways in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). From 1d184a08435fe5e938a3d7cfb121a03645bc09fa Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 9 Aug 2022 10:09:53 -0500 Subject: [PATCH 27/27] Fixes --- .../cluster-peering/create-manage-peering.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index fc0f946a4f..5662868834 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -35,7 +35,7 @@ Every time you generate a peering token, a single-use establishment secret is em -In `cluster-01`, issue a request for a peering token. +In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token. ```shell-session $ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token @@ -75,13 +75,17 @@ Next, use the peering token to establish a secure connection between the cluster -In one of the client agents in "cluster-02," use `peering_token.json` to establish the peering connection. This endpoint does not generate an output unless there is an error. +In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish` endpoint](/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error. ```shell-session $ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish ``` When you connect server agents through cluster peering, they peer their default partitions. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/api-docs/peering). + + +You can dial the `peering/establish` endpoint once per peering token. Peering tokens cannot be reused after being used to establish a connection. If you need to re-establish a connection, you must generate a new peering token. + @@ -118,6 +122,7 @@ Services = [ ## during the peering process. Peer = "cluster-02" } + } ] ``` @@ -173,7 +178,7 @@ You can list all active peering connections in a cluster. -After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects: +After you establish a peering connection, [query the `/peerings/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects: ```shell-session $ curl http://127.0.0.1:8500/v1/peerings @@ -222,7 +227,7 @@ You can get information about individual peering connections between clusters. -After you establish a peering connection, [query the `/peering/:name` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object: +After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object: ```shell-session $ curl http://127.0.0.1:8500/v1/peering/cluster-02