Add usage doc for compute section (#1212)

* add usage doc for compute

* refactoring

* refactoring

* incorporating review comments

* incorporating review comments

docs/usage/compute/machine.md

@@ -1 +1,73 @@
 # Machine
+
+A `Machine` resource in `Ironcore` is used to represent a compute resource or a virtual machine. 
+It serves as a means to configure network, storage, type of machine and other information needed to create a VM. The `MachineController` reconciler leverages this information to determine where the machine needs to be created and the type of machine that needs to be created along with the required `Network` and `Storage` configuration which will be further passed to respective `NetworkController` and `StorageController`.
+
+## Example Machine Resource
+
+An example of how to define a Machine resource:
+
+```yaml
+apiVersion: compute.ironcore.dev/v1alpha1
+kind: Machine
+metadata:
+  name: machine-sample
+spec:
+  machineClassRef:
+    name: machineclass-sample
+  image: my-image
+  volumes:
+    - name: rootdisk # first disk is the root disk
+      volumeRef:
+        name: my-volume
+  networkInterfaces:
+    - name: primary
+      networkInterfaceRef:
+        name: networkinterface-sample
+  ignitionRef:
+    name: my-ignition-secret
+```
+(`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e">E2E Examples</a> for more detailed examples.)
+
+**Key Fields**:
+
+- machineClassRef (`string`): machineClassRef is a reference to the machine class/flavor of the machine.
+- machinePoolRef (`string`): machinePoolRef defines the machine pool to run the machine in. If empty, a scheduler will figure out an appropriate pool to run the machine in.
+- image (`string`): image is the optional URL providing the operating system image of the machine.
+- volumes (`list`): volumes are list volumes(storage) attached to this machine.
+- networkInterfaces (`list`): networkInterfaces define a list of network interfaces present on the machine
+- ignitionRef (`string`): ignitionRef is a reference to a `secret` containing the ignition YAML for the machine to boot up. If a key is empty, `DefaultIgnitionKey` will be used as a fallback. (`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e/bases/ignition">Sample Ignition</a> for creating ignition secret)
+
+
+## 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.
+
+2. **IRI Machine Creation and Brokering**: 
+  - The Machine is allocated to a particular pool via the scheduler. 
+  - The `machinepoollet` responsible for this pool picks up the `Machine` resource and extracts the `ignitionData`, `networkInterfaces` and `volumes` information from the `spec` and prepares the IRI machine object. 
+  - Once the IRIMachine object is prepared the machine create/update request is sent to a broker via the IRI interface(via GRPC call) either against a broker (to copy the resource into another cluster) OR a provider implementation e.g. libvirt-provider which creates a corresponding machine against libvirt/QEMU. 
+  - Once the response is received from IRI call Machine status is updated with the status received.
+
+4. **Network Interface handling**: `MachineControllerNetworkinterface` takes care of attaching/detaching Network interfaces 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(Storage) defined for 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 `NetworkIntreface` or `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.

docs/usage/compute/machineclass.md

@@ -1 +1,28 @@
 # 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(For eg, CPU, memory) associated with a particular class. The `MachineClassController` reconciler leverages this information to create `MachineClass`.
+
+## Example Machine Resource
+
+An example of how to define a MachineClass resource:
+
+```yaml
+apiVersion: compute.ironcore.dev/v1alpha1
+kind: MachineClass
+metadata:
+  name: machineclass-sample
+capabilities:
+  cpu: 4
+  memory: 16Gi
+```
+
+**Key Fields**:
+
+- capabilities (`ResourceList`): capabilities are used to define a list of resources a Machine can have along with its capacity.
+
+
+## Reconciliation Process
+
+- **MachineClass Creation**: The `MachineClassController` uses the `capabilities` field in the MachineClass resource to create a flavor of MachineClass resource.
+- **MachineClass Deletion**: Before deleting any MachineClass it's been ensured that it is not in use by any `Machine` and then only deleted.
+

docs/usage/compute/machinepool.md

@@ -1 +1,33 @@
 # 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`)
+
+## Example MachinePool Resource
+
+An example of how to define a MachinePool resource:
+
+```yaml
+apiVersion: compute.ironcore.dev/v1alpha1
+kind: MachinePool
+metadata:
+  name: machinepool-sample
+  labels:
+    ironcore.dev/az: az1
+spec:
+  providerID: ironcore://shared
+```
+
+**Key Fields**:
+
+- `ProviderID`(`string`):  The `providerId` helps the controller identify and communicate with the correct compute system within the specific backend compute provider.
+For example `ironcore://shared`
+
+## Reconciliation Process
+
+- **Machine Type Discovery**: It constantly checks what kinds of `MachineClasses` are available in the `Ironcore` Infrastructure
+- **Compatibility Check**: Evaluating whether the `MachinePool` can manage available machine classes based on its capabilities. 
+- **Status Update**: Updating the MachinePool's status to indicate the supported `MachineClasses` with available capacity and allocatable.
+- **Event Handling**: Watches for changes in MachineClass resources and ensures the associated MachinePool is reconciled when relevant changes occur.
+
+
+