From 85b258a7f6b4211d40841239be90a907b5a0cda3 Mon Sep 17 00:00:00 2001
From: Axel Christ <axel.christ@sap.com>
Date: Fri, 22 Sep 2023 13:18:38 +0200
Subject: [PATCH] Document `apinetlet` <-> `onmetal-api` integration

---
 docs/concepts/README.md                  |  2 +
 docs/concepts/onmetal-api-integration.md | 76 ++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/concepts/onmetal-api-integration.md

diff --git a/docs/concepts/README.md b/docs/concepts/README.md
index 7ab41e7c..95e8bcb0 100644
--- a/docs/concepts/README.md
+++ b/docs/concepts/README.md
@@ -6,3 +6,5 @@
   of a `Network` object.
 * [`IP` lifecycle](ip-lifecycle.md) describes the lifecycle
   of an `IP` object.
+* [`onmetal-api` integration](onmetal-api-integration.md) describes how
+  `onmetal-api-net` can be integrated with `onmetal-api`.
diff --git a/docs/concepts/onmetal-api-integration.md b/docs/concepts/onmetal-api-integration.md
new file mode 100644
index 00000000..1543d9e5
--- /dev/null
+++ b/docs/concepts/onmetal-api-integration.md
@@ -0,0 +1,76 @@
+# `onmetal-api` integration
+
+`onmetal-api-net` controls networking over multiple peers
+and intelligently manages functions. It can be operated and
+used independently of `onmetal-api`. The binding to `onmetal-api`
+is only realized via `apinetlet`.
+
+## Mapped objects / interaction
+
+The `apinetlet` is a controller that has access to an `onmetal-api`-enabled
+cluster and an `onmetal-api-net`-enabled cluster. It maps objects of
+`onmetal-api`'s `networking` group to corresponding entities in
+`onmetal-api-net`, if possible.
+
+### `Network`
+
+When an `networking.api.onmetal.de/Network` is created, a corresponding
+`core.apinet.api.onmetal.de/Network` is created in the `apinet` cluster.
+The name of the `Network` in the `apinet` cluster is the `uid` of the
+`Network` in the `onmetal-api` cluster.
+
+Once created and with an allocated `ID`, the `onmetal-api` `Network` will
+be patched with the corresponding provider ID of the `apinet` `Network` and
+set to `state: Available`.
+The provider ID format & parsing can be found in [`provider.go`](../../apinetlet/provider/provider.go).
+
+### `LoadBalancer`
+
+For a `networking.api.onmetal.de/LoadBalancer` a corresponding
+`core.apinet.api.onmetal.de/LoadBalancer` is created, also having the
+`uid` of the source object as its name.
+
+The `apinet` `LoadBalancer` is configured to have an IP per IP family
+if it's a `Public` load balancer. Otherwise, it simply uses the IPs
+specified via the `onmetal-api` `LoadBalancer`.
+
+For the routing targets, the `onmetal-api` `LoadBalancerRouting` is
+inspected and transformed into an `apinet` `LoadBalancerRouting`.
+
+For its instances, the `apinet` `LoadBalancer` is created with a `template`
+that specifies instance anti-affinity to ensure instances are distributed
+cross-zone.
+
+### `NATGateway`
+
+For a `networking.api.onmetal.de/NATGateway` a corresponding
+`core.apinet.api.onmetal.de/NATGateway` is created, also having the
+`uid` of the source object as its name. Additionally, a
+`NATGatewayAutoscaler` is created, ensuring there are enough public
+IPs available.
+
+The `apinet` `NATGateway` will try to target all `NetworkInterface`s
+in its `Network` that share an `IPFamily` but don't have a public
+IP for that family and no other `NATGateway` claiming it.
+
+### `NetworkInterface`
+
+Since the location of an `apinet` `NetworkInterface` depends on an
+`apinet` `Node`, `apinetlet` can *not* create a mapping `apinet`
+`NetworkInterface` for an `onmetal-api` `NetworkInterface`. Instead,
+the `MachinePool` implementing entity is responsible of doing so.
+
+The desired flow here is for the `MachinePool` implementor to create
+an `apinet` `NetworkInterface` for each desired `onmetal-api`
+`NetworkInterface` a `Machine` specifies. Then, upon successful creation,
+the `MachinePool` implementor has to patch the `onmetal-api`'s
+`NetworkInterface` `spec.providerID` to the provider ID of the
+`apinet` `NetworkInterface` (again, see
+[`provider.go`](../../apinetlet/provider/provider.go) on how to obtain
+/ format the provider ID correctly).
+
+Once the `providerID` of the `onmetal-api` `NetworkInterface` is set,
+`apinetlet` takes care reporting the status of the `onmetal-api`
+`NetworkInterface` by observing the matching `apinet` `NetworkInterface`.
+`apinetlet` then also applies requested `VirtualIP`s and `LoadBalancer`
+targets to the `apinet` `NetworkInterface`.