From ff9348f877e15c46660a197a71799b411868c48e Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 13:57:04 -0500 Subject: [PATCH 01/23] Mike Morris clean up requests --- .../cluster-peering/create-manage-peering.mdx | 9 ++++----- .../docs/connect/cluster-peering/index.mdx | 17 +++++++++-------- .../service-to-service-traffic-peers.mdx | 2 +- 3 files changed, 14 insertions(+), 14 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 916ef33da8..343edfd6f3 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -94,8 +94,7 @@ In one of the client agents in "cluster-02," use `peering_token.json` and the [` $ 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). - +When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. 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. @@ -123,9 +122,9 @@ If you need to re-establish a connection, you must generate a new peering token. 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**. +2. Click **Establish peering**. +3. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. +4. Click **Add peer**. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index f216fb780c..c457f5ff4b 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -13,17 +13,18 @@ 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: +Cluster peering is a process that allows Consul clusters to communicate with each other. The cluster peering process consists of the following steps: + 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 authorize services for peers. +2. Use the peering token to establish peering with a second cluster. +3. Export services between clusters. +4. Create intentions to authorize services for peers. 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 -WAN federation and cluster peering are different ways to connect clusters. The most important distinction is that WAN federation assumes clusters are owned by the same operators, so it maintains and replicates global states such as ACLs and configuration entries. As a result, WAN federation requires a _primary datacenter_ to serve as an authority for replicated data. +WAN federation and cluster peering are different ways to connect Consul deployments. WAN federation connects multiple datacenters to make them function as if they were a single cluster, while cluster peering treats each datacenter as a separate cluster. As a result, WAN federation requires a primary datacenter to maintain and replicate global states such as ACLs and configuration entries, but cluster peering does not. 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. @@ -34,14 +35,16 @@ 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 | ❌ | ✅ | +| Gossip protocol: Requires LAN gossip only | ❌ | ✅ | | Forwards service requests for service discovery | ✅ | ❌ | | Shares key/value stores | ✅ | ❌ | -| Uses gossip protocol | ✅ | ❌ | + ## Beta release features and constraints The cluster peering beta includes the following features and functionality: +- Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - 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. @@ -52,8 +55,6 @@ Not all features and functionality are available in the beta release. In particu - 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. - 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 ad961fbf68..c971c0a275 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 @@ -11,7 +11,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 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. +Unlike mesh gateways for datacenters and partitions, mesh gateways between peers terminate mTLS sessions to decrypt data to HTTP services and then re-encrypt traffic to send to services. Data must be decrypted in order to evaluate and apply dynamic routing rules at the destination cluster, which reduces coupling between peers. ## Prerequisites From 6f52816680b4387d92702e037f49cd82afa89bbb Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 14:00:21 -0500 Subject: [PATCH 02/23] Kyle Rarey - requested constraints added --- website/content/docs/connect/cluster-peering/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index c457f5ff4b..567dda3307 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -58,3 +58,5 @@ Not all features and functionality are available in the beta release. In particu - 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. - 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. +- Cross-cluster traffic forwarding does not support `http` type services. +- Cross-cluster mesh gateways are supported in `remote` mode only. From 6fd154ec733dfd8eb90ffccd58075c9c1a42a78d Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 14:13:38 -0500 Subject: [PATCH 03/23] Tab groupings --- .../cluster-peering/create-manage-peering.mdx | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 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 343edfd6f3..7d61d67890 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -33,7 +33,7 @@ To begin the cluster peering process, generate a peering token in one of your cl 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. - + In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token. @@ -57,7 +57,7 @@ Create a JSON file that contains the first cluster's name and the peering token. - + In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token. @@ -70,13 +70,13 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0 - + 1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. -1. Click **Add peer connection**. -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. +2. Click **Add peer connection**. +3. In the **Generate token** tab, enter `cluster-02` in the **Name of peer** field. +4. Click the **Generate token** button. +5. 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. @@ -86,7 +86,7 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0 Next, use the peering token to establish a secure connection between the clusters. - + 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. @@ -100,7 +100,7 @@ You can dial the `peering/establish` endpoint once per peering token. Peering to - + In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. The commands prints "Successfully established peering connection with cluster-01" after the connection is established. @@ -119,7 +119,7 @@ If you need to re-establish a connection, you must generate a new peering token. - + 1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**. 2. Click **Establish peering**. @@ -208,7 +208,7 @@ After you establish a peering connection, you can get a list of all active peeri You can list all active peering connections in a cluster. - + 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: @@ -244,7 +244,7 @@ $ curl http://127.0.0.1:8500/v1/peerings ``` - + After you establish a peering connection, run the [`consul peering list`](/commands/peering/list) command to get a list of all peering connections. For example, the following command requests a list of all peering connections and returns the information in a table: @@ -258,7 +258,7 @@ cluster-03 PENDING 0 0 ``` - + In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in a datacenter. @@ -271,7 +271,7 @@ The name that appears in the list is the name of the cluster in a different data You can get information about individual peering connections between clusters. - + 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: @@ -293,7 +293,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 ``` - + After you establish a peering connection, run the [`consul peering read`](/commands/peering/list) command to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02": @@ -322,7 +322,7 @@ Modify Index: 89 ``` - + 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. @@ -346,7 +346,7 @@ A successful query includes service information in the output. 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. - + In "cluster-01," request the deletion through the [`/peering/ endpoint`](/api-docs/peering#delete-a-peering-connection). @@ -355,7 +355,7 @@ $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 ``` - + In "cluster-01," request the deletion through the [`consul peering delete`](/commands/peering/list) command. @@ -366,7 +366,7 @@ Successfully submitted peering connection, cluster-02, for deletion ``` - + In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter. From 3e2a650e5f5bcb81f2fe6d239d9a5f32ca3884e0 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 15:42:21 -0500 Subject: [PATCH 04/23] k8s page updates --- .../docs/connect/cluster-peering/k8s.mdx | 92 +++++++++++++------ 1 file changed, 62 insertions(+), 30 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 75a90bb1de..bf24093cf2 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -18,34 +18,31 @@ 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. +As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers. + ## Prerequisites You must implement the following requirements to create and use cluster peering connections with Kubernetes: -- Consul version 1.13.1 or later + +- Consul v1.13.1 or later - At least two Kubernetes clusters - The installation must be running on Consul on Kubernetes version 0.47.1 or later -### Prepare for install +### Prepare for installation -1. After provisioning a Kubernetes cluster and setting up your kubeconfig file to manage access to multiple Kubernetes clusters, export the Kubernetes context names for future use with `kubectl`. For more information on how to use kubeconfig and contexts, refer to [Configure access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) on the Kubernetes documentation website. +1. After you provision a Kubernetes cluster and set up your kubeconfig file to manage access to multiple Kubernetes clusters, use the `kubectl` command to export the Kubernetes context names and then set them to variables for future use. For more information on how to use kubeconfig and contexts, refer to the [Kubernetes docs on configuring access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). You can use the following methods to get the context names for your clusters: - * Issue the `kubectl config current-context` command to get the context for the cluster you are currently in. - * Issue the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file. + - Use the `kubectl config current-context` command to get the context for the cluster you are currently in. + - Use the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file. ```shell-session $ export CLUSTER1_CONTEXT= $ export CLUSTER2_CONTEXT= ``` -1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values. - - With these values, - the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized - using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). - - When generating a peering token from one of the clusters, Consul uses the address(es) of the load balancer in the peering token so that the peering stream goes through the load balancer in front of the servers. For customizing the addresses used in the peering token, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration). +1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values. @@ -71,12 +68,16 @@ You must implement the following requirements to create and use cluster peering ``` + + These Helm values configure the servers in each cluster so that they expose ports over a Kubernetes load balancer service. For additional configuration options, refer to [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). + + When generating a peering token from one of the clusters, Consul includes a load balancer address in the token so that the peering stream goes through the load balancer in front of the servers. For additional configuration options, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration). ### Install Consul on Kubernetes -1. Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. +Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each cluster. - 1. Install Consul on Kubernetes on `cluster-01` + 1. In `cluster-01`, run the following commands: ```shell-session $ export HELM_RELEASE_NAME=cluster-01 @@ -85,7 +86,8 @@ You must implement the following requirements to create and use cluster peering ```shell-session $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER1_CONTEXT ``` - 1. Install Consul on Kubernetes on `cluster-02` + + 1. In `cluster-02`, run the following commands: ```shell-session $ export HELM_RELEASE_NAME=cluster-02 @@ -95,9 +97,11 @@ You must implement the following requirements to create and use cluster peering $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER2_CONTEXT ``` -## Create a peering token +## Create a peering connection for Consul on Kubernetes -To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. As part of the peering process, the peer names for each respective cluster within the peering are established by using the `metadata.name` values for the `PeeringAcceptor` and `PeeringDialer` CRDs. +### Create a peering token + +To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. Peers identify each other using the `metadata.name` values you establish when creating the `PeeringAcceptor` and `PeeringDialer` CRDs. 1. In `cluster-01`, create the `PeeringAcceptor` custom resource. @@ -130,7 +134,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl --context $CLUSTER1_CONTEXT get secret peering-token --output yaml > peering-token.yaml ``` -## Establish a peering connection between clusters +### Establish a peering connection between clusters 1. Apply the peering token to the second cluster. @@ -138,7 +142,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl --context $CLUSTER2_CONTEXT apply --filename peering-token.yaml ``` -1. In `cluster-02`, create the `PeeringDialer` custom resource. +1. In `cluster-02`, create the `PeeringDialer` custom resource. @@ -163,9 +167,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml ``` -## Export services between clusters +### Export services between clusters -1. For the service in "cluster-02" that you want to export, add the following [annotation](/docs/k8s/annotations-and-labels) to your service's pods. +~> **Tip**: The examples in this section demonstrate how to export a service named `backend`. You should change instances of `backend` in the example code to the name of the service you want to export. + +1. For the service in `cluster-02` that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels) to your service's pods. @@ -189,7 +195,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a metadata: name: backend --- - # deployment for backend + # Deployment for backend apiVersion: apps/v1 kind: Deployment metadata: @@ -243,13 +249,13 @@ 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. +1. Apply the service file and the `ExportedServices` resource to the second cluster. ```shell-session $ kubectl apply --context $CLUSTER2_CONTEXT --filename backend.yaml --filename exportedsvc.yaml ``` -## Authorize services for peers +### Authorize services for peers 1. Create service intentions for the second cluster. @@ -278,7 +284,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yml ``` -1. For the services in `cluster-01` that you want to access the "backend," add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). +1. For the services in `cluster-01` that you want to access `backend`, add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). @@ -350,10 +356,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a $ kubectl --context $CLUSTER1_CONTEXT apply --filename frontend.yaml ``` -1. Run the following command in `frontend` and check the output to confirm that you peered your clusters successfully. +1. Run the following command in `frontend` and then check the output to confirm that you peered your clusters successfully. ```shell-session $ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090 + { "name": "frontend", "uri": "/", @@ -401,9 +408,9 @@ $ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02" ## Recreate or reset a peering connection -To recreate or reset the peering connection, you need to generate a new peering token on the cluster where you created the `PeeringAcceptor` (in this example, `cluster-01`). +To recreate or reset the peering connection, you need to generate a new peering token from the cluster where you created the `PeeringAcceptor`. -1. You can do this by creating or updating the annotation `consul.hashicorp.com/peering-version` on the `PeeringAcceptor`. If the annotation already exists, update its value to a version that is higher. +1. In the `PeeringAcceptor` CRD, add the annotation `consul.hashicorp.com/peering-version`. If the annotation already exists, update its value to a higher version. @@ -424,6 +431,31 @@ To recreate or reset the peering connection, you need to generate a new peering -1. Once you have done this, repeat the steps in the peering process. This includes saving your peering token so that you can export it to the other cluster. This will re-establish peering with the updated token. +2. After you update `PeeringAcceptor`, repeat the steps to create a peering connection, including saving a new peering token and exporting it to the other cluster. Your peering connection is re-established with the updated token. -~> **Note:** A new peering token is only generated upon manually setting and updating the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token will cause the previous token to expire. +~> **Note:** The only way to create or set a new peering token is to manually adjust the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token causes the previous token to expire. + +## Traffic management between peers + +As of Consul v1.14, you can use dynamic traffic management features to configure your service mesh so that services automatically failover and redirect between peers. + +To configure automatic service failovers and redirect, edit the `ServiceResolver` CRD so that traffic resolves to a backup service instance on a peer. The following example updates the `ServiceResolver` CRD in `cluster-02` so that Consul redirects traffic intended for the `backend` service to a backup instance in `cluster-01` when it detects multiple connection failures to the primary instance. + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: backend +spec: + connectTimeout: 15s + failover: + '*': + targets: + - peer: 'cluster-01' + service: 'backup' + namespace: 'default' +``` + + \ No newline at end of file From 66f8c65e898caa8508ad11fdde3315cd3ca62b5d Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 15:52:03 -0500 Subject: [PATCH 05/23] Traffic Management --- .../cluster-peering/create-manage-peering.mdx | 55 +++++++++++++++++++ .../docs/connect/cluster-peering/k8s.mdx | 8 +-- 2 files changed, 59 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 7d61d67890..7f82c2c326 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -374,3 +374,58 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** + +## Traffic nanagement between peers + +As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples updates the [ServiceResolver config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. + + + +```hcl +Kind = "service-resolver" +Name = "frontend" +ConnectTimeout = "15s" +Failover = { + "*" = { + Targets = [ + {Peer = "cluster-02"} + ] + } +} +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: frontend +spec: + connectTimeout: 15s + failover: + '*': + targets: + - peer: 'cluster-02' + service: 'backup' + namespace: 'default' +``` + +```json +{ + "ConnectTimeout": "15s", + "Kind": "service-resolver", + "Name": "frontend", + "Failover": { + "*": { + "Targets": [ + { + "Peer": "cluster-02" + } + ] + } + }, + "CreateIndex": 250, + "ModifyIndex": 250 +} +``` + + \ No newline at end of file diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index bf24093cf2..e9b42a8663 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -437,9 +437,9 @@ To recreate or reset the peering connection, you need to generate a new peering ## Traffic management between peers -As of Consul v1.14, you can use dynamic traffic management features to configure your service mesh so that services automatically failover and redirect between peers. +As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. -To configure automatic service failovers and redirect, edit the `ServiceResolver` CRD so that traffic resolves to a backup service instance on a peer. The following example updates the `ServiceResolver` CRD in `cluster-02` so that Consul redirects traffic intended for the `backend` service to a backup instance in `cluster-01` when it detects multiple connection failures to the primary instance. +To configure automatic service failovers and redirect, edit the `ServiceResolver` CRD so that traffic resolves to a backup service instance on a peer. The following example updates the `ServiceResolver` CRD in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in `cluster-02` when it detects multiple connection failures to the primary instance. @@ -447,13 +447,13 @@ To configure automatic service failovers and redirect, edit the `ServiceResolver apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver metadata: - name: backend + name: frontend spec: connectTimeout: 15s failover: '*': targets: - - peer: 'cluster-01' + - peer: 'cluster-02' service: 'backup' namespace: 'default' ``` From 2589f07659343d8763658d0b39bb7710716b3d2a Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 16:03:32 -0500 Subject: [PATCH 06/23] Fixes --- website/content/docs/connect/cluster-peering/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 567dda3307..0bae34e173 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -20,7 +20,7 @@ Cluster peering is a process that allows Consul clusters to communicate with eac 3. Export services between clusters. 4. Create intentions to authorize services for peers. -For detailed instructions on setting up cluster peering, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). +For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). ### Differences between WAN federation and cluster peering @@ -39,11 +39,11 @@ Regardless of whether you connect your clusters through WAN federation or cluste | Forwards service requests for service discovery | ✅ | ❌ | | Shares key/value stores | ✅ | ❌ | - ## Beta release features and constraints -The cluster peering beta includes the following features and functionality: +The cluster peering beta release includes the following features and functionality: +- **Consul v1.14 beta only**: Dyanmic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - 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. @@ -54,7 +54,7 @@ Not all features and functionality are available in the beta release. In particu - 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. +- Some dynamic routing features, such as splits and custom routes, cannot target services in a peered cluster. - 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. - 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. From efcb466e38e70a52f0239231ba559d8bbfb6701e Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 16:09:23 -0500 Subject: [PATCH 07/23] Typo fix --- .../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 7f82c2c326..2dedce8fe4 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -375,7 +375,7 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** -## Traffic nanagement between peers +## Traffic management between peers As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples updates the [ServiceResolver config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. From 055bb88ee58d7c843255f443e60b13674d0b5bc2 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 16:10:36 -0500 Subject: [PATCH 08/23] Typo fix --- 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 0bae34e173..a8d60b1407 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -43,7 +43,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste The cluster peering beta release includes the following features and functionality: -- **Consul v1.14 beta only**: Dyanmic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. +- **Consul v1.14 beta only**: Dynanmic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - 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 dfd5903c8e9f7f85dd1af6fa58c1620b784ffeb9 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 28 Sep 2022 16:19:24 -0500 Subject: [PATCH 09/23] Typo fix --- 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 a8d60b1407..67aea76561 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -43,7 +43,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste The cluster peering beta release includes the following features and functionality: -- **Consul v1.14 beta only**: Dynanmic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. +- **Consul v1.14 beta only**: Dynamic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - 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 443dc35c31ca786a0ac39f89f979921776833944 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Fri, 30 Sep 2022 14:00:37 -0500 Subject: [PATCH 10/23] Apply suggestions from code review Co-authored-by: Eric Haberkorn --- website/content/docs/connect/cluster-peering/index.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 67aea76561..d59b0557b0 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -43,7 +43,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste The cluster peering beta release includes the following features and functionality: -- **Consul v1.14 beta only**: Dynamic traffic control with a `ServiceResolver` config entry can target failover and redirects to service instances in a peered cluster. +- **Consul v1.14 beta only**: Dynamic traffic control with a service resolver config entry can target failover and redirects to service instances in a peered cluster. - Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering. - 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. @@ -58,5 +58,4 @@ Not all features and functionality are available in the beta release. In particu - 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. - 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. -- Cross-cluster traffic forwarding does not support `http` type services. - Cross-cluster mesh gateways are supported in `remote` mode only. From 6866e89630e5448d0b1a600ae5d7130fbbb57cca Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 30 Sep 2022 14:00:55 -0500 Subject: [PATCH 11/23] service-resolver alignment --- .../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 2dedce8fe4..acb632856c 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -405,7 +405,7 @@ spec: '*': targets: - peer: 'cluster-02' - service: 'backup' + service: 'frontend' namespace: 'default' ``` From 80e3f15d479e7e56c9ec3ddd4145afdc72e95390 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 30 Sep 2022 15:32:43 -0500 Subject: [PATCH 12/23] Dynamic routing clarifications --- .../cluster-peering/create-manage-peering.mdx | 93 ++++++++++++++++++- .../docs/connect/cluster-peering/index.mdx | 2 +- 2 files changed, 93 insertions(+), 2 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 acb632856c..39c9f476c0 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -377,7 +377,9 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** ## Traffic management between peers -As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples updates the [ServiceResolver config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. +### Redirects and failover + +As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. @@ -428,4 +430,93 @@ spec: } ``` + + +### Service splitters and custom routes + +The `service-splitter` and `service-router` config entry kinds do not support directly targeting a service instance hosted on a peer. To split or route traffic to a service on a peer, you must combine the definition with a `service-resolver` config entry that defines the service hosted on the peer as an upstream service. For example, to split traffic evenly between `frontend` services hosted on peers, first define the desired behavior locally: + + + +```hcl +Kind = "service-splitter" +Name = "frontend" +Splits = [ + { + Weight = 50 + ## defaults to service with same name as config entry ("frontend") + }, + { + Weight = 50 + Service = "frontend-peer" + }, +] +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceSplitter +metadata: + name: frontend +spec: + splits: + - weight: 50 + ## defaults to service with same name as config entry ("web") + - weight: 50 + service: frontend-peer +``` + +```json +{ + "Kind": "service-splitter", + "Name": "frontend", + "Splits": [ + { + "Weight": 50 + }, + { + "Weight": 50, + "Service": "frontend-peer" + } + ] +} +``` + + + +Then, create a local `service-resolver` config entry named `frontend-peer` and define a redirect targeting the peer and its service: + + + +```hcl +Kind = "service-resolver" +Name = "frontend-peer" +Redirect { + Service = frontend + Peer = "cluster-02" +} +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: frontend-peer +spec: + redirect: + peer: 'cluster-02' + service: 'frontend' +``` + +```json +{ + "Kind": "service-resolver", + "Name": "frontend-peer", + "Redirect": { + "Service": "frontend", + "Peer": "cluster-02" + } +} +``` + \ No newline at end of file diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index d59b0557b0..9680f2c51d 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -54,7 +54,7 @@ Not all features and functionality are available in the beta release. In particu - 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. -- Some dynamic routing features, such as splits and custom routes, cannot target services in a peered cluster. +- The `service-splitter` and `service-router` config entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. - 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. - 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. From 69189e0381a3cb45538ac38da8d8a95ccb0f0d12 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 3 Oct 2022 11:36:48 -0500 Subject: [PATCH 13/23] Update website/content/docs/connect/cluster-peering/index.mdx --- 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 9680f2c51d..a1de37709f 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -54,7 +54,7 @@ Not all features and functionality are available in the beta release. In particu - 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. -- The `service-splitter` and `service-router` config entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. +- The `service-splitter` and `service-router` config entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. Refer to [L7 traffic management between peers](/docs/connect/cluster-peering/create-manage-peering#L7-traffic) for more information. - 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. - 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. From 12aa3cac4a123eb07744cf21fd693993223f3779 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 3 Oct 2022 11:38:43 -0500 Subject: [PATCH 14/23] Apply suggestions from code review --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 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 39c9f476c0..06271323a2 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -375,9 +375,9 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** -## Traffic management between peers +## L7 traffic management between peers -### Redirects and failover +### Service resolvers for redirects and failover As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. From 6eefbe0e9d579868d7b90ec1355f1a63847a61e4 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 3 Oct 2022 14:08:57 -0500 Subject: [PATCH 15/23] Tutorial links --- website/content/docs/connect/cluster-peering/index.mdx | 2 ++ website/content/docs/connect/cluster-peering/k8s.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index a1de37709f..a3be7df95a 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -22,6 +22,8 @@ Cluster peering is a process that allows Consul clusters to communicate with eac For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). +> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs). + ### Differences between WAN federation and cluster peering WAN federation and cluster peering are different ways to connect Consul deployments. WAN federation connects multiple datacenters to make them function as if they were a single cluster, while cluster peering treats each datacenter as a separate cluster. As a result, WAN federation requires a primary datacenter to maintain and replicate global states such as ACLs and configuration entries, but cluster peering does not. diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index e9b42a8663..55dcbcc4fb 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -20,6 +20,8 @@ The following CRDs are used to create and manage a peering connection: As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers. +> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs). + ## Prerequisites You must implement the following requirements to create and use cluster peering connections with Kubernetes: From 71b14a13fc9fb2b9f1f1200764bfe9f6803ff944 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 3 Oct 2022 14:18:59 -0500 Subject: [PATCH 16/23] PeerName changed to Peer - fix --- .../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 06271323a2..266dd45ba4 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -151,7 +151,7 @@ Services = [ { ## The peer name to reference in config is the one set ## during the peering process. - PeerName = "cluster-02" + Peer = "cluster-02" } ] } From 9e7c83a1290eacdd474fd9688ae4d0dbe12bf08b Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:26:07 -0500 Subject: [PATCH 17/23] Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../cluster-peering/create-manage-peering.mdx | 18 +++++++++--------- .../docs/connect/cluster-peering/index.mdx | 8 ++++---- .../docs/connect/cluster-peering/k8s.mdx | 18 ++++++++++++++---- 3 files changed, 27 insertions(+), 17 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 266dd45ba4..80dcdb35e5 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -73,10 +73,10 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0 1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. -2. Click **Add peer connection**. -3. In the **Generate token** tab, enter `cluster-02` in the **Name of peer** field. -4. Click the **Generate token** button. -5. 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. +1. Click **Add peer connection**. +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. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one. @@ -376,7 +376,7 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** ## L7 traffic management between peers - +The following sections describe how to enable L7 traffic management features between peered clusters. ### Service resolvers for redirects and failover As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. @@ -434,7 +434,7 @@ spec: ### Service splitters and custom routes -The `service-splitter` and `service-router` config entry kinds do not support directly targeting a service instance hosted on a peer. To split or route traffic to a service on a peer, you must combine the definition with a `service-resolver` config entry that defines the service hosted on the peer as an upstream service. For example, to split traffic evenly between `frontend` services hosted on peers, first define the desired behavior locally: +The `service-splitter` and `service-router` configuration entry kinds do not support directly targeting a service instance hosted on a peer. To split or route traffic to a service on a peer, you must combine the definition with a `service-resolver` configuration entry that defines the service hosted on the peer as an upstream service. For example, to split traffic evenly between `frontend` services hosted on peers, first define the desired behavior locally: @@ -444,7 +444,7 @@ Name = "frontend" Splits = [ { Weight = 50 - ## defaults to service with same name as config entry ("frontend") + ## defaults to service with same name as configuration entry ("frontend") }, { Weight = 50 @@ -461,7 +461,7 @@ metadata: spec: splits: - weight: 50 - ## defaults to service with same name as config entry ("web") + ## defaults to service with same name as configuration entry ("web") - weight: 50 service: frontend-peer ``` @@ -484,7 +484,7 @@ spec: -Then, create a local `service-resolver` config entry named `frontend-peer` and define a redirect targeting the peer and its service: +Then, create a local `service-resolver` configuration entry named `frontend-peer` and define a redirect targeting the peer and its service: diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index a3be7df95a..76cbf1de0d 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -16,9 +16,9 @@ You can create peering connections between two or more independent clusters so t Cluster peering is a process that allows Consul clusters to communicate with each other. The cluster peering process consists of the following steps: 1. Create a peering token in one cluster. -2. Use the peering token to establish peering with a second cluster. -3. Export services between clusters. -4. Create intentions to authorize services for peers. +1. Use the peering token to establish peering with a second cluster. +1. Export services between clusters. +1. Create intentions to authorize services for peers. For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). @@ -56,7 +56,7 @@ Not all features and functionality are available in the beta release. In particu - 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. -- The `service-splitter` and `service-router` config entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. Refer to [L7 traffic management between peers](/docs/connect/cluster-peering/create-manage-peering#L7-traffic) for more information. +- The `service-splitter` and `service-router` configuration entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. Refer to [L7 traffic management between peers](/docs/connect/cluster-peering/create-manage-peering#L7-traffic) for more information. - 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. - 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/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index 55dcbcc4fb..c4f5d51c96 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -32,7 +32,9 @@ You must implement the following requirements to create and use cluster peering ### Prepare for installation -1. After you provision a Kubernetes cluster and set up your kubeconfig file to manage access to multiple Kubernetes clusters, use the `kubectl` command to export the Kubernetes context names and then set them to variables for future use. For more information on how to use kubeconfig and contexts, refer to the [Kubernetes docs on configuring access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). +Complete the following procedure after you have provisioned a Kubernetes cluster and set up your kubeconfig file to manage access to multiple Kubernetes clusters. + +1. Use the `kubectl` command to export the Kubernetes context names and then set them to variables for future use. For more information on how to use kubeconfig and contexts, refer to the [Kubernetes docs on configuring access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). You can use the following methods to get the context names for your clusters: @@ -101,9 +103,11 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu ## Create a peering connection for Consul on Kubernetes +To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. Complete the following steps to create the peer 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. Peers identify each other using the `metadata.name` values you establish when creating the `PeeringAcceptor` and `PeeringDialer` CRDs. +Peers identify each other using the `metadata.name` values you establish when creating the `PeeringAcceptor` and `PeeringDialer` CRDs. 1. In `cluster-01`, create the `PeeringAcceptor` custom resource. @@ -171,7 +175,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a ### Export services between clusters -~> **Tip**: The examples in this section demonstrate how to export a service named `backend`. You should change instances of `backend` in the example code to the name of the service you want to export. +The examples described in this section demonstrate how to export a service named `backend`. You should change instances of `backend` in the example code to the name of the service you want to export. 1. For the service in `cluster-02` that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels) to your service's pods. @@ -433,7 +437,13 @@ To recreate or reset the peering connection, you need to generate a new peering -2. After you update `PeeringAcceptor`, repeat the steps to create a peering connection, including saving a new peering token and exporting it to the other cluster. Your peering connection is re-established with the updated token. +2. After updating `PeeringAcceptor`, repeat the following steps to create a peering connection: + 1. [Create a peering token](#create-a-peering-token) + 1. [Establish a peering connection between clusters](#establish-a-peering-connection-between-clusters) + 1. [Export services between clusters](#export-services-between-clusters) + 1. [Authorize services for peers](#authorize-services-for-peers) + + Your peering connection is re-established with the updated token. ~> **Note:** The only way to create or set a new peering token is to manually adjust the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token causes the previous token to expire. From 6d0f58ffe5ab14df1ce16d09f6032a46afa0d46e Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 09:31:31 -0500 Subject: [PATCH 18/23] Minor fixes --- website/content/docs/connect/cluster-peering/k8s.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index c4f5d51c96..8b565e2204 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -437,9 +437,9 @@ To recreate or reset the peering connection, you need to generate a new peering -2. After updating `PeeringAcceptor`, repeat the following steps to create a peering connection: - 1. [Create a peering token](#create-a-peering-token) - 1. [Establish a peering connection between clusters](#establish-a-peering-connection-between-clusters) +1. After updating `PeeringAcceptor`, repeat the following steps to create a peering connection: + 1. [Create a peering token](#create-a-peering-token) + 1. [Establish a peering connection between clusters](#establish-a-peering-connection-between-clusters) 1. [Export services between clusters](#export-services-between-clusters) 1. [Authorize services for peers](#authorize-services-for-peers) @@ -470,4 +470,4 @@ spec: namespace: 'default' ``` - \ No newline at end of file + From 631e7c1d7b49783a07580cf14980ab9166638dfd Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 09:49:10 -0500 Subject: [PATCH 19/23] Tab groups fix --- .../content/docs/connect/config-entries/exported-services.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index 0aa37e711e..67308cf509 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -4,6 +4,7 @@ page_title: Exported Services - Configuration Entry Reference description: >- An exported services configuration entry defines the availability of a cluster's services to cluster peers and local admin partitions. Learn about `""exported-services""` config entry parameters and exporting services to other datacenters. --- + # Exported Services Configuration Entry @@ -678,3 +679,5 @@ An ACL token with `service:write` permissions is required for the cluster the qu Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports. For additional information, refer to [Health HTTP Endpoint](/api-docs/health). + + \ No newline at end of file From b455e0d5c83c016e48d62effae56b39a957e9aea Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 10:00:53 -0500 Subject: [PATCH 20/23] Tabs fix again --- .../docs/connect/cluster-peering/create-manage-peering.mdx | 4 +++- .../docs/connect/config-entries/exported-services.mdx | 5 +---- 2 files changed, 4 insertions(+), 5 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 80dcdb35e5..1a6b682000 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -4,6 +4,7 @@ page_title: Cluster Peering - Create and Manage Connections description: >- Generate a peering token to establish communication, export services, and authorize requests for cluster peering connections. Learn how to create, list, read, check, and delete peering connections. --- + # Create and Manage Cluster Peering Connections @@ -519,4 +520,5 @@ spec: } ``` - \ No newline at end of file + + \ No newline at end of file diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index 67308cf509..0ed093f2de 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -4,7 +4,6 @@ page_title: Exported Services - Configuration Entry Reference description: >- An exported services configuration entry defines the availability of a cluster's services to cluster peers and local admin partitions. Learn about `""exported-services""` config entry parameters and exporting services to other datacenters. --- - # Exported Services Configuration Entry @@ -678,6 +677,4 @@ An ACL token with `service:write` permissions is required for the cluster the qu Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports. -For additional information, refer to [Health HTTP Endpoint](/api-docs/health). - - \ No newline at end of file +For additional information, refer to [Health HTTP Endpoint](/api-docs/health). \ No newline at end of file From cf796ce3305b6f9cf8bb81879c8b98bf1a362036 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 10:20:14 -0500 Subject: [PATCH 21/23] More group fix attempts --- .../cluster-peering/create-manage-peering.mdx | 119 +++++++++--------- 1 file changed, 60 insertions(+), 59 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 1a6b682000..330c8a705b 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -34,52 +34,52 @@ To begin the cluster peering process, generate a peering token in one of your cl 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. - + -In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to 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 -``` + ```shell-session + $ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token + ``` -The CLI outputs the peering token, which is a base64-encoded string containing the token details. + The CLI outputs the peering token, which is a base64-encoded string containing the token details. -Create a JSON file that contains the first cluster's name and the peering token. + Create a JSON file that contains the first cluster's name and the peering token. - + -```json -{ - "PeerName": "cluster-01", - "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" -} -``` + ```json + { + "PeerName": "cluster-01", + "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" + } + ``` - - + + - + -In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token. + In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token. -```shell-session -$ consul peering generate-token -name cluster-02 -``` + ```shell-session + $ consul peering generate-token -name cluster-02 + ``` -The CLI outputs the peering token, which is a base64-encoded string containing the token details. -Save this value to a file or clipboard to be used in the next step on `cluster-02`. + The CLI outputs the peering token, which is a base64-encoded string containing the token details. + Save this value to a file or clipboard to be used in the next step on `cluster-02`. - + - + -1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. -1. Click **Add peer connection**. -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. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one. + 1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. + 1. Click **Add peer connection**. + 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. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one. - + ### Establish a connection between clusters @@ -87,47 +87,47 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0 Next, use the peering token to establish a secure connection between the clusters. - + -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. + 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 + ``` -```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, their default behavior is to peer to the `default` partition. 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). -When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. 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. -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. + - + - + In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. + The commands prints "Successfully established peering connection with cluster-01" after the connection is established. -In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. -The commands prints "Successfully established peering connection with cluster-01" after the connection is established. + ```shell-session + $ consul peering establish -name cluster-01 -peering-token token-from-generate + ``` -```shell-session -$ consul peering establish -name cluster-01 -peering-token token-from-generate -``` + 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` flag to the `establish` command and specify the partitions you want to peer. + For additional configuration information, refer to [`consul peering establish` command](/commands/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` flag to the `establish` command and specify the partitions you want to peer. -For additional configuration information, refer to [`consul peering establish` command](/commands/peering/establish) . + You can run the `peering establish` command 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. -You can run the `peering establish` command 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. + - + - + 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**. -1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**. -2. Click **Establish peering**. -3. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. -4. Click **Add peer**. - - + ### Export services between clusters @@ -521,4 +521,5 @@ spec: ``` + \ No newline at end of file From 9792f9ea26367e009cf1a34c0855cb9500e8b810 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 10:34:18 -0500 Subject: [PATCH 22/23] Reverts + fix --- .../cluster-peering/create-manage-peering.mdx | 119 +++++++++--------- 1 file changed, 59 insertions(+), 60 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 330c8a705b..1a6b682000 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -34,52 +34,52 @@ To begin the cluster peering process, generate a peering token in one of your cl 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. - + - In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to 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 - ``` +```shell-session +$ curl --request POST --data '{"PeerName":"cluster-02"}' --url http://localhost:8500/v1/peering/token +``` - The CLI outputs the peering token, which is a base64-encoded string containing the token details. +The CLI outputs the peering token, which is a base64-encoded string containing the token details. - Create a JSON file that contains the first cluster's name and the peering token. +Create a JSON file that contains the first cluster's name and the peering token. - + - ```json - { - "PeerName": "cluster-01", - "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" - } - ``` +```json +{ + "PeerName": "cluster-01", + "PeeringToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8" +} +``` - - + + - + - In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token. +In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token. - ```shell-session - $ consul peering generate-token -name cluster-02 - ``` +```shell-session +$ consul peering generate-token -name cluster-02 +``` - The CLI outputs the peering token, which is a base64-encoded string containing the token details. - Save this value to a file or clipboard to be used in the next step on `cluster-02`. +The CLI outputs the peering token, which is a base64-encoded string containing the token details. +Save this value to a file or clipboard to be used in the next step on `cluster-02`. - + - + - 1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. - 1. Click **Add peer connection**. - 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. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one. +1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**. +1. Click **Add peer connection**. +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. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one. - + ### Establish a connection between clusters @@ -87,47 +87,47 @@ Every time you generate a peering token, a single-use establishment secret is em Next, use the peering token to establish a secure connection between the clusters. - + - 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 - ``` +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. - When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. 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). +```shell-session +$ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish +``` - 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. +When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. 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. - + - In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. - The commands prints "Successfully established peering connection with cluster-01" after the connection is established. + - ```shell-session - $ consul peering establish -name cluster-01 -peering-token token-from-generate - ``` +In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. +The commands prints "Successfully established peering connection with cluster-01" after the connection is established. - 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` flag to the `establish` command and specify the partitions you want to peer. - For additional configuration information, refer to [`consul peering establish` command](/commands/peering/establish) . +```shell-session +$ consul peering establish -name cluster-01 -peering-token token-from-generate +``` - You can run the `peering establish` command 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. +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` flag to the `establish` command and specify the partitions you want to peer. +For additional configuration information, refer to [`consul peering establish` command](/commands/peering/establish) . - +You can run the `peering establish` command 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. - + - 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**. + - +1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**. +2. Click **Establish peering**. +3. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. +4. Click **Add peer**. + + ### Export services between clusters @@ -521,5 +521,4 @@ spec: ``` - \ No newline at end of file From c1f71e3ef82c5c0c121de10cf280f082a32599e2 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 4 Oct 2022 10:34:42 -0500 Subject: [PATCH 23/23] list --- .../connect/cluster-peering/create-manage-peering.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 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 1a6b682000..d410bfc613 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -123,9 +123,9 @@ If you need to re-establish a connection, you must generate a new peering token. 1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**. -2. Click **Establish peering**. -3. In the **Name of peer** field, enter `cluster-01`. Then paste the peering token in the **Token** field. -4. Click **Add peer**. +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**. @@ -377,7 +377,9 @@ Next to the name of the peer, click **More** (three horizontal dots) and then ** ## L7 traffic management between peers + The following sections describe how to enable L7 traffic management features between peered clusters. + ### Service resolvers for redirects and failover As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures.