Skip to content

Commit 538928c

Browse files
claudioloraleoli
claudiolor
authored and
aleoli
committed
Docs: Minor fixes to the inter-cluster network page
1 parent 30811df commit 538928c

File tree

1 file changed

+114
-90
lines changed

1 file changed

+114
-90
lines changed

‎docs/advanced/peering/inter-cluster-network.md‎

Lines changed: 114 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -31,19 +31,22 @@ When you have access to both clusters, you can configure the network connectivit
3131
First, you need to initialize the network:
3232

3333
```bash
34-
liqoctl network init --kubeconfig PATH_TO_CLUSTER_1_KUBECONFIG --remote-kubeconfig PATH_TO_CLUSTER_2_KUBECONFIG --wait
34+
liqoctl network init \
35+
--kubeconfig $CLUSTER_1_KUBECONFIG_PATH \
36+
--remote-kubeconfig $CLUSTER_2_KUBECONFIG_PATH \
37+
--wait
3538
```
3639

3740
You should see the following output:
3841

3942
```text
40-
INFO (local) Cluster identity correctly retrieved
41-
INFO (remote) Cluster identity correctly retrieved
42-
INFO (local) Network configuration correctly retrieved
43-
INFO (remote) Network configuration correctly retrieved
44-
INFO (local) Network configuration correctly set up
45-
INFO (remote) Network configuration correctly set up
46-
INFO (local) Configuration applied successfully
43+
INFO (local) Cluster identity correctly retrieved
44+
INFO (remote) Cluster identity correctly retrieved
45+
INFO (local) Network configuration correctly retrieved
46+
INFO (remote) Network configuration correctly retrieved
47+
INFO (local) Network configuration correctly set up
48+
INFO (remote) Network configuration correctly set up
49+
INFO (local) Configuration applied successfully
4750
INFO (remote) Configuration applied successfully
4851
```
4952

@@ -52,14 +55,19 @@ You will find in both your clusters a new Configuration in the tenant namespace.
5255

5356
```bash
5457
kubectl get configurations.networking.liqo.io -A
58+
5559
NAMESPACE NAME DESIRED POD CIDR REMAPPED POD CIDR AGE
5660
liqo-tenant-dry-paper-5d16c0 dry-paper 10.243.0.0/16 10.71.0.0/16 4m48s
5761
```
5862

5963
Now, you can establish the connection between the two clusters:
6064

6165
```bash
62-
liqoctl network connect --kubeconfig PATH_TO_CLUSTER_1_KUBECONFIG --remote-kubeconfig PATH_TO_CLUSTER_2_KUBECONFIG --server-service-type NodePort --wait
66+
liqoctl network connect \
67+
--kubeconfig $CLUSTER_1_KUBECONFIG_PATH \
68+
--remote-kubeconfig $CLUSTER_2_KUBECONFIG_PATH \
69+
--server-service-type NodePort \
70+
--wait
6371
```
6472

6573
You should see the following output:
@@ -101,17 +109,17 @@ kubectl get gatewayclients.networking.liqo.io -A
101109
```
102110

103111
```text
104-
NAMESPACE NAME TEMPLATE NAME IP PORT AGE
105-
liqo-tenant-crimson-field-46ec75 crimson-field wireguard-client 10.42.3.54 30316 61s
112+
NAMESPACE NAME TEMPLATE NAME IP PORT AGE
113+
liqo-tenant-cl02 cl02 wireguard-client 172.19.0.8 32009 28s
106114
```
107115

108116
```bash
109117
kubectl get connections.networking.liqo.io -A
110118
```
111119

112120
```text
113-
NAMESPACE NAME TYPE STATUS AGE
114-
liqo-tenant-crimson-field-46ec75 crimson-field Client Connected 76s
121+
NAMESPACE NAME TYPE STATUS AGE
122+
liqo-tenant-cl02 gw-cl02 Client Connected 76s
115123
```
116124

117125
In cluster 2 you will find the following resources:
@@ -121,17 +129,17 @@ kubectl get gatewayservers.networking.liqo.io -A
121129
```
122130

123131
```text
124-
NAMESPACE NAME TEMPLATE NAME IP PORT AGE
125-
liqo-tenant-dry-paper-5d16c0 dry-paper wireguard-server 10.42.3.54 30316 69s
132+
NAMESPACE NAME TEMPLATE NAME IP PORT AGE
133+
liqo-tenant-cl01 cl01 wireguard-server 172.19.0.8 32009 69s
126134
```
127135

128136
```bash
129137
kubectl get connections.networking.liqo.io -A
130138
```
131139

132140
```text
133-
NAMESPACE NAME TYPE STATUS AGE
134-
liqo-tenant-dry-paper-5d16c0 dry-paper Server Connected 51s
141+
NAMESPACE NAME TYPE STATUS AGE
142+
liqo-tenant-cl01 cl01 Server Connected 51s
135143
```
136144

137145
You can check the status of the connection to see if it is working correctly.
@@ -141,7 +149,9 @@ You can check the status of the connection to see if it is working correctly.
141149
You can remove the network connection between the two clusters with the following command:
142150

143151
```bash
144-
liqoctl network disconnect --kubeconfig PATH_TO_CLUSTER_1_KUBECONFIG --remote-kubeconfig PATH_TO_CLUSTER_2_KUBECONFIG --wait
152+
liqoctl network disconnect \
153+
--kubeconfig $CLUSTER_1_KUBECONFIG_PATH \
154+
--remote-kubeconfig $CLUSTER_2_KUBECONFIG_PATH --wait
145155
```
146156

147157
You should see the following output:
@@ -152,13 +162,16 @@ Are you sure you want to continue? [y/N]yes
152162
INFO (local) Cluster identity correctly retrieved
153163
INFO (remote) Cluster identity correctly retrieved
154164
INFO (local) Gateway client correctly deleted
155-
INFO (remote) Gateway server correctly deleted
165+
INFO (remote) Gateway server correctly deleted
156166
```
157167

158168
Optionally, you can remove the network configuration with the following command:
159169

160170
```bash
161-
liqoctl network reset --kubeconfig PATH_TO_CLUSTER_1_KUBECONFIG --remote-kubeconfig PATH_TO_CLUSTER_2_KUBECONFIG --wait
171+
liqoctl network reset \
172+
--kubeconfig $CLUSTER_1_KUBECONFIG_PATH \
173+
--remote-kubeconfig $CLUSTER_2_KUBECONFIG_PATH \
174+
--wait
162175
```
163176

164177
You should see the following output:
@@ -189,10 +202,16 @@ Use the `liqoctl network connect --help` command to see all the available option
189202
## Manual on single cluster
190203

191204
When you don't have access to both clusters, or you want to configure it in a declarative way, you can configure it by applying CRDs.
205+
The process consists of the following steps:
206+
207+
1. **Cluster client and server**: the clusters that need to connect have to exchange a `Configuration` resource, containing the `CIDR` of each remote cluster.
208+
2. **Cluster server**: one of the clusters defines a `GatewayServer`, which exposes a service acting as server for the inter-cluster communication.
209+
3. **Cluster client**: the other cluster defines a `GatewayClient` resource, which will configure a client that will connect to the gateway server exposed on the other cluster.
210+
4. **Cluster client and server**: the cluster client and server need to exchange the public keys to allow secure communication.
192211

193-
### Configuration CRDs
212+
### Definition of the network configuration (Configuration CRDs)
194213

195-
You need to apply in both clusters the **Configuration** resource:
214+
In this step, each cluster needs to exchange the network configuration. Therefore, you will need to apply in **both clusters** a `Configuration` resource, paying attention to apply in each cluster, the network configuration of the other one.
196215

197216
```yaml
198217
apiVersion: networking.liqo.io/v1beta1
@@ -208,10 +227,17 @@ spec:
208227
pod: 10.243.0.0/16 # the pod CIDR of the remote cluster
209228
```
210229
211-
You can find *REMOTE_CLUSTER_ID* these parameters in the output of the `kubectl get configmaps -n liqo liqo-clusterid-configmap --template {{.data.CLUSTER_ID}}` command in the remote cluster.
230+
You can find *REMOTE_CLUSTER_ID* these parameters in the output of the
231+
232+
```bash
233+
kubectl get configmaps -n liqo liqo-clusterid-configmap \
234+
--template {{.data.CLUSTER_ID}}
235+
```
236+
237+
command in the remote cluster.
212238

213239
```{admonition} Tip
214-
You can generate this file with the command `liqoctl generate configuration` run in the remote cluster.
240+
You can generate this file with the command `liqoctl generate configuration` executed in the remote cluster.
215241
```
216242

217243
```{important}
@@ -220,16 +246,17 @@ You need to apply this resource in both clusters.
220246

221247
### Gateway CRDs
222248

223-
#### Gateway Server
249+
#### Creation of a gateway server
224250

225-
Now, in the cluster that will expose the service and act as a server, you need to apply the **GatewayServer** resource:
251+
In the inter-cluster communication, one of the clusters will expose a gateway server, where a client on the other cluster will connect to.
252+
Therefore, in the cluster that will expose the service and act as a server, you need to apply the `GatewayServer` resource:
226253

227254
```yaml
228255
apiVersion: networking.liqo.io/v1beta1
229256
kind: GatewayServer
230257
metadata:
231258
labels:
232-
liqo.io/remote-cluster-id: <REMOTE_CLUSTER_ID> # the remote cluster ID
259+
liqo.io/remote-cluster-id: <CLIENT_CLUSTER_ID> # the remote cluster ID
233260
name: server
234261
spec:
235262
endpoint:
@@ -247,12 +274,13 @@ spec:
247274
You can generate this file with the following command, and then edit it:
248275
249276
``` bash
250-
liqoctl create gatewayserver server --remote-cluster-id <REMOTE_CLUSTER_ID> \
277+
liqoctl create gatewayserver server \
278+
--remote-cluster-id <CLIENT_CLUSTER_ID> \
251279
--service-type NodePort -o yaml
252280
```
253281
````
254282
255-
Some seconds after you will find an assigned IP and a port in the status of the GatewayServer resource:
283+
After some seconds, you will be able to see an IP address and a port assigned to the GatewayServer resource:
256284
257285
```bash
258286
kubectl get gatewayservers.networking.liqo.io -A
@@ -271,17 +299,18 @@ kubectl get gatewayservers --template {{.status.endpoint}}
271299
map[addresses:[172.19.0.9] port:32701 protocol:UDP]
272300
```
273301
274-
#### Gateway Client
302+
#### Creation of a gateway client
275303
276-
Now, in the cluster that will connect to the service and act as a client, you need to apply the **GatewayClient** resource:
304+
The other cluster will need to connect to the gateway server and act as a client.
305+
To configure the client, you need to apply the GatewayClient resource, containing the IP address and port where the `GatewayServer` is reachable and all the parameters required for the connection to the server:
277306
278307
```yaml
279308
apiVersion: networking.liqo.io/v1beta1
280309
kind: GatewayClient
281310
metadata:
282311
creationTimestamp: null
283312
labels:
284-
liqo.io/remote-cluster-id: <REMOTE_CLUSTER_ID> # the remote cluster ID
313+
liqo.io/remote-cluster-id: <SERVER_CLUSTER_ID> # the remote cluster ID
285314
name: client
286315
namespace: default
287316
spec:
@@ -304,14 +333,14 @@ The *REMOTE_IP* and *REMOTE_PORT* are the IP and the port of the GatewayServer s
304333
You can generate this file with the command:
305334
306335
``` bash
307-
liqoctl create gatewayclient client --remote-cluster-id <REMOTE_CLUSTER_ID> \
336+
liqoctl create gatewayclient client --remote-cluster-id <SERVER_CLUSTER_ID> \
308337
--addresses <REMOTE_IP> --port <REMOTE_PORT> -o yaml
309338
```
310339
````
311340

312-
### Public keys CRDs
341+
### Public keys exchange (PublicKey CRDs)
313342

314-
Finally, you need to exchange the **public keys** between the two clusters.
343+
Finally, to allow secure communication between the clusters, they need to generate a key pair and exchange the **public key**.
315344

316345
In the client cluster, you will run the following command:
317346

@@ -327,9 +356,9 @@ kind: PublicKey
327356
metadata:
328357
creationTimestamp: null
329358
labels:
330-
liqo.io/remote-cluster-id: <REMOTE_CLUSTER_ID> # the remote cluster ID
359+
liqo.io/remote-cluster-id: <CLIENT_CLUSTER_ID> # the remote cluster ID
331360
networking.liqo.io/gateway-resource: "true"
332-
name: dry-paper
361+
name: <CLIENT_CLUSTER_ID>
333362
spec:
334363
publicKey: <PUBLIC_KEY>
335364
```
@@ -350,9 +379,9 @@ kind: PublicKey
350379
metadata:
351380
creationTimestamp: null
352381
labels:
353-
liqo.io/remote-cluster-id: <REMOTE_CLUSTER_ID> # the remote cluster ID
382+
liqo.io/remote-cluster-id: <SERVER_CLUSTER_ID> # the remote cluster ID
354383
networking.liqo.io/gateway-resource: "true"
355-
name: crimson-field
384+
name: <SERVER_CLUSTER_ID>
356385
spec:
357386
publicKey: <PUBLIC_KEY>
358387
```
@@ -373,83 +402,78 @@ On the server cluster, you will see:
373402

374403
```text
375404
NAMESPACE NAME TYPE STATUS AGE
376-
default <REMOTE_CLUSTER_ID> Server Connected 2m
405+
default <CLIENT_CLUSTER_ID> Server Connected 2m
377406
```
378407

379408
On the client cluster, you will see:
380409

381410
```text
382411
NAMESPACE NAME TYPE STATUS AGE
383-
default <REMOTE_CLUSTER_ID> Client Connected 2m
412+
default <SERVER_CLUSTER_ID> Client Connected 2m
384413
```
385414

386415
### Summary
387416

388-
Resuming, you can implement the network connectivity between two clusters with these steps:
417+
Resuming, these are the steps to be followed by the administrators of each of the clusters to manually complete the configuration of the inter-cluster network:
389418

390-
Export the kubeconfigs environment variables:
419+
1. **Cluster client**: creates the configuration to be given to the **cluster server** administrator:
391420

392-
```bash
393-
export KUBE_SERVER=PATH_TO_CLUSTER_1_KUBECONFIG
394-
export KUBE_CLIENT=PATH_TO_CLUSTER_2_KUBECONFIG
395-
```
421+
```bash
422+
liqoctl generate configuration > conf-client.yaml
423+
```
396424

397-
Create the Configuration resources and apply them:
425+
2. **Cluster server**: applies the client configuration and generates its own to be applied by the **cluster client**:
398426

399-
```bash
400-
liqoctl --kubeconfig $KUBE_SERVER generate configuration > conf-server.yaml
401-
liqoctl --kubeconfig $KUBE_CLIENT generate configuration > conf-client.yaml
427+
```bash
428+
kubectl apply -f conf-client.yaml
429+
liqoctl generate configuration > conf-server.yaml
430+
```
402431

403-
kubectl --kubeconfig $KUBE_SERVER apply -f conf-client.yaml
404-
kubectl --kubeconfig $KUBE_CLIENT apply -f conf-server.yaml
405-
```
432+
3. **Cluster client**: applies the server configuration:
406433

407-
Get the cluster IDs:
434+
```bash
435+
kubectl apply -f server-client.yaml
436+
```
408437

409-
```bash
410-
CLUSTER_ID_SERVER=$(kubectl get --kubeconfig $KUBE_SERVER -n liqo configmaps \
411-
liqo-clusterid-configmap -o json | jq -r '.data.CLUSTER_ID')
412-
CLUSTER_ID_CLIENT=$(kubectl get --kubeconfig $KUBE_CLIENT -n liqo configmaps \
413-
liqo-clusterid-configmap -o json | jq -r '.data.CLUSTER_ID')
414-
```
438+
4. **Cluster server**: sets up the `GatewayServer` and provides to the cluster client administrator port and address where the server is reachable:
415439

416-
Create the Gateway resources and apply them:
440+
```bash
441+
liqoctl create gatewayserver server \
442+
--remote-cluster-id $CLUSTER_ID_CLIENT \
443+
--service-type NodePort
444+
```
417445

418-
```bash
419-
liqoctl --kubeconfig $KUBE_SERVER create gatewayserver server \
420-
--remote-cluster-id $CLUSTER_ID_CLIENT --service-type NodePort
446+
5. **Cluster client**: Sets up the client that connects to the `GatewayServer`:
421447

422-
kubectl wait --for jsonpath='{.status.endpoint.addresses[0]}' gatewayserver server \
423-
--timeout=300s --kubeconfig $KUBE_SERVER
424-
kubectl wait --for jsonpath='{.status.endpoint.port}' gatewayserver server \
425-
--timeout=300s --kubeconfig $KUBE_SERVER
426-
kubectl wait --for jsonpath='{.status.internalEndpoint.ip}' gatewayserver server \
427-
--timeout=300s --kubeconfig $KUBE_SERVER
448+
```bash
449+
liqoctl create gatewayclient client \
450+
--remote-cluster-id $CLUSTER_ID_SERVER \
451+
--addresses $ADDRESS_SERVER \
452+
--port $PORT_SERVER
453+
```
428454

429-
ADDRESS_SERVER=$(kubectl --kubeconfig $KUBE_SERVER get gatewayserver server \
430-
-o json | jq -r '.status.endpoint.addresses[0]')
431-
PORT_SERVER=$(kubectl --kubeconfig $KUBE_SERVER get gatewayserver server \
432-
-o json | jq -r '.status.endpoint.port')
455+
6. **Cluster server**: generates a key pair and generates a `PublicKey` resource to be applied by the **cluster client**:
433456

434-
liqoctl --kubeconfig $KUBE_CLIENT create gatewayclient client \
435-
--remote-cluster-id $CLUSTER_ID_SERVER \
436-
--addresses $ADDRESS_SERVER --port $PORT_SERVER
457+
```bash
458+
liqoctl generate publickey \
459+
--gateway-type server \
460+
--gateway-name server > publickey-server.yaml
461+
```
437462

438-
kubectl wait --for jsonpath='{.status.internalEndpoint.ip}' gatewayclient client \
439-
--timeout=300s --kubeconfig $KUBE_CLIENT
440-
```
463+
7. **Cluster client**: applies the `PublicKey` resource of the server and generates its own:
441464

442-
Create the public keys and apply them:
465+
```bash
466+
kubectl apply -f publickey-server.yaml
467+
liqoctl generate publickey \
468+
--gateway-type client \
469+
--gateway-name client > publickey-client.yaml
470+
```
443471

444-
```bash
445-
liqoctl --kubeconfig $KUBE_SERVER generate publickey --gateway-type server \
446-
--gateway-name server > publickey-server.yaml
447-
liqoctl --kubeconfig $KUBE_CLIENT generate publickey --gateway-type client \
448-
--gateway-name client > publickey-client.yaml
472+
8. **Cluster server**: applies the `PublicKey` resource of the client:
449473

450-
kubectl --kubeconfig $KUBE_SERVER apply -f publickey-client.yaml
451-
kubectl --kubeconfig $KUBE_CLIENT apply -f publickey-server.yaml
452-
```
474+
```bash
475+
kubectl apply -f publickey-client.yaml
476+
```
453477

454478
## Custom templates
455479

0 commit comments

Comments
 (0)