Update README.md and Scenarios page

README.md

@@ -29,9 +29,8 @@
     <a href="https://github.com/liqotech/liqo/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFeature%5D">Request Feature</a>
 </p>
 
-
-
 ## About the project
+
 Liqo is a platform to enable dynamic and decentralized resource sharing across Kubernetes clusters, either on-prem or managed. Liqo allows to run pods on a remote cluster seamlessly and without any modification of Kubernetes and the applications. With Liqo it is possible to extend the control plane of a Kubernetes cluster across the cluster's boundaries, making multi-cluster native and transparent: collapse an entire remote cluster to a virtual local node, by allowing workloads offloading and resource management compliant with the standard Kubernetes approach.
 
 <br />
@@ -71,7 +70,7 @@ Liqo is a platform to enable dynamic and decentralized resource sharing across K
 
 This quickstart lets you try Liqo in a playground environment built by two clusters in [KinD](https://kind.sigs.k8s.io/).
 
-#### __Provision__ two KinD clusters.
+### __Provision__ two KinD clusters.
 
 ```bash
 source <(curl -L https://get.liqo.io/clusters.sh)
@@ -110,13 +109,24 @@ kubectl apply -f https://get.liqo.io/app.yaml -n liqo-demo
 You can observe that:
 
 * Your application is correctly working by exposing the application frontend port and later connecting with a browser to [localhost:8000](localhost:8000). To expose the pod port:
+
 ```bash
   kubectl port-forward -n liqo-demo service/frontend 8080:80
 ```
+
 * Your application is transparently deployed across two different clusters:
+
 ```bash
   kubectl get pods -n liqo-demo -o wide  
-``` 
+```
+
+### Going Further
+
+If you want to understand and get more details, including how to inspect and interact with a service deployed with Liqo, you can explore the documentation website:
+
+* Continue the Liqo journey by exploring the [Liqo playground](https://doc.liqo.io/user/gettingstarted/play/)
+* Find out how to install Liqo on [your clusters](https://doc.liqo.io/user/install/)
+* Read more about the [Liqo architecture](https://doc.liqo.io/architecture/)
 
 ## Installation
 
@@ -128,10 +138,10 @@ Once you identified your scenario, follow the instructions for the proper instal
 
 Planned features for the next release (v0.3, expected mid-July, 2021) are the following:
 
-* Support for deployments spanning across more than two clusters
-* Support for a more balanced scheduling mechanism to distribute jobs across clusters
-* Support for Amazon Elastic Kubernetes Service
-* Support for more-granular permission control over remote cluster resources
+* Support for deployments spanning across more than two clusters.
+* Support for a more balanced scheduling mechanism to distribute jobs across clusters.
+* Support for Amazon Elastic Kubernetes Service.
+* Support for more-granular permission control over remote cluster resources.
 
 ## Contributing
 

deployments/liqo/README.md

@@ -22,7 +22,7 @@
 | auth.pod.labels | object | `{}` | auth pod labels |
 | auth.portOverride | string | `""` | Overrides the port were your service is available, you should configure it if behind a NAT or using an Ingress with a port different from 443. |
 | auth.service.annotations | object | `{}` | auth service annotations |
-| auth.service.type | string | `"NodePort"` | The type of service used to expose the Authentication Service If you are exposing this service with an Ingress consider to change it to ClusterIP, otherwise if you plan to use liqo over the Internet consider to change this field to "LoadBalancer". See https://doc.liqo.io/user/scenarios/ for more details. |
+| auth.service.type | string | `"NodePort"` | The type of service used to expose the Authentication Service If you are exposing this service with an Ingress consider to change it to ClusterIP, otherwise if you plan to use liqo over the Internet consider to change this field to "LoadBalancer". See https://doc.liqo.io/user/pre-install/ for more details. |
 | auth.tls | bool | `true` | Enable TLS for the Authentication Service Pod (using a self-signed certificate). If you are exposing this service with an Ingress consider to disable it or add the appropriate annotations to the Ingress resource. |
 | crdReplicator.imageName | string | `"liqo/crd-replicator"` | crdReplicator image repository |
 | crdReplicator.pod.annotations | object | `{}` | crdReplicator pod annotations |

deployments/liqo/values.yaml

@@ -130,7 +130,7 @@ auth:
     # -- The type of service used to expose the Authentication Service
     # If you are exposing this service with an Ingress consider to change it to ClusterIP,
     # otherwise if you plan to use liqo over the Internet consider to change this field to "LoadBalancer".
-    # See https://doc.liqo.io/user/scenarios/ for more details.
+    # See https://doc.liqo.io/user/pre-install/ for more details.
     type: "NodePort"
     # -- auth service annotations
     annotations: {}

docs/pages/User/Install/_index.md

@@ -6,7 +6,7 @@ weight: 4
 ### Pre-Installation
 
 Liqo can be used with different topologies and scenarios. This impacts several installation parameters you will configure (e.g., API Server, Authentication). In
-the [scenarios pages](../scenarios), we present some common patterns used to expose and interconnect clusters.
+the [scenarios pages](./pre-install), we present some common patterns used to expose and interconnect clusters.
 
 ### Installation
 

docs/pages/User/Install/platforms/aks.md

@@ -9,7 +9,7 @@ Azure Kubernetes Service (AKS) is a managed Kubernetes service available on the
 
 #### Scenarios
 
-This guide will show you how to install Liqo on your AKS cluster. AKS clusters have by default an Internet-exposed API Server and can easily expose LoadBalancer services using public IPs. As discussed in [Scenarios](/user/scenarios) section, those latter are the requirements to have a "public-exposed" cluster, which can be accessed by other Liqo instances.
+This guide will show you how to install Liqo on your AKS cluster. AKS clusters have by default an Internet-exposed API Server and can easily expose LoadBalancer services using public IPs. As discussed in [Scenarios](/user/install/pre-install) section, those latter are the requirements to have a "public-exposed" cluster, which can be accessed by other Liqo instances.
 
 Liqo may be installed on newly created clusters or existing ones.
 

docs/pages/User/Install/platforms/gke.md

@@ -14,7 +14,7 @@ Google Kubernetes Engine (GKE) is a managed Kubernetes service available on the
 
 ### Scenarios
 
-This guide will show you how to install Liqo on your GKE cluster. GKE clusters have by default an Internet-exposed API Service and can easily expose LoadBalancer services. As discussed in [Scenarios](/user/scenarios) section, those latter are the requirements to have a "public-exposed" cluster, which can be accessed by other Liqo instances.
+This guide will show you how to install Liqo on your GKE cluster. GKE clusters have by default an Internet-exposed API Service and can easily expose LoadBalancer services. As discussed in [Scenarios](/user/install/pre-install) section, those latter are the requirements to have a "public-exposed" cluster, which can be accessed by other Liqo instances.
 
 Liqo may be installed on a newly created clusters or on existing ones.
 

docs/pages/User/Install/platforms/k8s.md

@@ -5,7 +5,8 @@ weight: 3
 
 ### About Kubeadm
 
-[Kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/) is a tool built by the Kubernetes community to provision Kubernetes clusters. Kubeadm is used as the basis of most Kubernetes deployments and makes it easier to create conformant clusters.
+[Kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/) is a tool built by the Kubernetes community to provision Kubernetes clusters. Kubeadm is used as the basis of most Kubernetes deployments and makes it easier to create K8s clusters.
+
 ### CNI Compatibility Matrix
 
 Kubeadm does not install any CNI plugin by default, and it must be deployed after the initialization of the cluster.

docs/pages/User/Install/pre-install.md

@@ -0,0 +1,78 @@
+---
+title: Pre-Install
+weight: 2
+---
+
+### Introduction
+
+Liqo can be installed either in private or local clusters. Its configuration depends on the type of connectivity between the two clusters. Before installing Liqo, you have to consider how your clusters can connect to each other and can peer together. 
+
+### Peering Requirements
+
+Liqo requires the following services to be reciprocally accessible on both clusters in order to be able to start the cluster peering:
+
+* **Authentication server**: Liqo service, used to authenticate incoming peering requests coming from other clusters (i.e., `liqo-auth`). To configure the authentication, you should modify the values in section ``auth`` in the [Liqo chart values](./chart_values).
+* **Kubernetes API server**: Kubernetes APIServer, where the (remote) Liqo instance will create some new resources when the peering process starts. APIServer can be configure in the ``apiServer`` section of the [Liqo chart values](./chart_values). By default, Liqo will use an endpoint composed by the IP of the first master and the 6443 port. In managed clusters, you have to mandatorily configure those values to have Liqo working correctly.
+* **Network gateway**: Liqo service responsible for setting up the inter-cluster connectivity between clusters (i.e., `liqo-gateway`). The Liqo Gateway is configured in the ``gateway`` section of the [Liqo chart values](./chart_values).
+
+Depending on the physical setup of your cluster, you need to properly configure some parameters required by Liqo during the install process in order to enable remote clusters to contact the above services. Below we present some common scenarios that Liqo can handle. Once you identify yours, you can go have to the *table* of each section to find the right values you should specify when installing Liqo using the chart.
+
+The following parameters can be configured at installation time using the [Liqo Helm Chart](./chart_values) and updated by issuing an ``helm update``, after having changed them in your values.yml. If you need more information about Helm and how charts can be configured, you can have a look to the [Helm official documentation](https://helm.sh/docs/). Pay attention that changing exposition parameters may affect and break active peerings. We suggest to disable all peerings before changing the way a cluster is exposed.
+
+### Cloud to cloud
+
+![](/images/scenarios/cloud-to-cloud.svg)
+
+Two managed clusters peered together through the internet. It is possible to have a multi-cloud setup (AKS to AKS, GKE to GKE, and AKS to GKE). In this scenario, the services to exposes should be exposed using Public IPs/URLs.
+
+|  | Cluster A (Cloud) | Cluster B (Cloud) |
+| --------- | -------- |  ---------       | |
+| **Auth Server** |  LoadBalancer/ingress | LoadBalancer/Ingress |
+| **API server** | Provided | Provided |
+| **Network gateway** | LoadBalancer/Node Port | LoadBalancer/Node Port |
+
+Considering the Network Gateway, at least one among Cluster A and Cluster B should have the **Network Gateway** IP accessible from the other one (e.g.; Public IP).
+
+### On-premise to cloud
+
+![](/images/scenarios/on-prem-to-cloud.svg)
+
+On-premise cluster (K3s or K8s) exposed through the Internet peered with a Managed cluster (AKS or GKE).
+
+|  | Cluster A (On-prem) | Cluster B (Cloud) |
+| --------- | -------- |  ---------       |
+| **Auth Server** |  LoadBalancer/Ingress | LoadBalancer/Ingress |
+| **API server** | Ingress/Public IP | Provided |
+| **Network gateway** | LoadBalancer/Node Port | LoadBalancer/Node Port |
+
+Clusters API Server should be mutually accessible and so should be for the Auth Service.
+Considering the Network Gateway, at least one among Cluster A and Cluster B should have the **Network Gateway** IP accessible from the other one (e.g.; Public IP). If you configure the Auth service as Ingress, you should pay attention to disable TLS on the service or, more safely, to configure your Ingress Controller to support a TLS backend.
+
+#### On-premise behind NAT to cloud
+
+![](/images/scenarios/on-prem-nat-to-cloud.svg)
+
+When the On-premise cluster is exposed through a NAT, the configuration slightly changes:
+
+|  | Cluster A (On-prem behind NAT) | Cluster B (Cloud) |
+| --------- | -------- |  ---------       |
+| **Auth Server** |  NodePort with port-forwarding | LoadBalancer/ingress |
+| **API server** | Port-forwarding | Provided |
+| **Network gateway** | NodePort with port-forwarding | LoadBalancer |
+
+In this situation, the "cloud" cluster should have the Network Gateway exposed as a **LoadBalancer**. A couple of port-forwardings should be also configured for the Auth Server and K8s API Server to make them accessible from the Cloud B.
+
+### Clusters in the same LAN
+
+![](/images/scenarios/on-prem-to-on-prem.svg)
+
+Clusters (K3s or K8s) in the same LAN may rely on the mDNS-based Liqo discovery mechanism.
+In fact, the Liqo discovery mechanism based on mDNS will handle the discovery automatically. If you have your clusters in different L3 domains, you have to manually [create](/user/post-install/discovery#forging-the-foreigncluster) a *foreign_cluster* resource or rely on [DNS discovery](/user/post-install/discovery#manual-configuration).
+
+|  | Cluster A (On-prem) | Cluster B (On-prem) |
+| --------- | -------- |  ---------       |
+| **Auth Server** |  NodePort | NodePort |
+| **API server** | Exposed | Exposed |
+| **Network gateway** | NodePort | NodePort |
+
+This configuration is provided using the standard values of the Liqo chart.