add usage doc for NATGateway and refactor other docs

docs/usage/networking/natgateway.md

@@ -1 +1,58 @@
 # NATGateway
+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.
+
+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>
+
+# Example NATGateway Resource
+An example of how to define a `NATGateway` resource in `Ironcore`
+
+```
+apiVersion: networking.ironcore.dev/v1alpha1
+kind: NATGateway
+metadata:
+  namespace: default
+  name: natgateway-sample
+spec:
+  type: Public
+  ipFamily: IPv4
+  portsPerNetworkInterface: 64
+  networkRef:
+    name: network-sample
+```
+
+# Key Fields 
+- `type`(`string`): This represents a NATGateway type that allocates and routes a stable public IP. The supported value for type is `public`
+
+- `ipFamily`(`string`): `IPFamily` is the IP family of the `NATGateway`. Supported values for IPFamily are `IPv4` and `IPv6`.
+
+- `portsPerNetworkInterface`(`int32`): This Specifies the number of ports allocated per network interface and controls how many simultaneous connections can be handled per interface. 
+
+    If empty, 2048 (DefaultPortsPerNetworkInterface) is the default.
+
+- `networkRef`(`string`): It represents which network this `NATGateway` serves.
+
+# Example Use Case:
+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.
+
+# Reconciliation Process:
+
+- **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.
+
+- **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.
+    - 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.
+
+    - 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.
+
+    - 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.
+
+- **Error Handling and Logging**: Throughout the reconciliation process, any errors encountered are logged, schedule retries as necessary to ensure eventual consistency.
+
+- **Update Status**:
+After reconciling all `NATGateways`, log the successful reconciliation and update the `NATGateways` status with the corresponding values for `ips`as shown below.
+
+```
+#status:
+#  ips:
+#  - name: ip1
+#    ip: 10.0.0.1
+```

docs/usage/networking/networkinterface.md

@@ -22,16 +22,16 @@ spec:
     virtualIPRef:
       name: virtualip-sample
 ```
-**Note**: For a detailed end-to-end example to understand the ephemeral and non `NetworkInterface`, please refer <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e">E2E Examples</a>
+**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>
 
 # Key Fields 
-- **networkRef**: `NetworkRef` is the Network this NetworkInterface is connected to
+- `networkRef`(`string`): `NetworkRef` is the Network this NetworkInterface is connected to
 
-- **ipFamilies**: `IPFamilies` defines the list of IPFamilies this `NetworkInterface` supports. For eg: `IPV4` and `IPV6`
+- `ipFamilies`(`list`): `IPFamilies` defines the list of IPFamilies this `NetworkInterface` supports. Supported values for IPFamily are `IPv4` and `IPv6`.
 
-- **ips**: `IPs` are the list of provided internal IPs which should be assigned to this NetworkInterface
+- `ips`(`list`): `IPs` are the list of provided internal IPs which should be assigned to this NetworkInterface
 
-- **virtualIP**: `VirtualIP` specifies the public ip that should be assigned to this NetworkInterface.
+- `virtualIP`: `VirtualIP` specifies the public ip that should be assigned to this NetworkInterface.
 
 # Reconciliation Process:
 
@@ -43,7 +43,7 @@ If the Machine is marked for deletion (indicated by a non-zero DeletionTimestamp
 Analyze the Machine's specification to identify the desired ephemeral NetworkInterface resources.
 Construct a map detailing these desired NetworkInterfaces, including their configurations and expected states.
 
-- **Fetch Existing Network Interfaces**:
+- **Fetch Existing NetworkInterfaces**:
 List all existing NetworkInterface resources within the same namespace as the Machine.
 
 - **Compare and Reconcile**:

docs/usage/networking/networkpolicy.md

@@ -64,7 +64,11 @@ https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-po
 
 - `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.
+- `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.
+
+  For example, a `NetworkPolicy` with a single ingress rule may permit traffic on a specific port and only from one of the following sources:
+  - An IP range, defined using an ipBlock.
+  - A set of resources identified by an 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.
 

docs/usage/networking/virtualip.md

@@ -11,14 +11,12 @@ metadata:
 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.
+- `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`.
+- `ipFamily`(`string`): `IPFamily` is the ip family of the VirtualIP. Supported values for IPFamily are `IPv4` and `IPv6`.
 
 
 # Reconciliation Process:
@@ -39,6 +37,11 @@ Requeue the reconciliation to retry the operation.
 Update the VirtualIP status to reflect the actual state of the APINet IP.
 If successfully allocated, update the status with the assigned IP address.
 
+  for example:
+  ```
+  #status:
+  #  ip: 10.0.0.1 # This will be populated by the corresponding controller.
+  ```
 - **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.