Skip to content

Commit bb87c91

Browse files
ushabelgurbalpert89
ushabelgur
authored and
balpert89
committed
Add usage doc for compute section (#1212)
* add usage doc for compute * refactoring * refactoring * incorporating review comments * incorporating review comments
1 parent f4d3b51 commit bb87c91

File tree

3 files changed

+131
-0
lines changed

3 files changed

+131
-0
lines changed

‎docs/usage/compute/machine.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,73 @@
11
# Machine
2+
3+
A `Machine` resource in `Ironcore` is used to represent a compute resource or a virtual machine.
4+
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`.
5+
6+
## Example Machine Resource
7+
8+
An example of how to define a Machine resource:
9+
10+
```yaml
11+
apiVersion: compute.ironcore.dev/v1alpha1
12+
kind: Machine
13+
metadata:
14+
name: machine-sample
15+
spec:
16+
machineClassRef:
17+
name: machineclass-sample
18+
image: my-image
19+
volumes:
20+
- name: rootdisk # first disk is the root disk
21+
volumeRef:
22+
name: my-volume
23+
networkInterfaces:
24+
- name: primary
25+
networkInterfaceRef:
26+
name: networkinterface-sample
27+
ignitionRef:
28+
name: my-ignition-secret
29+
```
30+
(`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e">E2E Examples</a> for more detailed examples.)
31+
32+
**Key Fields**:
33+
34+
- machineClassRef (`string`): machineClassRef is a reference to the machine class/flavor of the machine.
35+
- 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.
36+
- image (`string`): image is the optional URL providing the operating system image of the machine.
37+
- volumes (`list`): volumes are list volumes(storage) attached to this machine.
38+
- networkInterfaces (`list`): networkInterfaces define a list of network interfaces present on the machine
39+
- 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)
40+
41+
42+
## Reconciliation Process
43+
44+
1. **Machine Scheduling**:
45+
The `MachineScheduler` controller continuously watches for `Machines` without an assigned `MachinePool` and tries to schedule it on available and matching MachinePool.
46+
- **Monitor Unassigned Machines**: The scheduler continuously watches for machines without an assigned `machinePoolRef`.
47+
- **Retrieve Available Machine Pools**: The scheduler fetches the list of available machine pools from the cache.
48+
- **Make Scheduling Decisions**: The scheduler selects the most suitable machine pool based on resource availability and other policies.
49+
- **Update Cache**: The scheduler updates the cache with recalculated allocatable `machineClass` quantities.
50+
- **Assign MachinePoolRef**: The scheduler assigns the selected `machinePoolRef` to the machine object.
51+
52+
2. **IRI Machine Creation and Brokering**:
53+
- The Machine is allocated to a particular pool via the scheduler.
54+
- 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.
55+
- 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.
56+
- Once the response is received from IRI call Machine status is updated with the status received.
57+
58+
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`.
59+
60+
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`.
61+
62+
6. **Ephemeral resource handling**:
63+
- 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>)
64+
- If `NetworkIntreface` or `Volume` is defined as ephemeral `MachineEphemeralControllers` takes care of creating and destroying respective objects on creation/deletion of the machine.
65+
66+
## Lifecycle and States
67+
68+
A Machine can be in the following states:
69+
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.
70+
2. **Running**: A Machine in Running state when the machine is running on a MachinePool.
71+
2. **Shutdown**: A Machine is in a Shutdown state.
72+
3. **Terminating**: A Machine is Terminating.
73+
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‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,28 @@
11
# MachineClass
2+
3+
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`.
4+
5+
## Example Machine Resource
6+
7+
An example of how to define a MachineClass resource:
8+
9+
```yaml
10+
apiVersion: compute.ironcore.dev/v1alpha1
11+
kind: MachineClass
12+
metadata:
13+
name: machineclass-sample
14+
capabilities:
15+
cpu: 4
16+
memory: 16Gi
17+
```
18+
19+
**Key Fields**:
20+
21+
- capabilities (`ResourceList`): capabilities are used to define a list of resources a Machine can have along with its capacity.
22+
23+
24+
## Reconciliation Process
25+
26+
- **MachineClass Creation**: The `MachineClassController` uses the `capabilities` field in the MachineClass resource to create a flavor of MachineClass resource.
27+
- **MachineClass Deletion**: Before deleting any MachineClass it's been ensured that it is not in use by any `Machine` and then only deleted.
28+

‎docs/usage/compute/machinepool.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,33 @@
11
# MachinePool
2+
3+
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`)
4+
5+
## Example MachinePool Resource
6+
7+
An example of how to define a MachinePool resource:
8+
9+
```yaml
10+
apiVersion: compute.ironcore.dev/v1alpha1
11+
kind: MachinePool
12+
metadata:
13+
name: machinepool-sample
14+
labels:
15+
ironcore.dev/az: az1
16+
spec:
17+
providerID: ironcore://shared
18+
```
19+
20+
**Key Fields**:
21+
22+
- `ProviderID`(`string`): The `providerId` helps the controller identify and communicate with the correct compute system within the specific backend compute provider.
23+
For example `ironcore://shared`
24+
25+
## Reconciliation Process
26+
27+
- **Machine Type Discovery**: It constantly checks what kinds of `MachineClasses` are available in the `Ironcore` Infrastructure
28+
- **Compatibility Check**: Evaluating whether the `MachinePool` can manage available machine classes based on its capabilities.
29+
- **Status Update**: Updating the MachinePool's status to indicate the supported `MachineClasses` with available capacity and allocatable.
30+
- **Event Handling**: Watches for changes in MachineClass resources and ensures the associated MachinePool is reconciled when relevant changes occur.
31+
32+
33+

0 commit comments

Comments
 (0)