You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/content/docs/connect/cluster-peering/tech-specs.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,7 +58,7 @@ The `exported-services` configuration entry is required in order for services to
58
58
59
59
Basic guidance on using the `exported-services` configuration entry is included in [Establish cluster peering connections](/consul/docs/connect/cluster-peering/usage/create-cluster-peering).
60
60
61
-
Refer to the [`exported-services`](/consul/docs/connect/config-entries/exported-services) configuration entry reference for more information.
61
+
Refer to the [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services) reference for more information.
Copy file name to clipboardExpand all lines: website/content/docs/connect/cluster-peering/usage/establish-cluster-peering.mdx
+31-33Lines changed: 31 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ description: >-
7
7
8
8
# Establish cluster peering connections
9
9
10
-
This page details the process for establishing a cluster peering connection between services deployed to different datacenters. You can interact with Consul's cluster peering features using the HTTP API, the CLI, or the UI. The overall process for establishing a cluster peering connection consists of the following steps:
10
+
This page details the process for establishing a cluster peering connection between services deployed to different datacenters. You can interact with Consul's cluster peering features using the CLI, the HTTP API, or the UI. The overall process for establishing a cluster peering connection consists of the following steps:
11
11
12
12
1. Create a peering token in one cluster.
13
13
1. Use the peering token to establish peering with a second cluster.
@@ -16,6 +16,8 @@ This page details the process for establishing a cluster peering connection betw
16
16
17
17
Cluster peering between services cannot be established until all four steps are complete.
18
18
19
+
For Kubernetes-specific guidance for establishing cluster peering connections, refer to [Establish cluster peering connections on Kubernetes](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering).
20
+
19
21
## Requirements
20
22
21
23
You must meet the following requirements to use cluster peering:
@@ -40,6 +42,19 @@ To begin the cluster peering process, generate a peering token in one of your cl
40
42
Every time you generate a peering token, a single-use secret for establishing the 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.
41
43
42
44
<Tabs>
45
+
<Tabheading="Consul CLI"group="cli">
46
+
47
+
1. In `cluster-01`, use the [`consul peering generate-token` command](/consul/commands/peering/generate-token) to issue a request for a peering token.
48
+
49
+
```shell-session
50
+
$ consul peering generate-token -name cluster-02
51
+
```
52
+
53
+
The CLI outputs the peering token, which is a base64-encoded string containing the token details.
54
+
55
+
1. Save this value to a file or clipboard to use in the next step on `cluster-02`.
56
+
57
+
</Tab>
43
58
<Tabheading="HTTP API"group="api">
44
59
45
60
1. In `cluster-01`, use the [`/peering/token` endpoint](/consul/api-docs/peering#generate-a-peering-token) to issue a request for a peering token.
@@ -64,21 +79,6 @@ Every time you generate a peering token, a single-use secret for establishing th
64
79
</CodeBlockConfig>
65
80
66
81
</Tab>
67
-
68
-
<Tabheading="Consul CLI"group="cli">
69
-
70
-
1. In `cluster-01`, use the [`consul peering generate-token` command](/consul/commands/peering/generate-token) to issue a request for a peering token.
71
-
72
-
```shell-session
73
-
$ consul peering generate-token -name cluster-02
74
-
```
75
-
76
-
The CLI outputs the peering token, which is a base64-encoded string containing the token details.
77
-
78
-
1. Save this value to a file or clipboard to use in the next step on `cluster-02`.
79
-
80
-
</Tab>
81
-
82
82
<Tabheading="Consul UI"group="ui">
83
83
84
84
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.
@@ -99,32 +99,31 @@ Every time you generate a peering token, a single-use secret for establishing th
99
99
Next, use the peering token to establish a secure connection between the clusters.
100
100
101
101
<Tabs>
102
-
<Tabheading="HTTP API"group="api">
102
+
<Tabheading="Consul CLI"group="cli">
103
103
104
-
1. In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish`endpoint](/consul/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error.
104
+
1. In one of the client agents deployed to "cluster-02," issue the [`consul peeringestablish`command](/consul/commands/peering/establish) and specify the token generated in the previous step.
105
105
106
106
```shell-session
107
-
$ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish
107
+
$ consul peering establish -name cluster-01 -peering-token token-from-generate
108
+
"Successfully established peering connection with cluster-01"
108
109
```
109
110
110
-
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](/consul/api-docs/peering).
111
+
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](/consul/commands/peering/establish).
111
112
112
-
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.
113
+
You can run the `peeringestablish`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.
113
114
114
115
</Tab>
116
+
<Tabheading="HTTP API"group="api">
115
117
116
-
<Tabheading="Consul CLI"group="cli">
117
-
118
-
1. In one of the client agents deployed to "cluster-02," issue the [`consul peering establish` command](/consul/commands/peering/establish) and specify the token generated in the previous step.
118
+
1. In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish` endpoint](/consul/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error.
119
119
120
120
```shell-session
121
-
$ consul peering establish -name cluster-01 -peering-token token-from-generate
122
-
"Successfully established peering connection with cluster-01"
121
+
$ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish
123
122
```
124
123
125
-
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](/consul/commands/peering/establish).
124
+
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](/consul/api-docs/peering).
126
125
127
-
You can run the `peeringestablish`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.
126
+
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.
128
127
129
128
</Tab>
130
129
@@ -194,7 +193,7 @@ Before you can call services from peered clusters, you must set service intentio
194
193
You must use the HTTP API or the Consul CLI to complete this step. The Consul UI supports intentions for local clusters only.
195
194
196
195
<Tabs>
197
-
<Tabheading="HTTP API"group="api">
196
+
<Tabheading="Consul CLI"group="cli">
198
197
199
198
1. Create a configuration entry and specify the `Kind` as `"service-intentions"`. Declare the service on "cluster-02" that can access the service in "cluster-01." In the following example, the service intentions configuration entry authorizes the `backend-service` to communicate with the `frontend-service` that is hosted on remote peer `cluster-02`:
200
199
@@ -220,12 +219,11 @@ You must use the HTTP API or the Consul CLI to complete this step. The Consul UI
220
219
1. Add the configuration entry to your cluster.
221
220
222
221
```shell-session
223
-
$ curl --request PUT --data @peering-intentions.hcl http://127.0.0.1:8500/v1/config
222
+
$ consul config write peering-intentions.hcl
224
223
```
225
224
226
225
</Tab>
227
-
228
-
<Tabheading="Consul CLI"group="cli">
226
+
<Tabheading="HTTP API"group="api">
229
227
230
228
1. Create a configuration entry and specify the `Kind` as `"service-intentions"`. Declare the service on "cluster-02" that can access the service in "cluster-01." In the following example, the service intentions configuration entry authorizes the `backend-service` to communicate with the `frontend-service` that is hosted on remote peer `cluster-02`:
231
229
@@ -251,7 +249,7 @@ You must use the HTTP API or the Consul CLI to complete this step. The Consul UI
251
249
1. Add the configuration entry to your cluster.
252
250
253
251
```shell-session
254
-
$ consul config write peering-intentions.hcl
252
+
$ curl --request PUT --data @peering-intentions.hcl http://127.0.0.1:8500/v1/config
Copy file name to clipboardExpand all lines: website/content/docs/connect/cluster-peering/usage/manage-connections.mdx
+28-33Lines changed: 28 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,28 +7,17 @@ description: >-
7
7
8
8
# Manage cluster peering connections
9
9
10
-
This usage topic describes how to manage cluster peering connections using the HTTP API, the CLI, and the UI.
10
+
This usage topic describes how to manage cluster peering connections using the CLI, the HTTP API, and the UI.
11
11
12
12
After you establish a cluster peering connection, you can get a list of all active peering connections, read a specific peering connection's information, and delete peering connections.
13
13
14
+
For Kubernetes-specific guidance for managing cluster peering connections, refer to [Manage cluster peering connections on Kubernetes](/consul/docs/k8s/connect/cluster-peering/usage/manage-peering).
15
+
14
16
## List all peering connections
15
17
16
18
You can list all active peering connections in a cluster.
17
19
18
20
<Tabs>
19
-
20
-
<Tabheading="HTTP API"group="api">
21
-
22
-
The following example shows how to format an API request to list peering connections:
For more information, including optional parameters and sample responses, refer to the [`/peering` endpoint reference](/consul/api-docs/peering#list-all-peerings).
29
-
30
-
</Tab>
31
-
32
21
<Tabheading="Consul CLI"group="cli">
33
22
34
23
```shell-session
@@ -41,7 +30,17 @@ For more information, including optional parameters and sample responses, refer
41
30
For more information, including optional flags and parameters, refer to the [`consul peering list` CLI command reference](/consul/commands/peering/list).
42
31
43
32
</Tab>
33
+
<Tabheading="HTTP API"group="api">
44
34
35
+
The following example shows how to format an API request to list peering connections:
For more information, including optional parameters and sample responses, refer to the [`/peering` endpoint reference](/consul/api-docs/peering#list-all-peerings).
42
+
43
+
</Tab>
45
44
<Tabheading="Consul UI"group="ui">
46
45
47
46
In the Consul UI, click **Peers**.
@@ -57,16 +56,6 @@ You can get information about individual peering connections between clusters.
For more information, including optional parameters and sample responses, refer to the [`/peering` endpoint reference](/consul/api-docs/peering#read-a-peering-connection).
67
-
68
-
</Tab>
69
-
70
59
<Tabheading="Consul CLI"group="cli">
71
60
72
61
The following example outputs information about a peering connection locally referred to as "cluster-02":
@@ -95,7 +84,15 @@ The following example outputs information about a peering connection locally ref
95
84
For more information, including optional flags and parameters, refer to the [`consul peering read` CLI command reference](/consul/commands/peering/read).
For more information, including optional parameters and sample responses, refer to the [`/peering` endpoint reference](/consul/api-docs/peering#read-a-peering-connection).
94
+
95
+
</Tab>
99
96
<Tabheading="Consul UI"group="ui">
100
97
101
98
1. In the Consul UI, click **Peers**.
@@ -110,15 +107,6 @@ For more information, including optional flags and parameters, refer to the [`co
110
107
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.
This endpoint does not return a response. For more information, including optional parameters, refer to the [`/peering` endpoint reference](/consul/api-docs/peering/consul/api-docs/peering#delete-a-peering-connection).
120
-
</Tab>
121
-
122
110
<Tabheading="Consul CLI"group="cli">
123
111
124
112
The following examples deletes a peering connection to a cluster locally referred to as "cluster-02":
@@ -131,7 +119,14 @@ This endpoint does not return a response. For more information, including option
131
119
For more information, including optional flags and parameters, refer to the [`consul peering delete` CLI command reference](/consul/commands/peering/delete).
This endpoint does not return a response. For more information, including optional parameters, refer to the [`/peering` endpoint reference](/consul/api-docs/peering/consul/api-docs/peering#delete-a-peering-connection).
129
+
</Tab>
135
130
<Tabheading="Consul UI"group="ui">
136
131
137
132
1. In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter.
0 commit comments