Add usage doc for Network and LoadBalancer

docs/usage/networking/loadbalancer.md

@@ -1 +1,64 @@
 # LoadBalancer
+
+A `LoadBalancer` resource is an L3(IP-based) load balancer service implementation provided by Ironcore. It provides an externally accessible IP address that sends traffic to the correct port on your cluster nodes. Ironcore LoadBalancer allows targeting multiple `NetworkInterfaces` and distributes traffic between them. This LoadBalancer supports dual stack IP addresses (IPv4/IPv6). 
+
+## Example Network Resource
+An example of how to define a `LoadBalancer` resource in `Ironcore`
+```
+apiVersion: networking.ironcore.dev/v1alpha1
+kind: LoadBalancer
+metadata:
+  namespace: default
+  name: loadbalancer-sample
+spec:
+  type: Public
+  ipFamilies: [IPv4]
+  networkRef:
+    name: network-sample
+  networkInterfaceSelector:
+    matchLabels:
+      app: web
+  ports:
+  - port: 80
+
+```
+(`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/loadbalancer-public">E2E Examples</a> for more detailed examples.)
+
+# Key Fields:
+- `type`(`string`): The type of `LoadBalancer`. Currently two types of `Loadbalancer` are supported: 
+    - `Public`: LoadBalancer that allocates public IP and routes a stable public IP.
+    - `Internal`: LoadBalancer that allocates and routes network-internal, stable IPs.
+- `ipFamilies`(`list`): ipFamilies are the IP families the LoadBalancer should have(Supported values are `IPv4` and `IPv6`). 
+- `ips`(`list`): The ips are the list of IPs to use. This can only be used when the type is LoadBalancerTypeInternal.
+- `networkRef`(`string`): networkRef is the Network this LoadBalancer should belong to.
+- `networkInterfaceSelector`(`labelSelector`): networkInterfaceSelector defines the NetworkInterfaces for which this LoadBalancer should be applied
+- `ports`(`list`): ports are the list of LoadBalancer ports should allow
+    - `protocol`(`string`): protocol is the protocol the load balancer should allow. Supported protocols are `UDP`, `TCP`, and `SCTP`, if not specified defaults to TCP.
+    - `port`(`int`): port is the port to allow.
+    - `endPort`(`int`): endPort marks the end of the port range to allow. If unspecified, only a single port `port` will be allowed.
+
+# Reconciliation Process:
+
+- **NetworkInterfaces selection**: LoadBalancerController continuously watches for `LoadBalancer` resources and reconciles. LoadBalancer resource dynamically selects multiple target `NetworkInterfaces` via a `networkInterfaceSelector` LabelSelector from the spec. Once the referenced Network is in `Available` state, the Loadbalancer destination IP list and referencing `NetworkInterface` is prepared by iterating over selected NetworkIntrefaces status information.
+
+- **Preparing Routing State Object**: Once the destination list is available `LoadBalancerRouting` resource is created. `LoadBalancerRouting` describes `NetworkInterfaces` load balanced traffic is routed to. This object describes the state of the LoadBalancer and results of the LoadBalancer definition specifically `networkInterfaceSelector` and `networkRef`. 
+Later this information is used at the Ironcore API level to describe the explicit targets in a pool traffic is routed to.
+
+Sample `LoadBalancerRouting` object(`Note`: it is created by LoadBalancerController)
+```
+apiVersion: networking.ironcore.dev/v1alpha1
+kind: LoadBalancerRouting
+metadata:
+  namespace: default
+  name: loadbalancer-sample # Same name as the load balancer it originates from.
+# networkRef references the exact network object the routing belongs to.
+networkRef:
+  name: network-sample
+# destinations list the target network interface instances (including UID) for load balancing.
+destinations:
+  - name: my-machine-interface-1
+    uid: 2020dcf9-e030-427e-b0fc-4fec2016e73a
+  - name: my-machine-interface-2
+    uid: 2020dcf9-e030-427e-b0fc-4fec2016e73d
+```
+**LoadBalancer status update**: The `LoadBalancerController` in ironcore-net takes care of allocating IPs for defined `ipFamilies` in the spec and updates them in its `status.ips`.

docs/usage/networking/network.md

@@ -1 +1,42 @@
 # Network
+
+A `Network` resource in `Ironcore` refers to a logically isolated network. 
+This further allows you to fully control your networking environment, including resource placement, connectivity, peering and security. 
+The `NetworkController` reconciler leverages this information to create a Network in Ironcore infrastructure.
+`Machine` type is provided with provision to integrate with the Network via `NetworkInterface`.
+
+## Example Network Resource
+An example of how to define a `Network` resource in `Ironcore`
+```
+apiVersion: networking.ironcore.dev/v1alpha1
+kind: Network
+metadata:
+  name: network-sample
+spec:
+  peerings:
+  - name: peering1
+    networkRef:
+      name: network-sample2
+```
+
+# Key Fields:
+- `providerID`(`string`): providerID is the provider-internal ID of the network.
+- `peerings`(`list`): peerings are the list of network peerings with this network(Optional).
+- `incomingPeerings`(`list`): incomingPeerings is a list of PeeringClaimRefs which is nothing but peering claim references of other networks.
+
+# Reconciliation Process:
+
+- **Network creation**: `ironcore-net` which is the network provider for Ironcore realizes the `Network` resource via `apinetlet` controllers. When an Ironcore `Network` is created, a corresponding `core.apinet.ironcore.dev/Network` is created in the apinet cluster. The name of the Network in the apinet cluster is the uid of the Network in the Ironcore cluster.
+
+  Once created and with an allocated ID, the Ironcore 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.
+  Once resource is in available state status is marked to `Available`. The format of a network provider ID is as follows:
+  `ironcore-net://<namespace>/<name>/<id>/<uid>`
+
+- **Network peering process**: Network peering is a technique used to interleave two isolated networks, allowing members of both networks to communicate with each 
+other as if they were in the same networking domain,  `NetworkPeeringController` facilitates this process.
+  - Information related to the referenced `Network` to be paired with is retrieved from the `peering` part of the spec.
+  - Validation is done to see if both Networks have specified a matching peering item (i.e. reference each other via `networkRef`) to mutually accept the peering.
+  - The (binding) phase of a `spec.peerings` item is reflected in a corresponding `status.peerings` item with the same name. 
+    The phase can either be `Pending`, meaning there is no active peering or `Bound` meaning the peering as described in the `spec.peerings` item is in place. 
+
+- **Network Release Controller**: `NetworkReleaseController` continuously checks if claiming Networks in other Network's peerings section still exist if not present it will be removed from the `incomingPeerings` list.