diff --git a/docs/usage/networking/loadbalancer.md b/docs/usage/networking/loadbalancer.md index c1fc54686..a0d56732f 100644 --- a/docs/usage/networking/loadbalancer.md +++ b/docs/usage/networking/loadbalancer.md @@ -1 +1,66 @@ # 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 Load Balancer 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 +#status: +# ips: +# - 10.0.0.1 # The publicly available IP of the load balancer + +``` +(`Note`: Refer to E2E Examples for more detailed examples.) + +# Key Fields: +- `type`(`string`): Type is 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`): ipFamiliesare the IP families the load balancer 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 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 +``` diff --git a/docs/usage/networking/network.md b/docs/usage/networking/network.md index 05db335c4..c2e8a5e3e 100644 --- a/docs/usage/networking/network.md +++ b/docs/usage/networking/network.md @@ -1 +1,39 @@ # 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 and updates +providerID in the spec. Once resource is in available state status is marked to `Available`. + +- **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. \ No newline at end of file