Improve usage doc, fix typos and follow style guide

Author: Rohit-0505

docs/baremetal/index.md

@@ -14,7 +14,7 @@ in a Kubernetes-native way. It leverages the power of Kubernetes Custom Resource
 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
 

docs/iaas/architecture/networking.md

@@ -50,10 +50,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`

docs/iaas/architecture/runtime-interface.md

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

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
 

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 <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/machine-with-ephemeral-resources">Machine with ephemeral resources</a>)
-- 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,18 @@ 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 +94,5 @@ spec:
 
 **Key Fields**:
 
-- `ProviderID`(`string`):  The `providerId` helps the controller identify and communicate with the correct compute 
+- `providerID` (`string`):  The `providerId` helps the controller identify and communicate with the correct compute 
   system within the specific backend compute provider.

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.

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.
+Detailed API references for the IronCore IaaS types can be found in the [API References](../api-references/) section.

docs/iaas/usage-guides/ipam.md

@@ -1,12 +1,13 @@
 # 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
 
 A `Prefix` resource provides a fully integrated IP address management (IPAM) solution inside IronCore. It serves as a 
 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: