Skip to content

Commit 6be4b62

Browse files
ushabelgurushabelgur
authored
Add usage doc for Network and LoadBalancer (#1215)
* add usage doc for network and loadbalancer * refactoring * incorporating review comments
1 parent 263747a commit 6be4b62

File tree

2 files changed

+104
-0
lines changed

2 files changed

+104
-0
lines changed

‎docs/usage/networking/loadbalancer.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,64 @@
11
# LoadBalancer
2+
3+
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).
4+
5+
## Example Network Resource
6+
An example of how to define a `LoadBalancer` resource in `Ironcore`
7+
```
8+
apiVersion: networking.ironcore.dev/v1alpha1
9+
kind: LoadBalancer
10+
metadata:
11+
namespace: default
12+
name: loadbalancer-sample
13+
spec:
14+
type: Public
15+
ipFamilies: [IPv4]
16+
networkRef:
17+
name: network-sample
18+
networkInterfaceSelector:
19+
matchLabels:
20+
app: web
21+
ports:
22+
- port: 80
23+
24+
```
25+
(`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.)
26+
27+
# Key Fields:
28+
- `type`(`string`): The type of `LoadBalancer`. Currently two types of `Loadbalancer` are supported:
29+
- `Public`: LoadBalancer that allocates public IP and routes a stable public IP.
30+
- `Internal`: LoadBalancer that allocates and routes network-internal, stable IPs.
31+
- `ipFamilies`(`list`): ipFamilies are the IP families the LoadBalancer should have(Supported values are `IPv4` and `IPv6`).
32+
- `ips`(`list`): The ips are the list of IPs to use. This can only be used when the type is LoadBalancerTypeInternal.
33+
- `networkRef`(`string`): networkRef is the Network this LoadBalancer should belong to.
34+
- `networkInterfaceSelector`(`labelSelector`): networkInterfaceSelector defines the NetworkInterfaces for which this LoadBalancer should be applied
35+
- `ports`(`list`): ports are the list of LoadBalancer ports should allow
36+
- `protocol`(`string`): protocol is the protocol the load balancer should allow. Supported protocols are `UDP`, `TCP`, and `SCTP`, if not specified defaults to TCP.
37+
- `port`(`int`): port is the port to allow.
38+
- `endPort`(`int`): endPort marks the end of the port range to allow. If unspecified, only a single port `port` will be allowed.
39+
40+
# Reconciliation Process:
41+
42+
- **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.
43+
44+
- **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`.
45+
Later this information is used at the Ironcore API level to describe the explicit targets in a pool traffic is routed to.
46+
47+
Sample `LoadBalancerRouting` object(`Note`: it is created by LoadBalancerController)
48+
```
49+
apiVersion: networking.ironcore.dev/v1alpha1
50+
kind: LoadBalancerRouting
51+
metadata:
52+
namespace: default
53+
name: loadbalancer-sample # Same name as the load balancer it originates from.
54+
# networkRef references the exact network object the routing belongs to.
55+
networkRef:
56+
name: network-sample
57+
# destinations list the target network interface instances (including UID) for load balancing.
58+
destinations:
59+
- name: my-machine-interface-1
60+
uid: 2020dcf9-e030-427e-b0fc-4fec2016e73a
61+
- name: my-machine-interface-2
62+
uid: 2020dcf9-e030-427e-b0fc-4fec2016e73d
63+
```
64+
**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‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,42 @@
11
# Network
2+
3+
A `Network` resource in `Ironcore` refers to a logically isolated network.
4+
This further allows you to fully control your networking environment, including resource placement, connectivity, peering and security.
5+
The `NetworkController` reconciler leverages this information to create a Network in Ironcore infrastructure.
6+
`Machine` type is provided with provision to integrate with the Network via `NetworkInterface`.
7+
8+
## Example Network Resource
9+
An example of how to define a `Network` resource in `Ironcore`
10+
```
11+
apiVersion: networking.ironcore.dev/v1alpha1
12+
kind: Network
13+
metadata:
14+
name: network-sample
15+
spec:
16+
peerings:
17+
- name: peering1
18+
networkRef:
19+
name: network-sample2
20+
```
21+
22+
# Key Fields:
23+
- `providerID`(`string`): providerID is the provider-internal ID of the network.
24+
- `peerings`(`list`): peerings are the list of network peerings with this network(Optional).
25+
- `incomingPeerings`(`list`): incomingPeerings is a list of PeeringClaimRefs which is nothing but peering claim references of other networks.
26+
27+
# Reconciliation Process:
28+
29+
- **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.
30+
31+
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.
32+
Once resource is in available state status is marked to `Available`. The format of a network provider ID is as follows:
33+
`ironcore-net://<namespace>/<name>/<id>/<uid>`
34+
35+
- **Network peering process**: Network peering is a technique used to interleave two isolated networks, allowing members of both networks to communicate with each
36+
other as if they were in the same networking domain, `NetworkPeeringController` facilitates this process.
37+
- Information related to the referenced `Network` to be paired with is retrieved from the `peering` part of the spec.
38+
- 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.
39+
- The (binding) phase of a `spec.peerings` item is reflected in a corresponding `status.peerings` item with the same name.
40+
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.
41+
42+
- **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.

0 commit comments

Comments
 (0)