Docs: ipmappings

docs/_toc.yml

@@ -48,6 +48,7 @@ subtrees:
       - file: advanced/virtualnode-customizations.md
       - file: advanced/kubernetes-api.md
       - file: advanced/nat.md
+      - file: advanced/external-ip-remapping.md
 
   - caption: Contributing
     entries:

docs/advanced/external-ip-remapping.md

@@ -0,0 +1,114 @@
+# External IP remapping
+
+You can use Liqo to map external IPs and make them reachable from a peered cluster. You can configure the external IP remapping using the **IP** CRD.
+This can be useful if you want to make a server (for example a legacy database) running outside the cluster, reachable from a peered cluster.
+
+```{warning}
+This feature is available only if [network module](/advanced/manual-peering.md) is enabled.
+```
+
+Check the figure below to understand how the external IP remapping works.
+We are going to make the **external host** reachable from **cluster 1**.
+
+```{figure} /_static/images/advanced/ipremap/ipremap.drawio.svg
+---
+align: center
+---
+Remap External IPs
+```
+
+## Forge an IP CRD
+
+The IP CRD allows you to remap an external IP to a new IP belonging to the **External CIDR**.
+
+Export the kubeconfig file of **cluster 2**:
+
+```bash
+export KUBECONFIG=./cluster2-kubeconfig
+```
+
+First of all, you need to create a file called **ip.yaml**.
+
+```yaml
+apiVersion: ipam.liqo.io/v1alpha1
+kind: IP
+metadata:
+  name: external-ip-remap
+spec:
+  ip: <EXTERNAL_IP>
+```
+
+Replace `<EXTERNAL_IP>` with the **external host** you want to map.
+
+Now, apply the **IP** CRD:
+
+```bash
+kubectl apply -f ip.yaml
+```
+
+Check the status of the **IP** CRD:
+
+```bash
+kubectl get ip external-ip-remap -o yaml
+```
+
+If everything went successfully, the status should be similar to the following:
+
+```yaml
+apiVersion: ipam.liqo.io/v1alpha1
+kind: IP
+...
+status:
+  ipMappings:
+    cluster1: <REMAPPED_IP>
+
+```
+
+The **status** field shows how the **external host** IP has been remapped.
+It is an IP belonging to the **External CIDR**.
+
+We are going to use the **remapped IP** on **cluster 1** to reach the **external host**.
+
+## Connect to the *external host*
+
+If **cluster 1** and **cluster 2** have different **External CIDRs** (it can be customized at installation time), you can skip this section and use the IP obtianed in the previous section to reach the **external host**.
+
+However, in most cases, the **External CIDRs** are the same, we need to get how the **remote external CIDR** has been remapped and *forge* the IP to reach the **external host**.
+
+First of all, export the kubeconfig file of **cluster 1**:
+
+```bash
+export KUBECONFIG=./cluster1-kubeconfig
+```
+
+Get the **configuration** CRD for **cluster 2**:
+
+```bash
+kubectl get configuration -n liqo-tenant-cluster2 -o yaml cluster2
+```
+
+The output should be similar to the following:
+
+```yaml
+apiVersion: networking.liqo.io/v1beta1
+kind: Configuration
+metadata:
+  labels:
+    configuration.liqo.io/configured: "true"
+    liqo.io/remote-cluster-id: cluster2
+  name: cluster2
+  namespace: liqo-tenant-cluster2
+spec:
+...
+status:
+  remote:
+    cidr:
+      external: <REMAPPED_EXT_CIDR>
+      pod: <REMAPPED_POD_CIDR>
+```
+
+Let's focus on the `REMAPPED_EXT_CIDR` value. Keep the *prefix* of that CIDR and replace it inside the `REMAPPED_IP` found in the **IP** CRD status (check the previous section).
+
+For example, if the `REMAPPED_EXT_CIDR` is *10.81.0.0/16* and the `REMAPPED_IP` is *10.70.0.1* the final IP will be *10.81.0.1*.
+
+Now, you can use the **forged IP** to reach the **external host** from **cluster 1**.

docs/usage/prometheus-metrics.md

@@ -28,7 +28,12 @@ These metrics are available for each peered remote cluster, providing statistics
 We provide a {download}`sample Grafana dashboard </_downloads/grafana/liqonetwork.json>` to monitor the network interconnection of an arbitrary number of Liqo peerings.
 As presented in the screenshot below, it includes an overview section presenting the overall cross-cluster throughput, followed by detailed per-peering throughput and latency information.
 
-![Grafana Network Dashboard](/_static/images/usage/prometheus-metrics/network-dashboard.png)
+```{figure} /_static/images/usage/prometheus-metrics/network-dashboard.png
+---
+align: center
+---
+Grafana Network Dashboard
+```
 
 ## Virtual kubelet metrics
 
@@ -43,4 +48,9 @@ We offer a {download}`sample Grafana dashboard </_downloads/grafana/liqovirtualk
 As shown in the screenshot below, it contains visual representations of the total number of reflected resources and the average rate per second.
 Additionally, there are detailed tables that provide information on the total number of each type of resource, as well as an overall summary of all reflected items during a certain time period.
 
-![Grafana Network Dashboard](/_static/images/usage/prometheus-metrics/virtualkubelet-dashboard.png)
+```{figure} /_static/images/usage/prometheus-metrics/virtualkubelet-dashboard.png
+---
+align: center
+---
+Grafana Virtual-Kubelet Dashboard
+```

docs/usage/stateful-applications.md

@@ -28,9 +28,14 @@ A virtual *PV* is eventually created by Liqo to mirror the real one, effectively
 
 The resulting configuration is depicted in the figure below.
 
-![Virtual Storage Class Local](/_static/images/usage/stateful-applications/virtual-storage-class-local.drawio.svg)
+```{figure} /_static/images/usage/stateful-applications/virtual-storage-class-local.drawio.svg
+---
+align: center
+---
+Virtual Storage Class Local
+```
 
-```{admonition} Current Limitations
+```{admonition} Note
 Currently, the virtual storage class does not support the configuration of [Kubernetes mount options](https://kubernetes.io/docs/concepts/storage/storage-classes/#mount-options) and parameters.
 ```
 
@@ -41,7 +46,12 @@ A virtual *PV* is eventually created by Liqo to mirror the real one, effectively
 
 The resulting configuration is depicted in the figure below.
 
-![Virtual Storage Class Remote](/_static/images/usage/stateful-applications/virtual-storage-class-remote.drawio.svg)
+```{figure} /_static/images/usage/stateful-applications/virtual-storage-class-remote.drawio.svg
+---
+align: center
+---
+Virtual Storage Class Remote
+```
 
 ```{warning}
 The tearing down of the peering and/or the deletion of the offloaded namespace will cause the deletion of the real PVC, and the stored data will be **permanently lost**.

pkg/consts/externalnetwork.go

@@ -15,10 +15,12 @@
 package consts
 
 const (
-	// IPCategoryTargetKey is the key used by the IPAM controller to reconcile only resources related to a group.
-	IPCategoryTargetKey = "ipam.liqo.io/ip-category"
-	// IPCategoryTargetValueMapping is the value used by the IPAM controller to reconcile only resources related to a group.
-	IPCategoryTargetValueMapping = "ip-mapping"
+	// IPHostUnreachableKey is the key used to prevent the gateways from adding
+	// the firewall rules to make the remapped IP reachable from a remote cluster.
+	IPHostUnreachableKey = "networking.liqo.io/host-unreachable"
+	// IPHostUnreachableValue is the value used to prevent the gateways from adding
+	// the firewall rules to make the remapped IP reachable from a remote cluster.
+	IPHostUnreachableValue = "true"
 
 	// GatewayResourceLabel is the label added to a gateway resource.
 	GatewayResourceLabel = "networking.liqo.io/gateway-resource"

pkg/liqo-controller-manager/ipmapping/configuration_controller.go

@@ -107,8 +107,7 @@ func (r *ConfigurationReconciler) createOrUpdateUnknownSourceIPResource(ctx cont
 			Name:      forgeUnknownSourceIPName(cfg),
 			Namespace: cfg.Namespace,
 			Labels: map[string]string{
-				consts.IPCategoryTargetKey: consts.IPCategoryTargetValueMapping,
-				consts.RemoteClusterID:     cfg.GetName(),
+				consts.RemoteClusterID: cfg.GetName(),
 			},
 		},
 	}

pkg/liqo-controller-manager/ipmapping/label.go

@@ -16,8 +16,6 @@ package ipmapping
 
 import (
 	corev1 "k8s.io/api/core/v1"
-
-	"github.com/liqotech/liqo/pkg/consts"
 )
 
 const (
@@ -27,7 +25,6 @@ const (
 
 func forgeIPLabels(pod *corev1.Pod) map[string]string {
 	return map[string]string{
-		consts.IPCategoryTargetKey:    consts.IPCategoryTargetValueMapping,
 		offloadedPodNameLabelKey:      pod.Name,
 		offloadedPodNamespaceLabelKey: pod.Namespace,
 	}

pkg/liqo-controller-manager/networking/external-network/remapping/ip_controller.go

@@ -29,6 +29,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 
 	ipamv1alpha1 "github.com/liqotech/liqo/apis/ipam/v1alpha1"
+	"github.com/liqotech/liqo/pkg/consts"
 )
 
 // IPReconciler manage IP.
@@ -100,12 +101,14 @@ func (r *IPReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Re
 // SetupWithManager register the IPReconciler to the manager.
 func (r *IPReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	filterByLabelsPredicate, err := predicate.LabelSelectorPredicate(metav1.LabelSelector{
-		MatchLabels: ForgeIPTargetLabelsMapping(),
+		MatchLabels: map[string]string{
+			consts.IPHostUnreachableKey: consts.IPHostUnreachableValue,
+		},
 	})
 	if err != nil {
 		return err
 	}
 	return ctrl.NewControllerManagedBy(mgr).
-		For(&ipamv1alpha1.IP{}, builder.WithPredicates(filterByLabelsPredicate)).
+		For(&ipamv1alpha1.IP{}, builder.WithPredicates(predicate.Not(filterByLabelsPredicate))).
 		Complete(r)
 }

pkg/liqo-controller-manager/networking/external-network/remapping/label.go

@@ -15,7 +15,6 @@
 package remapping
 
 import (
-	"github.com/liqotech/liqo/pkg/consts"
 	"github.com/liqotech/liqo/pkg/firewall"
 )
 
@@ -29,13 +28,6 @@ const (
 	FirewallSubCategoryTargetValueIPMapping = "ip-mapping"
 )
 
-// ForgeIPTargetLabelsMapping returns the labels used by the IPAM controller to reconcile only resources related to a single IP.
-func ForgeIPTargetLabelsMapping() map[string]string {
-	return map[string]string{
-		consts.IPCategoryTargetKey: consts.IPCategoryTargetValueMapping,
-	}
-}
-
 // ForgeFirewallTargetLabels returns the labels used by the firewallconfiguration controller
 // to reconcile only resources related to a single gateway.
 func ForgeFirewallTargetLabels(remoteID string) map[string]string {

pkg/liqoctl/test/network/setup/ip.go

@@ -25,7 +25,6 @@ import (
 
 	ipamv1alpha1 "github.com/liqotech/liqo/apis/ipam/v1alpha1"
 	networkingv1beta1 "github.com/liqotech/liqo/apis/networking/v1beta1"
-	"github.com/liqotech/liqo/pkg/consts"
 	"github.com/liqotech/liqo/pkg/liqoctl/test/network/client"
 )
 
@@ -54,9 +53,6 @@ func CreateIP(ctx context.Context, cl ctrlclient.Client, dstip string) error {
 		ObjectMeta: metav1.ObjectMeta{
 			Name:      IPName,
 			Namespace: NamespaceName,
-			Labels: map[string]string{
-				consts.IPCategoryTargetKey: consts.IPCategoryTargetValueMapping,
-			},
 		},
 		Spec: ipamv1alpha1.IPSpec{
 			IP:         networkingv1beta1.IP(dstip),

pkg/utils/ipam/mapping/ips.go

@@ -52,7 +52,6 @@ func EnforceAPIServerIPRemapping(ctx context.Context, cl client.Client, liqoName
 			ip.Labels = map[string]string{}
 		}
 
-		ip.Labels[consts.IPCategoryTargetKey] = consts.IPCategoryTargetValueMapping
 		ip.Labels[consts.IPTypeLabelKey] = consts.IPTypeAPIServer
 
 		ip.Spec.IP = networkingv1beta1.IP(k8sSvc.Spec.ClusterIP)