From c5171f482736bbfabccf595d92b4df9e0a448709 Mon Sep 17 00:00:00 2001 From: Rohit Kumar Date: Tue, 8 Jul 2025 16:02:59 +0530 Subject: [PATCH 1/3] Improve usage doc, fix typos and follow style guide --- docs/baremetal/index.md | 4 +- docs/baremetal/kubernetes/gardener.md | 10 +- .../metal-loadbalancer-controller.md | 9 +- docs/contribute/contributing.md | 33 ++- docs/iaas/architecture/networking.md | 14 +- docs/iaas/architecture/runtime-interface.md | 10 +- .../kubernetes/cloud-controller-manager.md | 8 +- docs/iaas/kubernetes/csi-driver.md | 6 +- docs/iaas/usage-guides/compute.md | 54 ++--- docs/iaas/usage-guides/core.md | 16 +- docs/iaas/usage-guides/index.md | 2 +- docs/iaas/usage-guides/ipam.md | 15 +- docs/iaas/usage-guides/networking.md | 228 +++++++----------- docs/iaas/usage-guides/storage.md | 21 +- 14 files changed, 170 insertions(+), 260 deletions(-) diff --git a/docs/baremetal/index.md b/docs/baremetal/index.md index 1ca017f..17f0503 100644 --- a/docs/baremetal/index.md +++ b/docs/baremetal/index.md @@ -7,14 +7,14 @@ in a Kubernetes-native way. It leverages the power of Kubernetes Custom Resource - **Provisioning**: Deploy and configure servers using Ignition. - **Day-2 Operations**: Manage BIOS, firmware, and hardware inventory declaratively. - **3rd Party Integrations**: Seamlessly integrate with existing tools like vendor-specific management tools. -- **Kubernetes Support**: Run Kubernetes on bare metal servers with support for Cluster API and Gardener. +- **Kubernetes Support**: Run Kubernetes on bare metal servers with support of Cluster API and Gardener. ## Core Components The core components of the baremetal automation in IronCore include: - [**Metal Operator**](https://github.com/ironcore-dev/metal-operator): The central component that manages the lifecycle of bare metal servers. - [**Boot Operator**](https://github.com/ironcore-dev/boot-operator): iPXE and HTTP boot server that provides boot images and Ignition configurations. -- [**FeDHCP**](https://github.com/ironcore-dev/fedhcp): A DHCP server that provides inband and out of band network configuration to bare metal servers. +- [**FeDHCP**](https://github.com/ironcore-dev/fedhcp): A DHCP server that provides in-band and out-of-band network configuration to bare metal servers. ## Concepts and Usage Guides diff --git a/docs/baremetal/kubernetes/gardener.md b/docs/baremetal/kubernetes/gardener.md index 171e098..630c75b 100644 --- a/docs/baremetal/kubernetes/gardener.md +++ b/docs/baremetal/kubernetes/gardener.md @@ -4,14 +4,12 @@ Apart from the [Cluster API Provider for Bare Metal](/baremetal/kubernetes/capi) [Gardener](https://gardener.cloud), a Kubernetes-native project for managing Kubernetes clusters at scale. There are two main components in the Gardener integration with IronCore: -- **Machine Controller Manager (MCM)**: This component is responsible for managing the lifecycle of machines in a - Kubernetes cluster. It uses the `metal-operator` API types to provision and manage bare metal servers. -- **Gardener Extension Provider**: This component provides the necessary integration points for Gardener to manage bare - metal clusters. +- **Machine Controller Manager (MCM)**: This component is responsible for managing the lifecycle of machines in a Kubernetes cluster. It uses the `metal-operator` API types to provision and manage bare metal servers. +- **Gardener Extension Provider**: This component provides the necessary integration points for Gardener to manage bare metal clusters. ## Machine Controller Manager (MCM) -The `[machine-controller-manager-provider-ironcore](https://github.com/ironcore-dev/machine-controller-manager-provider-ironcore-metal)` +The [machine-controller-manager-provider-ironcore](https://github.com/ironcore-dev/machine-controller-manager-provider-ironcore-metal) is responsible for managing the lifecycle of `Nodes` in a Kubernetes cluster. Here the MCM in essence is translating Gardener `Machine` resource to `ServerClaims` and wrapping the `user-data` coming from the Gardner OS extensions into an Ignition `Secret`. @@ -22,7 +20,7 @@ The [`gardener-extension-provider-ironcore-metal`](https://github.com/ironcore-d is responsible for providing the necessary integration points for Gardener to manage bare metal clusters. Those integration points include: -- Configure and the [Cloud Controller Manager](/baremetal/kubernetes/cloud-controller-manager) to handle the `Node` lifecycle +- Configure the [Cloud Controller Manager](/baremetal/kubernetes/cloud-controller-manager) to handle the `Node` lifecycle and topology information. - Configure the [metal-load-balancer-controller](/baremetal/kubernetes/metal-loadbalancer-controller) to handle `Service` of type `LoadBalancer`. - Configure the [Machine Controller Manager (MCM)](#machine-controller-manager-mcm) to manage the creation of `Nodes` in the cluster. diff --git a/docs/baremetal/kubernetes/metal-loadbalancer-controller.md b/docs/baremetal/kubernetes/metal-loadbalancer-controller.md index 627531d..7d99ab3 100644 --- a/docs/baremetal/kubernetes/metal-loadbalancer-controller.md +++ b/docs/baremetal/kubernetes/metal-loadbalancer-controller.md @@ -4,18 +4,15 @@ The [metal-loadbalancer-controller](https://github.com/ironcore-dev/metal-load-b for managing the lifecycle of `Services` of type `LoadBalancer` in a Kubernetes cluster running on bare metal servers. The project consists of two main components: - **Controller**: The main component that watches for changes in `Service` resources and manages the lifecycle of load balancers. -- **Speaker**: Is responsible for announcing the load balancer IP address to `metalbond` which acts as a route reflector - to the bare metal servers. +- **Speaker**: Is responsible for announcing the load balancer IP address to `metalbond` which acts as a route reflector to the bare metal servers. The `metal-loadbalancer-controller` is designed to work in an IPv6 only environment. ## Controller The controller component has the following responsibilities: -- Watches for changes in `Service` resources of type `LoadBalancer` and uses the `ClusterIP` of a `Service` and patches the - `LoadBalancer` status using this `ClusterIP`. -- Setting the `PodCIDRs` on the `Node` resources to ensure that the load balancer can route traffic to the pods. Here it - takes the main `Node` IP address and the configured `node-cidr-mask-size` and patches the `Node.spec.podCIDRs` field. +- Watches for changes in `Service` resources of type `LoadBalancer` and uses the `ClusterIP` of a `Service` and patches the `LoadBalancer` status using this `ClusterIP`. +- Setting the `PodCIDRs` on the `Node` resources to ensure that the load balancer can route traffic to the pods. Here it takes the main `Node` IP address and the configured `node-cidr-mask-size` and patches the `Node.spec.podCIDRs` field. ## Metalbond-Speaker diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md index e8833b1..1b4c8bd 100644 --- a/docs/contribute/contributing.md +++ b/docs/contribute/contributing.md @@ -12,9 +12,6 @@ We welcome contributions from the community! Follow these guidelines to help us - Feedback will be provided if any adjustments are necessary. Thank you for helping improve our documentation! -# Contributing to IronCore Documentation - -We welcome contributions from the community! Follow these guidelines to help us maintain high-quality, consistent documentation. ## Contributors Guide The IronCore Documentation project uses Github to manage reviews of pull requests. @@ -36,11 +33,11 @@ and us a good deal of inspiration. ## Steps to Contribute -Do you want to work on an issue? You are welcome to claim an existing one by commenting on it in GitHub. +Do you want to work on an issue? You are welcome to claim an existing one by commenting on it in GitHub. !!! note Perform a cursory search to see if the issue has already been taken by someone else. - This will prevent misunderstanding and duplication of effort from contributors on the same issue. + This will prevent misunderstanding and duplication of effort from contributors on the same issue. If you have questions about one of the issues please comment on them and one of the maintainers will clarify it. @@ -67,14 +64,14 @@ process. We use [the standard DCO text of the Linux Foundation](https://develope * Fork and clone the repository to your local machine. -```shell -git clone git@github.com:ironcore-dev/ironcore-dev.github.io.git -cd docs -``` + ```shell + git clone git@github.com:ironcore-dev/ironcore-dev.github.io.git + cd docs + ``` -* Create a branch from the `main` using 'git checkout' command. +* Create a branch from the `main` using 'git checkout' command. !!! note - If needed, rebase to the current `main` branch before submitting your pull request. If it doesn't merge properly + If needed, rebase to the current `main` branch before submitting your pull request. If it doesn't merge properly with `main` you may be asked to rebase your changes. ```shell @@ -86,13 +83,13 @@ cd docs * Commits should be as small as possible, while ensuring that each commit is correct independently -* Commit your changes to your feature branch and push it to your fork. +* Commit your changes to your feature branch and push it to your fork. -```shell -git add . -git commit -m "Something meaningful" -git push origin my_feature -``` + ```shell + git add . + git commit -m "Something meaningful" + git push origin my_feature + ``` !!! note Alternatively you can amend your commit before pushing if you forgot something by using `git commit --amend` @@ -111,7 +108,7 @@ for a review in the pull request or a comment. ## Issues and Planning -We use GitHub issues to track bugs and enhancement requests. Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to understand, reproduce the behavior and find related reports of that issue for the assignee. +We use GitHub issues to track bugs and enhancement requests. Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to understand, reproduce the behavior and find related reports of that issue for the assignee. Therefore, contributors may use but aren't restricted to the issue template provided by the IronCore maintainers. diff --git a/docs/iaas/architecture/networking.md b/docs/iaas/architecture/networking.md index fc1bd37..1ef4c7d 100644 --- a/docs/iaas/architecture/networking.md +++ b/docs/iaas/architecture/networking.md @@ -14,12 +14,12 @@ IronCore's virtual networking architecture is illustrated with the following fig The main elements involved in IronCore's networking are: - [**ironcore**](https://github.com/ironcore-dev/ironcore): Core networking component that manages network resources and configurations. For more details, see the - [Networking usage guide](/iaas/usage-guides/networking). +[Networking usage guide](/iaas/usage-guides/networking). - [**ironcore-net**](https://github.com/ironcore-dev/ironcore-net): Global coordination service that manages network resource in an IronCore instance. - [**metalnet**](https://github.com/ironcore-dev/metalnet): A service that provides cluster-level networking capabilities for `Machines`. - [**dpservice**](https://github.com/ironcore-dev/dpservice): A service that manages data plane operations, including network traffic routing and policies. - [**metalbond**](https://github.com/ironcore-dev/metalbond): A component that handles route announcements in an IronCore instance, ensuring that networking routes are - correctly propagated across the IronCore installation. +correctly propagated across the IronCore installation. ## `ironcore` and `ironcore-net` @@ -27,10 +27,8 @@ The main elements involved in IronCore's networking are: the place where all network related decisions like reservation of unique IP addresses, allocation of unique network IDs, etc. are made. `ironcore-net` has apart from its [own API](https://github.com/ironcore-dev/ironcore-net/tree/main/api/core/v1alpha1) two main components: -- **apinetlet**: This component is responsible from translating the user-facing API objects from the `networking` resource group into the - internal representation used by `ironcore-net`. -- **metalnetlet**: This component is interfacing with the `metalnet` API to manage cluster-level networking resources like `NetworkInterface` which - are requested globally in the `ironcore-net` API but are implemented by `metalnet` on a hypervisor level. +- **apinetlet**: This component is responsible from translating the user-facing API objects from the `networking` resource group into the internal representation used by `ironcore-net`. +- **metalnetlet**: This component is interfacing with the `metalnet` API to manage cluster-level networking resources like `NetworkInterface` which are requested globally in the `ironcore-net` API but are implemented by `metalnet` on a hypervisor level. ### Example `apinetlet` flow @@ -50,10 +48,10 @@ The `apinetlet` will reconcile this `VirtualIP` by performing the following step 1. Create an `IP` object in the `ironcore-net` API, which reserves a unique IP address. 2. Update the `VirtualIP` status with the allocated IP address. -The `ironcore` API server is agnostic on how the underlying global IP address is allocated and delegates this responsibility +The `IronCore` API server is agnostic on how the underlying global IP address is allocated and delegates this responsibility to `ironcore-net`. -A similar flow happens for `Networks`, `LoadBalancer` and `NatGateways` resources, where the `apinetlet` is responsible +A similar flow happens for `Network`, `LoadBalancer` and `NatGateway` resources, where the `apinetlet` is responsible for translating and allocating the necessary resources in `ironcore-net` to ensure that the networking requirements are met. ### `metalnetlet` and `metalnet` diff --git a/docs/iaas/architecture/runtime-interface.md b/docs/iaas/architecture/runtime-interface.md index 5ee781e..4099e10 100644 --- a/docs/iaas/architecture/runtime-interface.md +++ b/docs/iaas/architecture/runtime-interface.md @@ -1,6 +1,6 @@ # IronCore Runtime Interface (IRI) -The IronCore Runtime Interface (IRI) is a key concept in the IronCore architecture, designed to provide a consitent +The IronCore Runtime Interface (IRI) is a key concept in the IronCore architecture, designed to provide a consistent and unified interface for interacting with various compute and storage providers. The IRI abstracts the underlying complexities of different providers. @@ -12,7 +12,7 @@ There are three main runtime interfaces in IronCore: Implementations of these interfaces are done by provider-specific components. More infomation about the provider can be found in the [provider concept documentation](/iaas/architecture/providers/). -The definition of the runtime interfaces can be found in IronCores [`iri` package](https://github.com/ironcore-dev/ironcore/tree/main/iri/). +The definition of the runtime interfaces can be found in IronCore's [`iri` package](https://github.com/ironcore-dev/ironcore/tree/main/iri/). ## MachineRuntime Interface @@ -40,9 +40,7 @@ service MachineRuntime { } ``` -The general idea is that a `machinepoollet` ensures that the API level dependencies are met. For example, a `Machine`s -`Volume` which is used as a root disk is in the state `Available`. If those prerequisites are met, the `poollet` will -call the corresponding `CreateMachine` method of the `RuntimeInterface` to create the `Machine` resource. +The general idea is that a `machinepoollet` ensures that the API level dependencies are met. For example, a `Machine`'s `Volume` which is used as a root disk is in the state `Available`. If those prerequisites are met, the `poollet` will call the corresponding `CreateMachine` method of the `RuntimeInterface` to create the `Machine` resource. The `ListMachines` and `Status` methods are used to retrieve a list of all `Machine` instances managed by the provider. The result of those methods is then used to propagate `Machine` state changes. Those methods are periodically called by @@ -53,7 +51,7 @@ methods to attach volumes or network interfaces to a `Machine` if a change in th ## VolumeRuntime Interface -Similar to the `MachineRuntime`, the `VolumeRuntime` interface is responsible for managing storage resources in IronCore. +Similar to the `MachineRuntime`, the `VolumeRuntime` interface is responsible for managing block storage resources in IronCore. Here the `volumepoollet` takes a similar role as the `machinepoollet` for the `MachineRuntime` and invokes `CreateVolume`, `DeleteVolume`, `ExpandVolume`, and other methods to manage `Volume` resources. diff --git a/docs/iaas/kubernetes/cloud-controller-manager.md b/docs/iaas/kubernetes/cloud-controller-manager.md index 387c262..16960f8 100644 --- a/docs/iaas/kubernetes/cloud-controller-manager.md +++ b/docs/iaas/kubernetes/cloud-controller-manager.md @@ -27,10 +27,10 @@ Below is the detailed explanation on how APIs are implemented by `cloud-provider InstanceMetadata returns metadata of a node instance, which includes : -- `ProviderID`: Provider is combination of ProviderName(Which is nothing but set to `IronCore`) -- `InstanceType`: InstanceType is set to referencing MachineClass name by the instance. +- `ProviderID`: Provider is combination of ProviderName(Which is nothing but set to `IronCore`) +- `InstanceType`: InstanceType is set to referencing MachineClass name by the instance. - `NodeAddresses`: Node addresses are calculated from the IP information available from NetworkInterfaces of the machine. -- `Zone`: Zone is set to referenced MachinePool name. +- `Zone`: Zone is set to referenced MachinePool name. ## Load balancing for Services of type LoadBalancer @@ -47,7 +47,7 @@ explanation on how APIs are implemented in IronCore cloud-provider. ### Ensure LoadBalancer - `EnsureLoadBalancer` gets the LoadBalancer name based on service name. -- Checks if IronCore `LoadBalancer` object already exists. If not it gets the `port` and `protocol`, `ipFamily` information from the service and creates a new LoadBalancer object in the Ironcore. +- Checks if IronCore `LoadBalancer` object already exists. If not it gets the `port` and `protocol`, `ipFamily` information from the service and creates a new LoadBalancer object in the Ironcore. - Newly created LoadBalancer will be associated with Network reference provided in cloud configuration. - Then `LoadBalancerRouting` object is created with the destination IP information retrieved from the nodes (Note: `LoadBalancerRouting` is internal object to Ironcore). Later, this information is used at the Ironcore API level to describe the explicit targets in a pool traffic is routed to. - Ironcore supports two types of LoadBalancer `Public` and `Internal`. If LoadBalancer has to be of type Internal, "service.beta.kubernetes.io/ironcore-load-balancer-internal" annotation needs to be set to true, otherwise it will be considered as public type. diff --git a/docs/iaas/kubernetes/csi-driver.md b/docs/iaas/kubernetes/csi-driver.md index 1402323..69b5c04 100644 --- a/docs/iaas/kubernetes/csi-driver.md +++ b/docs/iaas/kubernetes/csi-driver.md @@ -8,7 +8,7 @@ management capabilities. ## IronCore CSI Driver Integration -The [Ironcore CSI Driver](https://github.com/ironcore-dev/ironcore-csi-driver) is implemented as a Kubernetes storage +The [IronCore CSI Driver](https://github.com/ironcore-dev/ironcore-csi-driver) is implemented as a Kubernetes storage plugin that bridges the gap between Kubernetes storage management and IronCore's `storage` resource types. The core components of the IronCore CSI driver include: @@ -20,8 +20,8 @@ The core components of the IronCore CSI driver include: The CSI driver supports various storage class parameters for customizing volume provisioning: -- **Volume Type**: Specifies the type of volume to be created (e.g., standard, high-performance) -- **AllowVolumeExpansion**: This Specifies the Volume can be resized if set to `true` and the respective volume Type has `ResizePolicy` set to `ExpandOnly` +- **Volume Type**: Specifies the type of volume to be created (e.g., standard, high-performance). +- **AllowVolumeExpansion**: This specifies that the `Volume` can be resized if set to `true` and the respective volume Type has `ResizePolicy` set to `ExpandOnly`. ### Volume Management diff --git a/docs/iaas/usage-guides/compute.md b/docs/iaas/usage-guides/compute.md index 19eda22..d6348d1 100644 --- a/docs/iaas/usage-guides/compute.md +++ b/docs/iaas/usage-guides/compute.md @@ -1,5 +1,7 @@ # Compute Resources +IronCore compute resources are `Machines`, their associated `Machineclasses` and `MachinePools` that allow you to define, provision, and manage virtual machines. This guide explains the core compute resource types and how to use them. + ## Machine A `Machine` resource in IronCore is used to represent a compute resource or a virtual machine. It serves as a means to @@ -34,48 +36,21 @@ spec: - `machineClassRef` (`string`): Is a reference to the `MachineClass` of the machine. - `machinePoolRef` (`string`): Defines the `MachinePool` to run the `Machine` on. If empty, the IronCore scheduler will figure out an appropriate pool to run the `Machine` on. -- `image` (`string`): Image is the optional URL providing the operating system image to memory boot the `Machine`. A detailed description of OS images can be found the corresponding [section](/iaas/architecture/os-images). +- `image` (`string`): Image is the optional URL providing the operating system image to memory boot the `Machine`. A detailed description of OS images can be found in the corresponding [section](/iaas/architecture/os-images). - `volumes` (`list`): Are list of `Volumes` attached to this machine. Here the first volume is considered as the root disk. Each volume is defined with a name and a reference to the `Volume` resource. - `networkInterfaces` (`list`): Define a list of network interfaces present on the machine. -- `ignitionRef` (`string`): Is a reference to a `secret` containing the ignition YAML for the machine to boot up. If the `key` value is empty, the `DefaultIgnitionKey=ignition` will be used as a fallback. - - -### Reconciliation Process - -1. **Machine Scheduling**: - The `MachineScheduler` controller continuously watches for `Machines` without an assigned `MachinePool` and tries to schedule it on available and matching MachinePool. -- **Monitor Unassigned Machines**: The scheduler continuously watches for machines without an assigned `machinePoolRef`. -- **Retrieve Available Machine Pools**: The scheduler fetches the list of available machine pools from the cache. -- **Make Scheduling Decisions**: The scheduler selects the most suitable machine pool based on resource availability and other policies. -- **Update Cache**: The scheduler updates the cache with recalculated allocatable `machineClass` quantities. -- **Assign MachinePoolRef**: The scheduler assigns the selected `machinePoolRef` to the machine object. - -More information on how the IRI contract works can be found in the [IronCore Runtime Interface (IRI)](/iaas/architecture/runtime-interface) section. +- `ignitionRef` (`string`): Is a reference to a `Secret` containing the ignition YAML for the machine to boot up. If the `key` value is empty, the `DefaultIgnitionKey=ignition` will be used as a fallback. -4. **Network Interface handling**: `MachineControllerNetworkinterface` takes care of attaching/detaching `NetworkInterfaces` defined for the `Machine`. Once the attachment is successful status is updated from `Pending` to `Attached`. - -5. **Volume handling**: `MachineControllerVolume` takes care of attach/detach of `Volumes` defined for a `Machine`. Once the attachment is successful status is updated from `Pending` to `Attached`. - -6. **Ephemeral resource handling**: -- The `Volume` and `NetworkIntreface` can be bound with the lifecycle of the Machine by creating them as ephemeral resources. (`Note`: For more details on how to create ephemeral resources refer to Machine with ephemeral resources) -- If a `NetworkIntreface` or a `Volume` is defined as ephemeral `MachineEphemeralControllers` takes care of creating and destroying respective objects on creation/deletion of the machine. - -### Lifecycle and States - -A Machine can be in the following states: -1. **Pending**: A Machine is in a Pending state when the Machine has been accepted by the system, but not yet completely started. This includes time before being bound to a MachinePool, as well as time spent setting up the Machine on that MachinePool. -2. **Running**: A Machine in Running state when the machine is running on a MachinePool. -2. **Shutdown**: A Machine is in a Shutdown state. -3. **Terminating**: A Machine is Terminating. -2. **Terminated**: A Machine is in the Terminated state when the machine has been permanently stopped and cannot be started. +Detailed e2e examples on `Machine` creation with ephemeral/non-ephemeral `Volume` and `NetworkInterface` +- [Machine with ephemeral resources](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/machine-with-ephemeral-resources) +- [Machine with non ephemeral resources](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/machine-with-non-ephemeral-resources) ## MachineClass A `MachineClass` is an IronCore resource used to represent a class/flavor of a `Machine`. It serves as a means to -define the number of resources a `Machine` object can have as capabilities (e.g. CPU, memory) associated with a -particular class. +define the number of resources a `Machine` object can have as capabilities (e.g. CPU, memory) associated with a particular class. -### Example Machine Resource +### Example MachineClass Resource An example of how to define a `MachineClass` resource: @@ -91,15 +66,17 @@ capabilities: **Key Fields**: -- capabilities (`ResourceList`): capabilities are used to define a list of resources a Machine can have along with its capacity. +- `capabilities` (`ResourceList`): Capabilities are used to define a list of resources a Machine can have, along with its capacity. ## MachinePool A `MachinePool` is a resource in IronCore that represents a pool of compute resources managed collectively. It defines the infrastructure's compute configuration used to provision and manage `Machines`, ensuring resource availability and -compatibility with associated `MachineClasses`. (`Note`: One `machinepoollet` is responsible for one `MachinePool`) +compatibility with associated `MachineClasses`. + +> Note:One `machinepoollet` is responsible for one `MachinePool`. -Details on how `Pools` are announced and used can be found in the [Pools and Poollets](/iaas/architecture/scheduling) section. +Details on how `MachinePools` are announced and used can be found in the [Pools and Poollets](/iaas/architecture/scheduling) section. ### Example MachinePool Resource @@ -116,5 +93,4 @@ spec: **Key Fields**: -- `ProviderID`(`string`): The `providerId` helps the controller identify and communicate with the correct compute - system within the specific backend compute provider. +- `providerID` (`string`): The `providerId` helps the controller identify and communicate with the correct compute system within the specific backend compute provider. diff --git a/docs/iaas/usage-guides/core.md b/docs/iaas/usage-guides/core.md index 8b56851..eca8879 100644 --- a/docs/iaas/usage-guides/core.md +++ b/docs/iaas/usage-guides/core.md @@ -1,11 +1,12 @@ # Core Resources +This guide describes the core resource types in IronCore and how to use them to manage and limit resource usage. + ## ResourceQuota A `ResourceQuota` in IronCore provides a mechanism to manage and limit the usage of resources across multiple requesting entities. This allows protecting the system from usage spikes and services can be kept responsive. With the -help of `ResourceQuota` a hard limit with a list of resources along with `ScopeSelector` can be set for `Namespace` and -restricted hereby the amount of resources a user can create. +help of `ResourceQuota`, you can set a hard limit with a list of resources and a `ScopeSelector` for a `Namespace`, restricting the amount of resources a user can create. ::: tip `ResourceQuota` is a namespaced resource, and it can only limit resource count/accumulated resource usage within a defined namespace. @@ -29,16 +30,9 @@ spec: ### Key Fields: -- `hard`(`ResourceList`): Is a `ResourceList` of the strictly enforced number of resources. `ResourceList` is a list of ResourceName alongside their resource quantity. -- `scopeSelector`(`ResourceScopeSelector`): scopeSelector selects the resources that are subject to this quota. +- `hard` (`ResourceList`): Is a `ResourceList` of the strictly enforced number of resources. `ResourceList` is a list of ResourceName alongside their resource quantity. +- `scopeSelector` (`ResourceScopeSelector`): scopeSelector selects the resources that are subject to this quota. ::: tip By using `scopeSelectors`, only certain resources like CPU and memory may be tracked. ::: - -### Reconciliation Process: - -- **Gathering matching evaluators**: The `ResourceQuotaController` retrieves all the matching evaluators from the registry for the specified resources in hard spec. Each resource evaluator implements set of Evaluator interface methods which helps in retrieving the current usage of that particular resource type. -- **Calculating resource usage**: Resource usage is calculated by iterating over each evaluator and listing the namespace resource of that particular type. Listed resources are then filtered out by matching specified scope selector and accumulated usage is calculated. -- **Status update**: Once usage data is available, the `ResourceQuota` status is updated with the enforced hard resource limits and currently used resources. -- **Resource quota handling**: On request of create/update resources whether to allow creating/update based on `ResourceQuota` usage is handled via admission controller. Resources that would exceed the quota will fail with HTTP status code 403 Forbidden. diff --git a/docs/iaas/usage-guides/index.md b/docs/iaas/usage-guides/index.md index ebfb516..f9e53fd 100644 --- a/docs/iaas/usage-guides/index.md +++ b/docs/iaas/usage-guides/index.md @@ -7,4 +7,4 @@ operations. Those guides are intended to give the user a comprehensive understan More examples and detailed usage can be found in the [end to end examples](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e) in the `ironcore` repository. -Detailed API references for the IronCore IaaS types can be found in the [API References](../api-references/) section. \ No newline at end of file +Detailed API references for the IronCore IaaS types can be found in the [API References](../api-references/) section. diff --git a/docs/iaas/usage-guides/ipam.md b/docs/iaas/usage-guides/ipam.md index 2b16d34..93fad52 100644 --- a/docs/iaas/usage-guides/ipam.md +++ b/docs/iaas/usage-guides/ipam.md @@ -1,4 +1,5 @@ # IPAM Resources +This guide explains how to use IronCore's integrated IP address management (IPAM) resources to define and manage IP prefixes and allocations. ## Prefix @@ -6,7 +7,7 @@ A `Prefix` resource provides a fully integrated IP address management (IPAM) sol means to define IP prefixes along with prefix length to a reserved range of IP addresses. It is also possible to define child prefixes with the specified prefix length referring to the parent prefix. -### Example Volume Resource +### Example Prefix Resource An example of how to define a root `Prefix` resource in IronCore: @@ -38,21 +39,15 @@ spec: ### Key Fields: -- `ipFamily`(`string`): Is the IPFamily of the prefix. If unset but `Prefix` is set, this can be inferred. +- `ipFamily` (`string`): Is the IPFamily of the prefix. If unset but `Prefix` is set, this can be inferred. - `prefix` (`string`): `prefix` is the IP prefix to allocate for this Prefix. - `prefixLength` (`int`): `prefixLength` is the length of prefix to allocate for this Prefix. - `parentRef` (`string`): `parentRef` references the parent to allocate the Prefix from. If `parentRef` and `parentSelector` is empty, the Prefix is considered a root prefix and thus allocated by itself. - `parentSelector` (`LabelSelector`): `parentSelector` is the LabelSelector to use for determining the parent for this Prefix. +Once prefix allocation is successful, status is updated to `Allocated`. In the case of sub-prefixes once the prefix is allocated the parent Prefix's status gets updated with the used prefix IPs list. -# Reconciliation Process: - -- **Allocate root prefix**: If `parentRef` and `parentSelector` is empty, the PrefixController reconciler considers it as a root prefix and allocates by itself and the status is updated as `Allocated`. -- **Allocating sub-prefix**: If `parentRef` or `parentSelector` is set PrefixController lists all the previously allocated prefix allocations by parent prefix. Finds all the active allocations and prunes outdated ones. If no existing PrefixAllocation object is found new `PrefixAllocation` object is created for the new prefix to allocate. If prefix allocation is successful status is updated to `Allocated` otherwise to `Failed`. -- **Prefix allocation scheduler**: `PrefixAllocationScheduler` continuously watches for Prefix resource and tries to schedule all PrefixAllocation objects for which prefix is not yet allocated. PrefixAllocationScheduler determines suitable prefix for allocation by listing available prefixes based on label filter, namespace and desired IP family. Once a suitable prefix is found PrefixAllocation spec.parentRef is updated with the selected prefix reference. -- **Status update**: Once prefix allocation is successful status is updated to `Allocated`. In the case of sub-prefixes once the prefix is allocated `PrefixController` updates the parent Prefix's status with the used prefix IPs list. - -Below is the sample `Prefix.status` : +Below is the sample `Prefix.status`: ```yaml status: diff --git a/docs/iaas/usage-guides/networking.md b/docs/iaas/usage-guides/networking.md index df5ad70..2a29eea 100644 --- a/docs/iaas/usage-guides/networking.md +++ b/docs/iaas/usage-guides/networking.md @@ -1,5 +1,7 @@ # Networking Resources +This guide describes the core networking resources in IronCore, such as `Networks`, `NetworkInterfaces`, `VirtualIPs`, `NAT gateways`, `LoadBalancers`, and `NetworkPolicies`. It explains how to define, configure, and manage these resources for the infrastructure. + ## Network A `Network` resource in IronCore refers to a logically isolated network (Layer 3). This further allows you to fully @@ -22,35 +24,55 @@ spec: ``` ### Key Fields: -- `providerID`(`string`): Is the provider-internal ID of the network. -- `peerings`(`list`): Are the list of network peerings with this `Network` (optional). -- `incomingPeerings`(`list`): Is a list of `PeeringClaimRef`s which are peering claim references of other `Networks`. -### Reconciliation Process: +- `peerings` (`list`): Are the list of network peerings with this `Network` (optional). + + +### More about IronCore Network: -- **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. - 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`. - Once the `Network` resource is in an available state. The format of a network provider ID is as follows: - `ironcore-net://///` +- **Network creation**: [ironcore-net](https://github.com/ironcore-dev/ironcore-net) is the network plugin for IronCore that realizes the `Network` resource, When an IronCore `Network` is created, a corresponding `core.apinet.ironcore.dev/Network` is created in the ironcore-net(apinet) cluster. +Once created and with an allocated ID, the IronCore `Network` will be patched with the corresponding providerID of the apinet Network and set to state: `Available`. +The format of a network providerID is as follows: +`ironcore-net://///` -- **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. +- **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. - 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. + - 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. + + +After successful reconciliation, the Ironcore `Network` resource gets updated with `providerID`, `incomingpeerings` and `status`. + +```yaml +apiVersion: networking.ironcore.dev/v1alpha1 +kind: Network +metadata: + name: network-sample +spec: + peerings: + - name: peering1 + networkRef: + - name: network-sample2 + incomingPeerings: + - name: network-sample2 + providerID: ironcore-net://ironcore-net-system/15e43205-3cfe-4b27-a29c-4ade42b94fca/11621310/292f19b4-2ff4-41e8-b324-075550340786 +status: + peerings: + - name: peering1 + state: Ready + state: Available + +``` -- **Network Release Controller**: `NetworkReleaseController` continuously checks if claiming `Networks` in another Network's peerings section still exist if not present it will be removed from the `incomingPeerings` list. +For detailed e2e example on network peering +- [e2e example networkpeering](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-peering) ## NetworkInterface -A `NetworkInterface` resource in IronCore represents a connection point between and a `Machine` and a virtual +A `NetworkInterface` resource in IronCore represents a connection point between a `Machine` and a virtual network. It encapsulates the configuration and life cycle management of the virtual network interface, ensuring seamless connectivity for `Machines`. -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. ### Example NetworkInterface Resource @@ -75,34 +97,12 @@ spec: ### Key Fields -- `networkRef`(`string`): `NetworkRef` is the `Network` this `NetworkInterface` is connected to. -- `ipFamilies`(`list`): `IPFamilies` defines the list of IPFamilies this `NetworkInterface` supports. Supported values for IPFamily are `IPv4` and `IPv6`. -- `ips`(`list`): `IPs` are the list of provided internal IPs which should be assigned to this NetworkInterface +- `networkRef` (`string`): `NetworkRef` is the `Network` this `NetworkInterface` is connected to. +- `ipFamilies` (`list`): `IPFamilies` defines the list of IPFamilies this `NetworkInterface` supports. Supported values for IPFamily are `IPv4` and `IPv6`. +- `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. -### Reconciliation Process: - -- **Generate Desired Ephemeral Network Interfaces**: - 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 NetworkInterfaces**: - List all existing `NetworkInterface` resources within the same namespace as the Machine. - -- **Compare and Reconcile**: - - For each existing `NetworkInterface`: - Determine if it is managed by the current `Machine` and whether it matches the desired state. - - If unmanaged but should be managed, avoid adopting it to prevent conflicts. - - For each desired `NetworkInterface` which is not present: - Create the missing `NetworkInterface` and establish the Machine as its controller. - -- **Handle Errors**: - Collect any errors encountered during the reconciliation of individual `NetworkInterfaces`. - Log these errors and schedule retries as necessary to ensure eventual consistency. - -- **Update Status**: - 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. +After successful reconciliation of all `NetworkInterfaces`, the status gets updated with the corresponding values for `ips`, `state`, and `virtualIP`, as shown below. ```yaml status: @@ -113,18 +113,13 @@ status: virtualIP: 172.89.244.23 ``` -The `state` is updated as one of the following lifecycle states based on the reconciliation result -- **Pending** -- **Available** -- **Error** - ## VirtualIP -A `VirtualIP` (VIP) in the IronCore API is an abstract network resource representing an IP address that that is +A `VirtualIP` (VIP) in the IronCore API is an abstract `Network` resource representing an IP address that is allocated and kept during the lifetime of the `VirtualIP` resource. It can be associated with a `NetworkInterface` of a `Machine` exposing this `Machine` e.g. to the public internet. -### Examaple VirtualIP Resource +### Example VirtualIP Resource An example of how to define a `VirtualIP` resource in IronCore: @@ -139,43 +134,26 @@ spec: ``` ### 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` and `IPv6`. - - -### Reconciliation Process: +- `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` and `IPv6`. -- **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. + After successful reconciliation of the `VirtualIP` resource, the status gets updated with the corresponding public IP address. -- **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. +for example: +```yaml +status: + ip: 10.0.0.1 # This will be populated by the corresponding controller. +``` - for example: - ```yaml - status: - ip: 10.0.0.1 # This will be populated by the corresponding controller. - ``` - - **Networking Configuration**: - - `Machine` Integration: The allocated `VirtualIP` is associated with the `Machine` in the `VirtualIP` part of the `NetworkInterface` spec. - - Load Balancer Integration: If a load balancer is used, the `VirtualIP` is configured as the frontend IP to route requests to the `Machine`. + - `Machine` Integration: The allocated `VirtualIP` is associated with the `Machine` in the `VirtualIP` part of the `NetworkInterface` spec. + - Load Balancer Integration: If a load balancer is used, the `VirtualIP` is configured as the frontend IP to route requests to the `Machine`. ## NATGateway In the IronCore API, 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. +private subnets, ensuring that instances in private subnets can access external services without exposing them to unauthorized inbound traffic. ### Example NATGateway Resource @@ -196,22 +174,13 @@ spec: ``` ### 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. - -### 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 `NATGateways` to detect any changes or drifts from the desired state, triggering the reconciliation process as needed. - - Creation: If a `NATGateway` 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 `NATGateway` 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 `NATGateway` 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. +- `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. + + +After reconciling all `NATGateways`, the status gets updated with the corresponding values for `ips` as shown below. ```yaml status: @@ -224,10 +193,10 @@ status: 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 single stack +allows targeting multiple `NetworkInterfaces` and distributes traffic among them. This LoadBalancer supports single stack (IPv4 or IPv6) or dual stack IP addresses (IPv4/IPv6). -### Example Network Resource +### Example LoadBalancer Resource An example of how to define a `LoadBalancer` resource in IronCore: @@ -251,23 +220,17 @@ spec: ``` ### Key Fields: -- `type`(`string`): 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`): ipFamilies are the IP families the LoadBalancer 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 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. +- `type` (`string`): 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`): ipFamilies are the IP families the LoadBalancer 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 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. Sample `LoadBalancerRouting` object which is an internal type and is created by the `LoadBalancerController`: @@ -288,12 +251,15 @@ destinations: uid: 2020dcf9-e030-427e-b0fc-4fec2016e73d ``` -**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`. +The `LoadBalancerController` in [ironcore-net](https://github.com/ironcore-dev/ironcore-net/blob/main/apinetlet/controllers/loadbalancer_controller.go) takes care of allocating IPs for defined `ipFamilies` in the spec and updates them in its `status.ips`. + +For a detailed e2e example on LoadBalancer +- [e2e example LoadBalancer](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/loadbalancer-public) ## NetworkPolicy In IronCore, `NetworkPolicies` are implemented based on the standard Kubernetes `NetworkPolicy` approach, which is -enforced by the underlying IronCore's network plugin ironcore-net and other components. +enforced by the underlying IronCore's network plugin [ironcore-net](https://github.com/ironcore-dev/ironcore-net/blob/main/apinetlet/controllers/networkpolicy_controller.go) 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. @@ -350,30 +316,20 @@ spec: ### 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`): 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. +- `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`): 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. + - 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. -### Reconciliation Process: -The `NetworkPolicyReconciler` in the IronCore project is responsible for managing the lifecycle of `NetworkPolicy` +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 apinetlet -component in `ironcore-net` plugin is responsible for translating the policy rules into another `apinet` resource named -`NetworkPolicyRule`. Finally, the metalnetlet -component in `ironcore-net` and propagates these rules for enforcement at `metalnet` 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. +For more detailed e2e example on `NetworkPolicy` +- [e2e example on NetworkPolicy](https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/network-policy) diff --git a/docs/iaas/usage-guides/storage.md b/docs/iaas/usage-guides/storage.md index f9c7405..72f1b08 100644 --- a/docs/iaas/usage-guides/storage.md +++ b/docs/iaas/usage-guides/storage.md @@ -1,8 +1,9 @@ # Storage Resources +IronCore storage resources are `Volumes`, their associated `Volumeclasses` and `VolumePools` that allow you to define, provision, and manage Block devices in the Ironcore infrastructure. This guide explains the core storage resource types and how to use them. ## Volume -The `Volume` resource is representing a block device in the IronCore API. +The `Volume` resource represents a block device in the IronCore API. ### Example Volume Resource @@ -24,7 +25,7 @@ spec: ### Key Fields: -- `volumeClassRef`(`string`): `volumeClassRef` refers to the name of an IronCore `volumeClass`( for eg: `slow`, `fast`, `super-fast` etc.) to create a volume, +- `volumeClassRef` (`string`): `volumeClassRef` refers to the name of an IronCore `volumeClass`( for eg: `slow`, `fast`, `super-fast` etc.) to create a volume, - `volumePoolRef` (`string`): `VolumePoolRef` indicates which VolumePool to use for a volume. If unset, the scheduler will figure out a suitable `VolumePoolRef`. - `resources`: `Resources` is a description of the volume's resources and capacity. @@ -48,8 +49,8 @@ capabilities: ### Key Fields: - `capabilities`: Capabilities has tps and iops fields that need to be specified, it's a mandatory field, - - `tps`(`string`): The `tps` represents transactions per second. - - `iops`(`string`): `iops` is the number of input/output operations a storage device can complete per second. + - `tps` (`string`): The `tps` represents transactions per second. + - `iops` (`string`): `iops` is the number of input/output operations a storage device can complete per second. ### Usage @@ -76,7 +77,7 @@ spec: ``` ### Key Fields: -- `providerID`(`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage porvider. +- `providerID` (`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage provider. ## Bucket @@ -100,11 +101,11 @@ spec: ``` ### Key Fields: -- `bucketClassRef`(`string`): +- `bucketClassRef` (`string`): - Mandatory field - `BucketClassRef` is the `BucketClass` of a bucket -- `bucketPoolRef`(`string`): +- `bucketPoolRef` (`string`): - Optional field - `bucketPoolRef` indicates which `BucketPool` to use for the `Bucket`, if not specified the controller itself picks the available `BucketPool` @@ -137,8 +138,8 @@ capabilities: ### Key Fields: - `capabilities`: Capabilities has `tps` and `iops` fields which need to be specified, it's a mandatory field, - - `tps`(`string`): The `tps` represents transactions per second. - - `iops`(`string`): `iops` is the number of input/output operations a storage device can complete per second. + - `tps` (`string`): The `tps` represents transactions per second. + - `iops` (`string`): `iops` is the number of input/output operations a storage device can complete per second. ### Usage @@ -167,4 +168,4 @@ spec: ### Key Fields: -- `ProviderID`(`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage porvider. +- `ProviderID` (`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage provider. From e9799d3e5af0136379c4cd75bd053fe795a19158 Mon Sep 17 00:00:00 2001 From: Rohit Kumar Date: Wed, 9 Jul 2025 12:56:47 +0530 Subject: [PATCH 2/3] Replace baremetal with `bare metal` to maintain consistency --- docs/baremetal/architecture/discovery.md | 2 +- docs/baremetal/architecture/provisioning.md | 2 +- docs/baremetal/index.md | 6 +++--- docs/iaas/architecture/networking.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/baremetal/architecture/discovery.md b/docs/baremetal/architecture/discovery.md index d99d45b..b9ab470 100644 --- a/docs/baremetal/architecture/discovery.md +++ b/docs/baremetal/architecture/discovery.md @@ -1,6 +1,6 @@ # Server Discovery and First Boot -This document describes the discovery and first boot process for bare metal servers in IronCore's baremetal automation. +This document describes the discovery and first boot process for bare metal servers in IronCore's bare metal automation. The goal here is to provide a clear understanding of how bare metal servers are discovered and prepared for provisioning. ## Server Discovery diff --git a/docs/baremetal/architecture/provisioning.md b/docs/baremetal/architecture/provisioning.md index f79047a..f7220c4 100644 --- a/docs/baremetal/architecture/provisioning.md +++ b/docs/baremetal/architecture/provisioning.md @@ -1,6 +1,6 @@ # Server Provisioning -This section describes how the provisioning of bare metal servers is handled in IronCore's baremetal automation. +This section describes how the provisioning of bare metal servers is handled in IronCore's bare metal automation. In the [discovery section](/baremetal/architecture/discovery) we discussed how servers are discovered and first time booted and how they are transitioned into an `Available` state. Now we will focus on the provisioning process, and one can use such a `Server` resource to provision a custom operating system and automate the software installation on diff --git a/docs/baremetal/index.md b/docs/baremetal/index.md index 17f0503..7e41446 100644 --- a/docs/baremetal/index.md +++ b/docs/baremetal/index.md @@ -1,6 +1,6 @@ # Baremetal Automation -The baremetal automation in IronCore is designed to provide a comprehensive solution for managing physical servers +The bare metal automation in IronCore is designed to provide a comprehensive solution for managing physical servers in a Kubernetes-native way. It leverages the power of Kubernetes Custom Resource Definitions (CRDs) to automate: - **Discovery**: Automatically detect and register bare metal servers. @@ -11,7 +11,7 @@ in a Kubernetes-native way. It leverages the power of Kubernetes Custom Resource ## Core Components -The core components of the baremetal automation in IronCore include: +The core components of the bare metal automation in IronCore include: - [**Metal Operator**](https://github.com/ironcore-dev/metal-operator): The central component that manages the lifecycle of bare metal servers. - [**Boot Operator**](https://github.com/ironcore-dev/boot-operator): iPXE and HTTP boot server that provides boot images and Ignition configurations. - [**FeDHCP**](https://github.com/ironcore-dev/fedhcp): A DHCP server that provides in-band and out-of-band network configuration to bare metal servers. @@ -22,7 +22,7 @@ Usage guides and concepts for the `metal-operator` API types can be found in the ## Prerequisites -The current implementation of the baremetal automation in IronCore requires the following prerequisites: +The current implementation of the bare metal automation in IronCore requires the following prerequisites: - In-band and out-of-band network connectivity to the bare metal servers. - A management server in the out-of-band network that can communicate with the bare metal servers. diff --git a/docs/iaas/architecture/networking.md b/docs/iaas/architecture/networking.md index 1ef4c7d..6cf0a28 100644 --- a/docs/iaas/architecture/networking.md +++ b/docs/iaas/architecture/networking.md @@ -2,7 +2,7 @@ ## Overview -IronCore's virtual networking architecture provides an end-to-end virtual networking solution for provisioned `Machine`s running in data centers, regardless they are baremetal machines or virtual machines. It is designed to enable robust, flexible and performing networking control plane and data plane. +IronCore's virtual networking architecture provides an end-to-end virtual networking solution for provisioned `Machine`s running in data centers, regardless they are bare metal machines or virtual machines. It is designed to enable robust, flexible and performing networking control plane and data plane. - **Robust**: IronCore's virtual networking control plane is mainly implemented using Kubernetes controller model. Thus, it is able to survive component's failure and recover the running states by retrieving the desired networking configuration. - **Flexible**: Thanks to the modular and layered architecture design, IronCore's virtual networking solution allows developers to implement and interchange components from the most top-level data center management system built upon defined IronCore APIs, to lowest-level packet processing engines depending on the used hardware. From c891dd20b7b0d2f282427c1a97e8faa9501bff4f Mon Sep 17 00:00:00 2001 From: Rohit Kumar Date: Tue, 15 Jul 2025 17:50:01 +0530 Subject: [PATCH 3/3] address review comments --- docs/contribute/contributing.md | 31 ++++++++++++++-------------- docs/iaas/usage-guides/ipam.md | 1 + docs/iaas/usage-guides/networking.md | 9 ++------ 3 files changed, 18 insertions(+), 23 deletions(-) diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md index 1b4c8bd..1986e9a 100644 --- a/docs/contribute/contributing.md +++ b/docs/contribute/contributing.md @@ -64,32 +64,32 @@ process. We use [the standard DCO text of the Linux Foundation](https://develope * Fork and clone the repository to your local machine. - ```shell - git clone git@github.com:ironcore-dev/ironcore-dev.github.io.git - cd docs - ``` +```shell +git clone git@github.com:ironcore-dev/ironcore-dev.github.io.git +cd docs +``` * Create a branch from the `main` using 'git checkout' command. !!! note If needed, rebase to the current `main` branch before submitting your pull request. If it doesn't merge properly with `main` you may be asked to rebase your changes. - ```shell - git checkout -b my_feature - # rebase if necessary - git fetch upstream main - git rebase upstream/main - ``` +```shell +git checkout -b my_feature +# rebase if necessary +git fetch upstream main +git rebase upstream/main +``` * Commits should be as small as possible, while ensuring that each commit is correct independently * Commit your changes to your feature branch and push it to your fork. - ```shell - git add . - git commit -m "Something meaningful" - git push origin my_feature - ``` +```shell +git add . +git commit -m "Something meaningful" +git push origin my_feature +``` !!! note Alternatively you can amend your commit before pushing if you forgot something by using `git commit --amend` @@ -111,5 +111,4 @@ for a review in the pull request or a comment. We use GitHub issues to track bugs and enhancement requests. Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to understand, reproduce the behavior and find related reports of that issue for the assignee. Therefore, contributors may use but aren't restricted to the issue template provided by the IronCore maintainers. - Thank you for helping improve our documentation! diff --git a/docs/iaas/usage-guides/ipam.md b/docs/iaas/usage-guides/ipam.md index 93fad52..9e830db 100644 --- a/docs/iaas/usage-guides/ipam.md +++ b/docs/iaas/usage-guides/ipam.md @@ -1,4 +1,5 @@ # IPAM Resources + This guide explains how to use IronCore's integrated IP address management (IPAM) resources to define and manage IP prefixes and allocations. ## Prefix diff --git a/docs/iaas/usage-guides/networking.md b/docs/iaas/usage-guides/networking.md index 2a29eea..b674e93 100644 --- a/docs/iaas/usage-guides/networking.md +++ b/docs/iaas/usage-guides/networking.md @@ -1,6 +1,6 @@ # Networking Resources -This guide describes the core networking resources in IronCore, such as `Networks`, `NetworkInterfaces`, `VirtualIPs`, `NAT gateways`, `LoadBalancers`, and `NetworkPolicies`. It explains how to define, configure, and manage these resources for the infrastructure. +This guide describes the core networking resources in IronCore, such as `Networks`, `NetworkInterfaces`, `VirtualIPs`, `NAT gateways`, `LoadBalancers`, and `NetworkPolicies`. ## Network @@ -26,11 +26,9 @@ spec: ### Key Fields: - `peerings` (`list`): Are the list of network peerings with this `Network` (optional). - - ### More about IronCore Network: -- **Network creation**: [ironcore-net](https://github.com/ironcore-dev/ironcore-net) is the network plugin for IronCore that realizes the `Network` resource, When an IronCore `Network` is created, a corresponding `core.apinet.ironcore.dev/Network` is created in the ironcore-net(apinet) cluster. +- **Network creation**: [ironcore-net](https://github.com/ironcore-dev/ironcore-net) is the network plugin for IronCore that realizes the `Network` resource. When an IronCore `Network` is created, a corresponding `core.apinet.ironcore.dev/Network` is created in the ironcore-net(apinet) cluster. Once created and with an allocated ID, the IronCore `Network` will be patched with the corresponding providerID of the apinet Network and set to state: `Available`. The format of a network providerID is as follows: `ironcore-net://///` @@ -61,7 +59,6 @@ status: - name: peering1 state: Ready state: Available - ``` For detailed e2e example on network peering @@ -73,7 +70,6 @@ A `NetworkInterface` resource in IronCore represents a connection point between network. It encapsulates the configuration and life cycle management of the virtual network interface, ensuring seamless connectivity for `Machines`. - ### Example NetworkInterface Resource An example of how to define a `NetworkInterface` resource in IronCore: @@ -179,7 +175,6 @@ spec: - `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. - After reconciling all `NATGateways`, the status gets updated with the corresponding values for `ips` as shown below. ```yaml