Create and Manage Peering Connections page

website/content/docs/connect/cluster-peering/create-manage-peering.mdx

@@ -1,8 +1,144 @@
 ---
 layout: docs
 page_title: Create and Manage Peering Connections
-description: |-
-
+description: >-
+    This page describes how to use the Consul CLI to create, manage, and delete peering connections for cluster peering.
 ---
 
 # Create and Manage Peering Connections
+
+~> This page covers features that are currently in _technical preview_. Features and functionality are subject to change. You should never use the technical preview release in secure environments or production scenarios. Features in technical preview may face performance and scaling issues, with limited support options available.
+
+A peering token enables cluster peering between different datacenters. Once you generate a peering token, you can use it to initiate a connection between clusters. Then you can export services and authorize other clusters to call those services.
+
+To peer clusters, you must complete the following steps in order:
+
+1. Create a peering token
+1. Establish a connection between clusters
+1. Connect service endpoints
+1. Authorize connections between peers
+
+## Create a peering token
+
+You can generate peering tokens and initiate connections from either the server agents or the client agents in your clusters. For the current release, we recommend you initiate peering through the client agents in the partitions 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,” run the ``generate-token`` command.
+
+```shell-session
+$ consul peering generate-token -peer="cluster-02"
+```
+
+The CLI outputs the peering token, which is a string of alphanumeric characters and symbols.
+
+For the peering token to function correctly, you must enter the second cluster’s exact name in the ``peer`` parameter.
+
+## 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,” run the ``peering initiate`` command. This command does not generate an output.
+
+```shell-session
+$ consul peering initiate -peer="cluster-01" -token="eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImF1ZCI6IlNvbHIifQ.5T7L_L1MPfQ_5FjKGa1fTPqrzwK4bNSM812nW6oyjb8"
+```
+
+In the peer parameter, specify the first cluster’s exact name. The ``token`` parameter should include the entire peering token created in the first cluster.
+
+When you connect server agents through cluster peering, they will peer through their default partitions. To connect other partitions through server agents, you must specify the partitions you want to peer using the ``partition`` parameter.
+
+## Connect service endpoints
+
+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 make services, queries, and key/value stores available to peered clusters.
+
+First, create a configuration entry and specify the ``Kind`` as ``“exported-services”``.
+
+<CodeBlockConfig filename="peering-config.hcl">
+
+```shell-session
+Kind = "exported-services"
+Partition = "partition-name"
+
+Services = [
+  {
+    ## The name and namespace of the service to export.
+    Name      = "service-name"
+    Namespace = "default"
+
+    ## The list of peer clusters to export the service to.
+    Consumers = [
+      {
+        ## The peer name to reference in config is the one set
+        ## during the peering process.
+        Peer = "cluster-02"
+      }
+    ]
+```
+
+</CodeBlockConfig>
+
+Then, add the configuration entry to your cluster.
+
+```shell-session
+$ consul config write peering-config.hcl
+```
+
+Before you proceed, wait for the clusters to sync and make services available to their peers
+
+### Check peering connection status
+
+To find issues blocking the cluster peering, you can call the ``/health/service`` HTTP endpoint.
+
+```shell-session
+$ curl \
+    http://127.0.0.1:8500/v1/health/service/service-name?peer=cluster-01
+```
+
+You can also check the status of the data replication to the peer cluster.
+```shell-session
+$ curl \
+    http://127.0.0.1:8500/v1/peering/cluster-01
+```
+
+If the cluster peering process is successful, the output returns both ``"status": "active"`` and ``"connected": true``.
+
+## Authorize connections from 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”``.
+
+<CodeBlockConfig filename="peering-intentions.hcl">
+
+```shell-session
+Kind      = "service-intentions"
+Name      = "service-name"
+Partition = "partition-name"
+
+Sources = [
+  {
+    Name   = "orders"
+    Peer   = "cluster-02"
+    Action = "allow"
+  }
+]
+```
+
+</CodeBlockConfig>
+
+**Tip:** If the peer’s name is not specified in ``Peer``, then Consul assumes that the service is in the local cluster.
+
+Then, add the configuration entry to your cluster.
+
+```shell-session
+$ consul config write peering-intentions.hcl
+```
+
+## Remove peering connections
+
+After you create a peering connection between clusters in different datacenters, you can “unpeer” the connected clusters. Deleting a peering connection stops data replication to the peer and deletes imported data, including services and CA certificates.
+
+In “cluster-01,” run the ``peering delete`` command.
+
+```shell-session
+$ consul peering delete -peer="cluster-02"
+```