Skip to content

Commit

Permalink
Add usage doc for virtualIP and networkPolicy
Browse files Browse the repository at this point in the history
  • Loading branch information
Rohit-0505 committed Jan 10, 2025
1 parent 6bbca96 commit 8fe3d97
Show file tree
Hide file tree
Showing 2 changed files with 130 additions and 0 deletions.
86 changes: 86 additions & 0 deletions docs/usage/networking/networkpolicy.md
Original file line number Diff line number Diff line change
@@ -1 +1,87 @@
# NetworkPolicy
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.

In the `Ironcore` ecosystem, the `NetworkPolicy` has the following characteristics:

- NetworkPolicy is applied exclusively to NetworkInterfaces selected using label selectors.

- These NetworkInterfaces must belong to the same network.

- The policy governs traffic to and from other `NetworkInterfaces`, `LoadBalancers`, etc., based on the rules defined in the NetworkPolicy.

# Example NetworkPolicy Resource
An example of how to define a `NetworkPolicy` resource in `Ironcore`

```
apiVersion: networking.ironcore.dev/v1alpha1
kind: NetworkPolicy
metadata:
namespace: default
name: my-network-policy
spec:
networkRef:
name: my-network
networkInterfaceSelector:
matchLabels:
app: db
policyTypes:
- Ingress
- Egress
ingress:
- from:
- ipBlock:
cidr: 172.17.0.0/16
- objectSelector:
kind: NetworkInterface
matchLabels:
app: web
- objectSelector:
kind: LoadBalancer
matchLabels:
app: web
# Ports always have to be specified. Only traffic matching the ports
# will be allowed.
ports:
- protocol: TCP
port: 5432
egress:
- to:
- ipBlock:
cidr: 10.0.0.0/24
ports:
- protocol: TCP
port: 8080
```
https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-policy

(`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)

# Key Fields

- `networkRef`(`string`): NetworkRef is the Network to regulate using this NetworkPolicy.

- `networkInterfaceSelector`(`labelSelector`): NetworkInterfaceSelector defines the target `NetworkInterfaces` for which this `NetworkPolicy` should be applied.

- `policyTypes`(`list`): There are two supported policyTypes `Ingress` and `Egress`.

- `ingress`(`list`): ingress defines the list of `NetworkPolicyIngressRules`. Each NetworkPolicy may include a list of allowed `ingress` rules. Each rule allows traffic that matches both the `from` and `ports` sections. The example policy contains a single rule, which matches traffic on a single port, from one of three sources, the first specified via an ipBlock, the second and third via different objectSelector.

- `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.

# Reconciliation Process:
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`.

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.

The reconciliation process involves several key steps:

- **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.

- **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.

- **Fetching Associated Network Interfaces**: Using the NetworkInterfaceSelector, the reconciler identifies the network interfaces that are subject to the policy.

- **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.

- **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.

44 changes: 44 additions & 0 deletions docs/usage/networking/virtualip.md
Original file line number Diff line number Diff line change
@@ -1 +1,45 @@
# VirtualIP
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`.

# Examaple VirtualIP Resource

```
apiVersion: networking.ironcore.dev/v1alpha1
kind: VirtualIP
metadata:
name: virtualip-sample
spec:
type: Public
ipFamily: IPv4
#status:
# ip: 10.0.0.1 # This will be populated by the corresponding controller.
```

# Key Fields
- **type**(`string`): Currently supported type is `public`, which allocates and routes a stable public IP.

- **ipFamily**(`string`): `IPFamily` is the ip family of the VirtualIP. Supported values for IPFamily are `IPv4` or `IPv6`.


# Reconciliation Process:

- **VirtualIP Creation**:
A VirtualIP resource is created, specifying attributes like `ipFamily`: IPv4 or IPv6 and `Type`: public

- **Reconciliation and IP Assignment**:
The VirtualIP reconciler
Creates or updates a corresponding APINet IP in Ironcore's APINet system.
Ensures the IP is dynamically allocated and made available for use.

- **Error Handling**:
If the creation or update of the APINet IP fails, update the VirtualIP status to indicate it is unallocated.
Requeue the reconciliation to retry the operation.

- **Synchronize Status**:
Update the VirtualIP status to reflect the actual state of the APINet IP.
If successfully allocated, update the status with the assigned IP address.

- **Networking Configuration**:
- VM Integration: The allocated VirtualIP is associated with the VM through network configuration mechanisms
- Load Balancer Integration: If a load balancer is used, the virtualIP is configured as the frontend IP to route requests to the VM.

0 comments on commit 8fe3d97

Please sign in to comment.