diff --git a/docs/usage/compute/machine.md b/docs/usage/compute/machine.md index 129347925..e502cb46f 100644 --- a/docs/usage/compute/machine.md +++ b/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 E2E Examples 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 Sample Ignition 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 Machine with ephemeral resources) + - 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. \ No newline at end of file diff --git a/docs/usage/compute/machineclass.md b/docs/usage/compute/machineclass.md index 47ecd03bf..a7c88c233 100644 --- a/docs/usage/compute/machineclass.md +++ b/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. + diff --git a/docs/usage/compute/machinepool.md b/docs/usage/compute/machinepool.md index f46437595..f832408ec 100644 --- a/docs/usage/compute/machinepool.md +++ b/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. + + +