Skip to content

Commit affeb90

Browse files
Rohit-0505Rohit-0505
authored
Add usage doc for virtualIP, networkPolicy, networkInterface, and NATGateway (#1216)
* Add usage doc for `virtualIP` and `networkPolicy` * add usage doc for `NetworkInterface` * add usage doc for `NATGateway` and refactor other docs * address review comments
1 parent 6b6932d commit affeb90

File tree

4 files changed

+269
-0
lines changed

4 files changed

+269
-0
lines changed

‎docs/usage/networking/natgateway.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,58 @@
11
# NATGateway
2+
In the `Ironcore` project, a `NATGateway` (Network Address Translation Gateway) facilitates outbound internet connectivity in private subnets, ensuring that instances in private subnets can access external services without exposing them to unauthorized inbound traffic.
3+
4+
It is a critical network service that provides secure and controlled internet access for private resources in the `Ironcore` infrastructure. It is enforced by the underlying `Ironcore's` network plugin called <a href="https://github.com/ironcore-dev/ironcore-net/blob/main/apinetlet/controllers/natgateway_controller.go"> ironcore-net </a>
5+
6+
# Example NATGateway Resource
7+
An example of how to define a `NATGateway` resource in `Ironcore`
8+
9+
```
10+
apiVersion: networking.ironcore.dev/v1alpha1
11+
kind: NATGateway
12+
metadata:
13+
namespace: default
14+
name: natgateway-sample
15+
spec:
16+
type: Public
17+
ipFamily: IPv4
18+
portsPerNetworkInterface: 64
19+
networkRef:
20+
name: network-sample
21+
```
22+
23+
# Key Fields
24+
- `type`(`string`): This represents a NATGateway type that allocates and routes a stable public IP. The supported value for type is `public`
25+
26+
- `ipFamily`(`string`): `IPFamily` is the IP family of the `NATGateway`. Supported values for IPFamily are `IPv4` and `IPv6`.
27+
28+
- `portsPerNetworkInterface`(`int32`): This Specifies the number of ports allocated per network interface and controls how many simultaneous connections can be handled per interface.
29+
30+
If empty, 2048 (DefaultPortsPerNetworkInterface) is the default.
31+
32+
- `networkRef`(`string`): It represents which network this `NATGateway` serves.
33+
34+
# Example Use Case:
35+
Imagine you have a private server in a private subnet without a public IP. It needs to download software updates from the internet. Instead of giving it direct internet access (which compromises security), the server sends its requests through the NAT Gateway. The NAT Gateway fetches the updates and returns them to the server while keeping the server's private IP hidden from the external world.
36+
37+
# Reconciliation Process:
38+
39+
- **Fetch NATGateway Resource**: It fetches the current state of `NATGateways`, Based on user specifications the desired state of `NATGateway` is determined. This includes the number of NAT Gateways, their types, associated subnets, and routing configurations.
40+
41+
- **Compare and Reconcile**: The reconciler keeps monitoring the state of NAT Gateways to detect any changes or drifts from the desired state, triggering the reconciliation process as needed.
42+
- Creation: If a NAT Gateway specified in the desired state does not exist in the current state, it is created. For instance, creating a public NAT Gateway in a public subnet to provide internet access to instances in private subnets.
43+
44+
- Update: If a NAT Gateway exists but its configuration differs from the desired state, it is updated accordingly. This may involve modifying routing tables or changing associated Elastic IPs.
45+
46+
- Deletion: If a NAT Gateway exists in the current state but is not present in the desired state, it is deleted to prevent unnecessary resource utilization.
47+
48+
- **Error Handling and Logging**: Throughout the reconciliation process, any errors encountered are logged, schedule retries as necessary to ensure eventual consistency.
49+
50+
- **Update Status**:
51+
After reconciling all `NATGateways`, log the successful reconciliation and update the `NATGateways` status with the corresponding values for `ips`as shown below.
52+
53+
```
54+
status:
55+
ips:
56+
- name: ip1
57+
ip: 10.0.0.1
58+
```

‎docs/usage/networking/networkinterface.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,76 @@
11
# NetworkInterface
2+
A `NetworkInterface` resource in `Ironcore` represents a connection point between a virtual machine(VM) and a virtual network. It encapsulates the configuration and life cycle management of the virtual network interface, ensuring seamless connectivity for VMs.
3+
4+
The `MachineEphemeralNetworkInterfaceReconciler` is responsible for managing the lifecycle of ephemeral network interfaces associated with machines. Its primary function is to ensure that the actual state of these network interfaces aligns with the desired state specified in each machine's configuration.
5+
6+
# Example NetworkPolicy Resource
7+
An example of how to define a `NetworkInterface` resource in `Ironcore`
8+
9+
```
10+
apiVersion: networking.ironcore.dev/v1alpha1
11+
kind: NetworkInterface
12+
metadata:
13+
name: networkinterface-sample
14+
spec:
15+
networkRef:
16+
name: network-sample
17+
ipFamilies:
18+
- IPv4
19+
ips:
20+
- value: 10.0.0.1 # internal IP
21+
virtualIP:
22+
virtualIPRef:
23+
name: virtualip-sample
24+
```
25+
**Note**: For a detailed end-to-end example to understand the ephemeral and non-ephemeral `NetworkInterface` resource, please refer <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e">E2E Examples</a>
26+
27+
# Key Fields
28+
- `networkRef`(`string`): `NetworkRef` is the Network this NetworkInterface is connected to
29+
30+
- `ipFamilies`(`list`): `IPFamilies` defines the list of IPFamilies this `NetworkInterface` supports. Supported values for IPFamily are `IPv4` and `IPv6`.
31+
32+
- `ips`(`list`): `IPs` are the list of provided internal IPs which should be assigned to this NetworkInterface
33+
34+
- `virtualIP`: `VirtualIP` specifies the public ip that should be assigned to this NetworkInterface.
35+
36+
# Reconciliation Process:
37+
38+
- **Fetch Machine Resource**:
39+
Retrieve the specified Machine resource from the reconciliation request.
40+
If the Machine is marked for deletion (indicated by a non-zero DeletionTimestamp), exit the process without further action.
41+
42+
- **Generate Desired Ephemeral Network Interfaces**:
43+
Analyze the Machine's specification to identify the desired ephemeral NetworkInterface resources.
44+
Construct a map detailing these desired NetworkInterfaces, including their configurations and expected states.
45+
46+
- **Fetch Existing NetworkInterfaces**:
47+
List all existing NetworkInterface resources within the same namespace as the Machine.
48+
49+
- **Compare and Reconcile**:
50+
- For each existing Network Interface:
51+
Determine if it is managed by the current Machine and whether it matches the desired state.
52+
- If unmanaged but should be managed, avoid adopting it to prevent conflicts.
53+
- For each desired Network Interface not present:
54+
Create the missing `NetworkInterface` and establish the Machine as its controller.
55+
56+
- **Handle Errors**:
57+
Collect any errors encountered during the reconciliation of individual NetworkInterfaces.
58+
Log these errors and schedule retries as necessary to ensure eventual consistency.
59+
60+
- **Update Status**:
61+
After reconciling all NetworkInterfaces, log the successful reconciliation and update the `NetworkInterface` status with the corresponding values for `ips`, `state`, and `virtualIP`, as shown below.
62+
63+
```
64+
status:
65+
ips:
66+
- 10.0.0.1
67+
lastStateTransitionTime: "2025-01-13T11:39:17Z"
68+
state: Available
69+
virtualIP: 172.89.244.23
70+
```
71+
The `state` is updated as one of the following lifecycle states based on the reconciliation result
72+
- **Pending**
73+
- **Available**
74+
- **Error**
75+
76+

‎docs/usage/networking/networkpolicy.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,91 @@
11
# NetworkPolicy
2+
In `Ironcore`, NetworkPolicies are implemented based on the standard Kubernetes `NetworkPolicy` approach, which is enforced by the underlying `Ironcore's` network plugin <a href="https://github.com/ironcore-dev/ironcore-net/blob/main/apinetlet/controllers/networkpolicy_controller.go"> ironcore-net </a> and other components. These policies use label selectors to define the source and destination of allowed traffic within the same network and can specify rules for both ingress (incoming) and egress (outgoing) traffic.
3+
4+
In the `Ironcore` ecosystem, the `NetworkPolicy` has the following characteristics:
5+
6+
- NetworkPolicy is applied exclusively to NetworkInterfaces selected using label selectors.
7+
8+
- These NetworkInterfaces must belong to the same network.
9+
10+
- The policy governs traffic to and from other `NetworkInterfaces`, `LoadBalancers`, etc., based on the rules defined in the NetworkPolicy.
11+
12+
# Example NetworkPolicy Resource
13+
An example of how to define a `NetworkPolicy` resource in `Ironcore`
14+
15+
```
16+
apiVersion: networking.ironcore.dev/v1alpha1
17+
kind: NetworkPolicy
18+
metadata:
19+
namespace: default
20+
name: my-network-policy
21+
spec:
22+
networkRef:
23+
name: my-network
24+
networkInterfaceSelector:
25+
matchLabels:
26+
app: db
27+
policyTypes:
28+
- Ingress
29+
- Egress
30+
ingress:
31+
- from:
32+
- ipBlock:
33+
cidr: 172.17.0.0/16
34+
- objectSelector:
35+
kind: NetworkInterface
36+
matchLabels:
37+
app: web
38+
- objectSelector:
39+
kind: LoadBalancer
40+
matchLabels:
41+
app: web
42+
# Ports always have to be specified. Only traffic matching the ports
43+
# will be allowed.
44+
ports:
45+
- protocol: TCP
46+
port: 5432
47+
egress:
48+
- to:
49+
- ipBlock:
50+
cidr: 10.0.0.0/24
51+
ports:
52+
- protocol: TCP
53+
port: 8080
54+
```
55+
https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-policy
56+
57+
(`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-policy">E2E Examples</a> for more detailed example on networkpolicy to understant e2e flow)
58+
59+
# Key Fields
60+
61+
- `networkRef`(`string`): NetworkRef is the Network to regulate using this NetworkPolicy.
62+
63+
- `networkInterfaceSelector`(`labelSelector`): NetworkInterfaceSelector defines the target `NetworkInterfaces` for which this `NetworkPolicy` should be applied.
64+
65+
- `policyTypes`(`list`): There are two supported policyTypes `Ingress` and `Egress`.
66+
67+
- `ingress`(`list`): An Ingress section in a `NetworkPolicy` defines a list of `NetworkPolicyIngressRules` that specify which incoming traffic is allowed. Each `NetworkPolicy` can have multiple ingress rules, and each rule allows traffic that satisfies both the from and ports criteria.
68+
69+
For example, a `NetworkPolicy` with a single ingress rule may permit traffic on a specific port and only from one of the following sources:
70+
- An IP range, defined using an ipBlock.
71+
- A set of resources identified by an objectSelector.
72+
73+
- `egress`(`list`): egress defines the list of `NetworkPolicyEgressRules`. Each NetworkPolicy may include a list of allowed egress rules. Each rule allows traffic that matches both `to` and `ports` sections. The example policy contains a single rule, which matches traffic on a single port to any destination in 10.0.0.0/24.
74+
75+
# Reconciliation Process:
76+
The `NetworkPolicyReconciler` in the Ironcore project is responsible for managing the lifecycle of `NetworkPolicy` resources. Its primary function is to ensure that the rules specified by the user in the NetworkPolicy resource are enforced and applied on the target `NetworkInterface`.
77+
78+
The <a href="https://github.com/ironcore-dev/ironcore-net/blob/main/apinetlet/controllers/networkpolicy_controller.go"> apinetlet </a> component in `ironcore-net` plugin is responsible for translating the policy rules into another APInet type resource `NetworkPolicyRule`. Finally, the <a href="https://github.com/ironcore-dev/ironcore-net/blob/main/metalnetlet/controllers/networkinterface_controller.go"> metalnetlet </a> component in `ironcore-net` and other components propagates these rules for enforcement at `dpservice` level in the Ironcore infrastucture.
79+
80+
The reconciliation process involves several key steps:
81+
82+
- **Fetching the NetworkPolicy Resource**: The reconciler retrieves the NetworkPolicy resource specified in the reconciliation request. If the resource is not found, it may have been deleted, and the reconciler will handle this scenario appropriately.
83+
84+
- **Validating the NetworkPolicy**: The retrieved NetworkPolicy is validated to ensure it confirms the expected specifications. This includes checking fields such as NetworkRef, NetworkInterfaceSelector, Ingress, Egress, and PolicyTypes to ensure they are correctly defined.
85+
86+
- **Fetching Associated Network Interfaces**: Using the NetworkInterfaceSelector, the reconciler identifies the network interfaces that are subject to the policy.
87+
88+
- **Applying Policy Rules**: The reconciler translates the ingress and egress rules defined in the NetworkPolicy into configurations that can be enforced by the underlying network infrastructure. This involves interacting with other components responsible for NetworkPolicy or Firewall rule enforcement.
89+
90+
- **Handling Errors and Reconciliation Loops**: If errors occur during any of the above steps, the reconciler will log the issues and may retry the reconciliation.
91+

‎docs/usage/networking/virtualip.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,48 @@
11
# VirtualIP
2+
A `Virtual IP (VIP)` in the `Ironcore` ecosystem is an abstract network resource representing an IP address that is dynamically associated with an `ironcore` `networkInterface`, which in turn is linked to an `ironcore machine/vm`.
3+
4+
# Examaple VirtualIP Resource
5+
6+
```
7+
apiVersion: networking.ironcore.dev/v1alpha1
8+
kind: VirtualIP
9+
metadata:
10+
name: virtualip-sample
11+
spec:
12+
type: Public
13+
ipFamily: IPv4
14+
```
15+
16+
# Key Fields
17+
- `type`(`string`): Currently supported type is `public`, which allocates and routes a stable public IP.
18+
19+
- `ipFamily`(`string`): `IPFamily` is the ip family of the VirtualIP. Supported values for IPFamily are `IPv4` and `IPv6`.
20+
21+
22+
# Reconciliation Process:
23+
24+
- **VirtualIP Creation**:
25+
A VirtualIP resource is created, specifying attributes like `ipFamily`: IPv4 or IPv6 and `Type`: public
26+
27+
- **Reconciliation and IP Assignment**:
28+
The VirtualIP reconciler
29+
Creates or updates a corresponding APINet IP in Ironcore's APINet system.
30+
Ensures the IP is dynamically allocated and made available for use.
31+
32+
- **Error Handling**:
33+
If the creation or update of the APINet IP fails, update the VirtualIP status to indicate it is unallocated.
34+
Requeue the reconciliation to retry the operation.
35+
36+
- **Synchronize Status**:
37+
Update the VirtualIP status to reflect the actual state of the APINet IP.
38+
If successfully allocated, update the status with the assigned IP address.
39+
40+
for example:
41+
```
42+
status:
43+
ip: 10.0.0.1 # This will be populated by the corresponding controller.
44+
```
45+
- **Networking Configuration**:
46+
- VM Integration: The allocated VirtualIP is associated with the VM through network configuration mechanisms
47+
- Load Balancer Integration: If a load balancer is used, the virtualIP is configured as the frontend IP to route requests to the VM.
48+

0 commit comments

Comments
 (0)