Docs: in-band docs refactored

Author: cheina97

docs/advanced/k8s-api-server-proxy.md

@@ -1,15 +1,21 @@
 # Kubernetes API Server Proxy
 
 The Kubernetes API Server Proxy is a Liqo component that allows you to expose the Kubernetes API Server of a cluster to a remote cluster through the Liqo network fabric.
-This feature is useful when you want to establish a peering relationship between two clusters, but you cannot expose the Kubernetes API Server to the public.
+
+This feature is **internally** used by the [in-band peering](UsagePeeringInBand) to establish a peering relationship between two clusters, which does not publicly expose the Kubernetes API Server.
+
+```{warning}
+If you just need to peer two clusters without publicly exposing the Kubernetes API server, you can use the [in-band peering](UsagePeeringInBand).
+```
 
 The Kubernetes API Server Proxy is an Envoy HTTP server that accepts [HTTP Connect](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT) requests and forwards them to the Kubernetes API Server of the local cluster.
-It has no permission on the local cluster, and the requesters must authenticate with the Kubernetes API Server to access the resources.
+It just proxy the requests to the API server and it has no permission on the local cluster.
+This means that, as usual, all the requesters must authenticate with the Kubernetes API Server to access the resources.
 
-The Kubernetes API Server Proxy is deployed as a Kubernetes deployment in the `liqo` namespace.
+By default the Kubernetes API Server Proxy is deployed as a Kubernetes deployment in the `liqo` namespace and it is exposed by a service, whose address is remapped by an `IP` CRD located in the `liqo` namespace.
+This allows another peer cluster to reach the Kubernetes API server of the peer even when this is not directly reachable, by passing through the **gateways tunnel** between the clusters, using the remapped IP.
 
-By default, its service is remapped by an `IP` CRD in the `liqo` namespace.
-You can get its IP address by running the following command:
+You can get this IP address by running the following command:
 
 ```bash
 kubectl get ip -n liqo api-server-proxy -o wide
@@ -20,6 +26,9 @@ NAME               LOCAL IP        AGE    REMAPPED IPS
 api-server-proxy   10.95.245.141   167m   {"wild-frog":"10.70.0.2"}
 ```
 
-Note that in order to use it in a remote cluster, you may need to remap it to a different IP address according to the remote cluster network configuration as explained in the [external IP remapping](ExternalIPRemappingConnectToExternalHost) page.
+Note that **the IP retrieved with the command above might not be used as is in a remote cluster, you may need to remap it** to a different IP address according to the remote cluster network configuration, as explained in the [external IP remapping](ExternalIPRemappingConnectToExternalHost) page.
+
+For example, let's suppose that a cluster `cl01` wants to reach the Kubernetes API Server Proxy of another cluster `cl02`.
 
-For example, if the `REMAPPED_EXT_CIDR` is *10.81.0.0/16* and the `REMAPPED_IP` is *10.70.0.3* the final IP will be *10.81.0.3*.
+Looking at the `Configuration` resource, we might see that, for example, the `REMAPPED_EXT_CIDR` is *10.81.0.0/16*, which means that the requests directed to that network will be redirected to cluster `cl01` and remmapped to the `cl02` external CIDR.
+Therefore, if the `REMAPPED_IP` of the `api-server-proxy` in `cl02` is *10.70.0.3*, the final IP to be used in `cl01` to reach the Kubernetes API Server Proxy will be *10.81.0.3*.

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

@@ -69,6 +69,15 @@ cl01   16m   Active
 
 Check the [offloading guide](/advanced/peering/offloading-in-depth) to understand how to start the pod offloading and the reflection of the resources.
 
+### In-Band
+
+If you can't make the Kubernetes API Server of the **Provider** cluster reachable from the **Consumer**, you can leverage on **in-band** peering.
+You can enable this by setting the `--in-band` flag in the `liqoctl authenticate` command, which automatically configure all the features needed for this mechanism to work (i.e., the API server proxy and the IP remapping).
+
+```{admonition} Note
+For this feature to work, the Liqo **networking module** must be enabled.
+```
+
 ### Undo the authentication
 
 `liqoctl unauthenticate` allows to undo the changes applied by the `authenticate` command. Even in this case, the user should be able to access both the involved clusters.
@@ -122,7 +131,7 @@ When successful the output of the command will be something like the following:
 ```
 
 ```{admonition} Tip
-**Take note of the nonce as it can will be used in the following step**.
+Take note of the **nonce** as it can will be used in the following step.
 ```
 
 As a result of this command, you should be able to see:
@@ -199,6 +208,11 @@ As a result of the command, you should be able to see:
   NAME                TYPE     DATA   AGE
   liqo-signed-nonce   Opaque   2      78s
   ```
+  
+```{admonition} Note
+If you want to use the [in-band](UsagePeeringInBand) approach, use the `spec.proxyURL` field inside the `Tenant` CRD. 
+Check the [Kubernetes API Server Proxy](/advanced/k8s-api-server-proxy.md) page
+```
 
 ### Creation of the Identity resource (cluster provider)
 

docs/features/peering.md

@@ -36,15 +36,11 @@ The approach is schematized at a high level in the figure below.
 
 ![Peering architecture](/_static/images/features/peering/peering-arch.drawio.svg)
 
-```{admonition} Note
+```{warning}
 The standard *liqoctl* peer command requires the machine running it to have simultaneous access to both cluster API servers, through their *kubeconfigs*.
 If this is not possible, refer to the advanced guide to learn how to perform the [peering manually](/advanced/manual-peering) without having contemporary access to both clusters.
 ```
 
-```{warning}
+```{admonition} Note
 The user can adopt different peering approaches depending if it has contemporary access to both clusters or not, as described in the [dedicated page](/advanced/peering-strategies.md). 
-
-If you cannot expose the Kubernetes API Server to the public, you can leverage the Liqo networking to connect to the remote Kubernetes API Server, and the related traffic will flow into the cross-cluster VPN tunnel by leveraging the [IP remapping](../advanced/external-ip-remapping.md) (of the `liqo-proxy` service) and the [Kubernetes API Server proxy](../advanced/k8s-api-server-proxy.md) features.
-You can achieve this by setting the `--in-band` flag in the `liqoctl peer` or `liqoctl authenticate` commands, which automatically configure all the features needed for this mechanism to work (i.e., the API server proxy and the IP remapping).
-Note that, for this feature to work, the Liqo networking module must be enabled.
 ```

docs/usage/peer.md

@@ -111,6 +111,17 @@ You should see the following output:
  INFO   (local) ResourceSlice resources: Accepted
 ```
 
+(UsagePeeringInBand)=
+
+### In-Band
+
+If you can't make the Kubernetes API Server of the **provider** cluster reachable from the **consumer**, you can leverage on **in-band** peering.
+You can enable this by setting the `--in-band` flag in the `liqoctl peer` command, which automatically configure all the features needed for this mechanism to work (i.e., the API server proxy and the IP remapping).
+
+```{admonition} Note
+For this feature to work, the Liqo **networking module** must be enabled.
+```
+
 ## Results
 
 The command configures the above-described modules.