docs: improve NAT and manual peering documentation

Author: claudiolor

docs/_static/images/advanced/nat/provider_nat.png

@@ -1,5 +1,21 @@
 # Manual peering
 
+In the [peer two clusters](../usage/peer.md) section of this documentation, we used the `liqoctl peer`, which automatically configure each single module of Liqo to create a peering between two clusters. However, this command can be used when:
+
+- the user is willing to use `liqoctl` to create the peerings between the clusters
+- all Liqo modules need to be used and configured
+- the cluster acting as provider can expose the service for the Wireguard gateway server that the client can reach
+- a single ResourceSlice (request for resources) backed by a single VirtualNode is enough
+
+Whenever you need a different configuration, like, for example:
+
+- you want to configure Liqo peerings via a [declarative approach](./peering/peering-via-cr.md) via CRs.
+- the networking module is not required, either because the inter-cluster networking is not needed or because networking is provided by a third party
+- it is required to configure the WireGuard gateway server on the cluster consumer (e.g. the nodes of the cluster provider are [behind a NAT](./nat.md))
+- The consumer needs to create multiple requests for resources (ResourceSlice) or you want to customize the way resources are distributed on virtual nodes
+
+then, you will need to set up the peering with the cluster, by configuring each single module separatly.
+
 In this section, you will discover how to interact with each Liqo module without using the automatic peering method.
 
 ## Prerequirements

docs/advanced/manual-peering.md

@@ -1,14 +1,57 @@
-# NAT Firewall
+# Configure a Liqo gateway server behind a NAT
 
-In Case a **gateway server** is behind a NAT firewall, the following steps are required to establish the connection:
-You can configure the settings for the connection by setting the following *annotations* in the `values.yaml` file or by using the `liqoctl` command line `--set` option:
+There might be some cases, especially when working in lab environments, where **it is not possible to configure the gateway server service as `LoadBalancer`**, and it should be configured via a `NodePort` service.
+However, the nodes of the cluster might not be directly reachable, as for example, they are behind a NAT.
 
-Under the `networking.gatewayTemplates.server.service.annotations` key, you can set the following annotations:
+In such cases, it is not possible to configure the Liqo peering directly with the `liqoctl peer` command, as the gateway client would point to the internal address and port of the server gateway.
 
-* **liqo.io/override-address**: the public IP address of the NAT firewall.
-* **liqo.io/override-port**: the public port of the NAT firewall.
+In this documentation page, we are going to describe how to configure Liqo in this kind of cases.
 
-```{admonition} Tip
-In case you need to have multiple gateways behind the same NAT firewall, you need to override the port for each peer using the `--server-port` flag at peering time.
-This flag works with `liqoctl peer` and `liqoctl network connect` commands.
+## Case A: Use a NodePort service with the provider cluster behind a NAT and client directly reachable
+
+![The provider is behind a NAT](../_static/images/advanced/nat/provider_nat.png)
+
+There might be the case in which the cluster provider nodes are not directly reachable, as for example they are behind a NAT, while the consumer can be directly reached.
+
+By default using the `peer` command, the gateway server is configured on the provider cluster, which, in this case, is not directly reachable, as behind the NAT.
+To fix this issue, we can swap the roles of the gateways, configuring the client on the cluster provider and the server on the consumer.
+To do so, you need to use [manual peering](./manual-peering.md), setting the inter-cluster network up separately.
+
+This solution allows to configure the Liqo networking without the need to configure port-mapping on the NAT, as we moved the gateway server on the nodes that are directly reachable.
+
+In the case you would like to keep the gateway server on the provider, you can follow the instructions on the next paragraph.
+
+## Case B: Use a NodePort service when both cluster provider and consumer are behind a NAT
+
+The solution presented in this section is valid when both consumer and provider clusters are reachable from an IP and a port different than the ones configured on the nodes of the clusters, for example, when they both are behind a NAT.
+
+In this case, **you must configure port-mapping on the NAT** so that the traffic directed on a specific port of the NAT can be forwarded to one of nodes of the cluster.
+
+When network is configured via `liqoctl` commands, if the service is of type `NodePort`, Liqo automatically uses the external IPs of the nodes to configure the gateway client.
+You can force Liqo to use the public IP of the NAT and the port of the NAT where we configured port mapping, by providing some options at installation time.
+
+Create a `values.yaml` file like the following:
+
+```{code-block} yaml
+:caption: "values.yaml"
+networking:
+  gatewayTemplates:
+    server:
+      service:
+        annotations:
+          liqo.io/override-address: <NAT_ADDRESS>
+          liqo.io/override-port: <NAT_PORT>
+```
+
+Where:
+
+- **liqo.io/override-address** is the public IP address of the NAT firewall.
+- **liqo.io/override-port** is the public port of the NAT firewall where you configured port mapping.
+
+At this point you can pass this file to the `install` command:
+
+```bash
+liqoctl install <HERE_YOUR_PROVIDER> <ARG...> --values <PATH_TO>/values.yaml
 ```
+
+If you use [Helm to install Liqo](../installation/install.md#install-with-helm), you can add those fields in your own `values.yaml`.

docs/advanced/nat.md

@@ -26,9 +26,11 @@ The unpeer process will automatically remove the Liqo Gateway from the tenant na
 
 ## Manual on cluster couple
 
-When you have access to both clusters, you can configure the network connectivity for all the successive peering creations.
+When you have access to both clusters, you can configure the inter-cluster network connectivity via the `liqoctl network` command.
 
-First, you need to initialize the network:
+Note that when you use the `liqoctl network` command, the remote kubeconfig/context provided as argument, is the one of the cluster where we want to configure the server gateway of Wireguard tunnel.
+
+The first step to configure network is initializing the network:
 
 ```bash
 liqoctl network init \

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

@@ -29,7 +29,7 @@ Ensure you selected the correct target cluster before issuing *liqoctl* commands
 ## Requirements
 
 The peering command requires the user to provide the kubeconfig of **both** *consumer* and *provider* clusters, as it will apply resources on both clusters.
-To perform a peering without having access to both clusters, you need to manually apply on your cluster the resources and exchange with the remote cluster all the resources needed over out-of-band mediums (refer to the individual guides describing the procedure for each module).
+To perform a peering without having access to both clusters, you need to manually apply on your cluster the resources and exchange with the remote cluster all the resources needed over out-of-band mediums (refer to the [individual guides](../advanced/manual-peering.md) describing the procedure for each module).
 
 ## Performed steps