Technical documentation about the namespace replication mechanism

This commmit introduces technical concepts about the namespace replication:
1. Resources involved.
2. Controllers involved.
3. Namespace replication workflow.
4. Namespace deletion workflow.

Co-authored-by: Alex Palesandro <[email protected]>

Author: Andreagit97

docs/images/namespace-replication/replication-example.png

@@ -54,7 +54,7 @@ The network parameters between two clusters are exchanged using the NetworkConfi
 Embedded within the Liqo Network Manager, the IPAM (IP Address Management) is the Liqo module in charge of:
 1. Manage networks currently in use in the home cluster.
 2. Translate the IP address of an offloaded remote pod (assigned by a foreign cluster) in the corresponding IP address that is visible from the home cluster.
-3. Translate Endpoints IP addresses during the [Reflection](../../../offloading/features/api-reflection#Overview).
+3. Translate Endpoints IP addresses during the [Reflection](../../../offloading/api-reflection#Overview).
 
 
 #### Networks management
@@ -113,7 +113,7 @@ The IPAM module achieves this task by keeping track of how foreign clusters have
 
 
 #### Reflection
-The [Reflection](../../../offloading/features/api-reflection#Overview) is one of the most relevant Liqo features; is carried out by the Virtual Kubelet and deals with the replication of local Kubernetes resources on foreign clusters, in particular _Services_ and _Endpoints_.
+The [Reflection](../../../offloading/api-reflection#Overview) is one of the most relevant Liqo features; is carried out by the Virtual Kubelet and deals with the replication of local Kubernetes resources on foreign clusters, in particular _Services_ and _Endpoints_.
 
 {{% notice note %}}
 After having offloaded a workload, the Virtual Kubelet takes also care of creating the Shadow Pod locally and keeping it updated by inspecting its remote counterpart. During the reflection of an Endpoint instead, the Virtual Kubelet creates the resource on the foreign cluster.

docs/images/namespace-replication/replication.png

@@ -1,62 +1,46 @@
 ---
-title: Offloading
+title: Resource Offloading
 weight: 4
 ---
 
 ## Overview
 
 The peering process terminates by creating a new virtual node in the home cluster.
-According to the Liqo terminology, the new virtual node is called _big node_, as it represents (and aggregates) a subset
-of the resources available in the foreign cluster. Conversely, the home cluster becomes what we call a _big cluster_, 
-as it represents a cluster whose resources span (transparently) across multiple physical clusters.
+According to the Liqo terminology, the new virtual node is called *big node*, as it represents (and aggregates) a subset of the resources available in the foreign cluster. 
+Conversely, the home cluster becomes what we call a *big cluster*, as it represents a cluster whose resources span (transparently) across multiple physical clusters.
 
-In Kubernetes, each physical node is managed by the 
-[Kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/), a process running in the hosting 
-machine that interfaces with the Kubernetes API server, and handles the lifecycle of the pods scheduled on it.
+In Kubernetes, each physical node is managed by the [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/), a process running in the hosting machine that interfaces with the Kubernetes API server and handles the lifecycle of the pods scheduled on it.
 
-Since the foreign cluster is represented by a local (virtual) node in the home cluster, offloading a pod on the remote 
-cluster correspond to scheduling it on a specific node.
-When the virtual Kubelet creates a new pod in the foreign cluster, the foreign scheduler elects one _remote, physical_ 
-node as host for the received pod, while the _remote, physical_ kubelet managing that pod takes care of the containers' 
-execution.
+Since the foreign cluster is represented by a virtual node in the home cluster, offloading a pod on the remote cluster corresponds to scheduling it on a specific node.
+When the [virtual kubelet](#virtual-kubelet) creates a new pod in the foreign cluster, the foreign scheduler elects one *remote, physical* node as host for the received pod, while the *remote, physical* kubelet managing that pod takes care of the containers' execution.
 
-According to this mechanism, the offloading of a pod to the foreign cluster is fully compliant with the Kubernetes 
-control plane: the home cluster can control all the remote jobs by interacting with the big node that models the remote 
-cluster. 
+According to this mechanism, the offloading of a pod to the foreign cluster is fully compliant with the Kubernetes control plane: the home cluster can control all the remote jobs by interacting with the big node that represents the remote cluster. 
 
 ### Virtual Kubelet
 
-The _big node_ is a virtual node, hence it cannot have a real `kubelet` process such as normal (physical) nodes.
-Liqo leverages a custom version of the [Virtual kubelet](https://github.com/virtual-kubelet/virtual-kubelet) project for
-the management of the virtual node, with the kubelet managing the virtual node that runs as a (containerized) pod as a 
-part of the Liqo control plane.
-In a nutshell, a cluster that peers with `N` foreign clusters will have `N` big nodes, representing the `N` remote 
-clusters, and it will run `N` instances of the virtual kubelet, each one dedicated to the mapping between the (local) 
-big node and the corresponding (remote) foreign cluster.
+The *big node* is a virtual node, so it cannot have a real kubelet process such as normal physical nodes.
+Liqo leverages a custom version of the [virtual kubelet project](https://github.com/virtual-kubelet/virtual-kubelet) for the management of the virtual node.
+In a nutshell, a cluster that peers with `N` foreign clusters has `N` big nodes representing the clusters and runs `N` instances of the virtual kubelet process.
 
-Generally speaking, a real Kubelet is in charge of accomplishing two tasks:
-* handling the node resources and reconciling its status
-* taking the received pods, starting the containers, and reconciling their status in the pod resource.
+Generally speaking, a standard kubelet is in charge of accomplishing two tasks:
+
+1. Handling the node resource and reconciling its status.
+2. Taking the received pods, starting the containers, and reconciling their status in the pod resource.
 
 Similarly, the virtual kubelet is in charge of:
-* creating the virtual node resource and reconciling its status, as described in the
- [node-management](features/node-management) section;
-* offloading the local pod scheduled on the virtual node to the remote cluster, as described in the 
-[computing](features/computing) section.
 
-Also, our implementation provides a feature we called "reflection", described [here](features/api-reflection).
+1. Creating the virtual node resource and reconciling its status, as described in the [node-management](/concepts/offloading/node-management/#overview) section.
+2. Offloading the local pod scheduled on the virtual node to the remote cluster, as described in the [computing](/concepts/offloading/computing#overview) section.
+
+Also, our implementation provides a feature we called "reflection", described [here](/concepts/offloading/api-reflection/#overview).
 
 ### Namespace mapping
 
-To make the pods in a certain namespace suitable to be offloaded in the remote cluster, the virtual Kubelet has to face 
-with the problem of the offloading namespace, i.e., in which namespace of the remote cluster to create the pods.
-Further details can be found in the dedicated [section](features/namespace-management).
+The virtual kubelet has to face the namespace replication problem to make the pods in a certain namespace suitable to be offloaded.
+Further details can be found in the dedicated [section](/concepts/offloading/namespace-replication/#the-liqo-namespace-model).
 
 ### Scheduling behavior
 
-The virtual node is created with a specific taint. To make a pod available to be scheduled on that node, that taint must
-be tolerated. The toleration is added by a `MutatingWebhook` watching all the pods being created in all the namespaces 
-labeled with the label `liqo.io/enabled="true"`.
-
-By default, the Kubernetes scheduler selects the eligible node with the highest score (scores are computed on several 
-parameters, among which the available resources).
+The virtual node is created with a specific taint. To make a pod available to be scheduled on a virtual node that taint must be tolerated. 
+The toleration is added by the Liqo MutatingWebhook watching the pods created in all the namespaces labeled with the label `liqo.io/enabled="true"`.
+By default, the Kubernetes scheduler selects the eligible node with the highest score (scores are computed on several parameters, among which the available resources).

docs/images_src/namespace-replication/replication-example.xml

@@ -0,0 +1,19 @@
+---
+title: API reflection
+weight: 5
+---
+
+### Overview
+
+In addition to the well-known kubelet features, our virtual kubelet implementation provides a feature we called "*reflection*": the offloaded Pods may need some resources to be properly executed in the remote clusters, such as:
+
+* `Services`.
+* `Endpoints`.
+* `Secret`.
+* `ConfigMaps`.
+
+The virtual kubelet itself is in charge of replicating those APIs in the remote cluster by properly operating some translations (e.g., the endpoints addresses have to be translated to point to the home cluster).
+
+{{% notice note %}}
+This documentation section is a work in progress
+{{% /notice %}}

docs/images_src/namespace-replication/replication.xml

@@ -0,0 +1,45 @@
+---
+title: Computing
+weight: 4
+---
+
+### Overview
+
+The pod offloading in a foreign cluster involves a two-steps scheduling process, which can be summarized as follows:
+
+- the scheduler of the home cluster selects the *big node* as the best target to run the pod;
+- the *big node*, being virtual, cannot run any pod. Hence, the virtual kubelet handling the *big node* involves the foreign cluster scheduler, which will select the best physical node on the foreign cluster.
+
+In addition, the virtual kubelet executes the proper reconciliation processes to allow pods in the home cluster to be up-to-date with the remote ones' status. These processes ensure complete visibility in the home cluster.
+
+### Remote pod resiliency 
+
+Due to the properties of the two-step scheduling process, different behaviors can be spotted when deleting a pod running in a foreign cluster:
+
+- The pod is deleted in the **home cluster** (intentionally or by eviction): the remote one has to be immediately deleted. In fact, the home cluster is the owner of the pod, therefore whatever modification to the pod is set, this has to be reflected on the remote pod. Hence, when the pod is deleted in the home cluster, the status of the remote cluster has to be aligned, leading to the deletion of the remote pod.
+- The pod is deleted in the **foreign cluster** (intentionally or by eviction): not only the local pod must not be deleted, but the remote pod has to be re-created as soon as possible. The requested pod must be running in the foreign cluster without involving the home cluster unless an unrecoverable condition is detected.
+
+To implement this behavior, a new pod scheduled in the virtual node triggers the Virtual Kubelet to create a new [ReplicaSet](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), that ultimately leads to the creation of the pod (through the foreign controller-manager).
+
+Creating a remote ReplicaSet addresses the problem of the remote pod resiliency : once a ReplicaSet is created in the remote cluster, the remote ReplicaSet-controller reconciles its status, leading to the desired number of running pods at any time (the desired amount of replicas for those ReplicaSet is always one).
+
+### Computing resources offloading and reconciliation
+
+The scheme below describes the offloading workflow.
+The local pod is referred to as *shadow pod* (because it is a mere local representation of the remote pod).
+
+![](/images/offloading/computing-offloading-overview.svg)
+
+1. A user creates a deployment in the local cluster.
+2. The controller-manager detects the new deployment, then
+    1. Creates the corresponding ReplicaSet;
+    2. Detects the ReplicaSet creation;
+    3. Creates the specified amount of Pod replicas.
+3. The scheduler detects the creation of the new Pod.
+4. The scheduler binds some Pods to the virtual node.
+5. The Virtual Kubelet detects that a Pod has been scheduled on the virtual node managed by this process.
+7. The Virtual Kubelet creates a remote ReplicaSet having the local Pod as `PodTemplate` field and _one_ replica.
+8. The remote controller-manager detects the ReplicaSet.
+9. The remote controller-manager creates one Pod starting from the `PodTemplate` field.
+10. The Virtual Kubelet detects the creation of the remote offloaded Pod.
+11. The Virtual Kubelet keeps the local Pod status updated with the remote one.