Skip to content

Commit d6af8f3

Browse files
ushabelgurushabelgur
committed
add usage doc for compute
1 parent 4c492f2 commit d6af8f3

File tree

3 files changed

+130
-0
lines changed

3 files changed

+130
-0
lines changed

‎docs/usage/compute/machine.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,72 @@
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 type of machine needs to be created along with 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 an 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+
# machinePoolRef:
19+
# name: default
20+
image: my-image
21+
volumes:
22+
- name: rootdisk # first disk is root disk
23+
# priority: 0 # optional
24+
volumeRef:
25+
name: my-volume
26+
networkInterfaces:
27+
- name: primary
28+
networkInterfaceRef:
29+
name: networkinterface-sample
30+
ignitionRef:
31+
name: my-ignition-secret
32+
```
33+
(`Note`: Refer to <a href="https://github.com/ironcore-dev/ironcore/tree/main/config/samples/e2e">E2E Examples</a> for more detailed examples.)
34+
35+
**Key Fields**:
36+
37+
- machineClassRef (`string`): MachineClassRef is a reference to the machine class/flavor of the machine.
38+
- machinePoolRef (`string`): MachinePoolRef defines machine pool to run the machine in. If empty, a scheduler will figure out an appropriate pool to run the machine in.
39+
- image (`string`): Image is the optional URL providing the operating system image of the machine.
40+
- volumes (`list`): Volumes are list volumes(Storage) attached to this machine.
41+
- networkInterfaces (`list`): NetworkInterfaces define a list of network interfaces present on the machine
42+
- ignitionRef (`string`): IgnitionRef is a reference to a secret containing the ignition YAML for the machine to boot up. If key is empty, DefaultIgnitionKey will be used as fallback.
43+
44+
45+
## Reconciliation Process
46+
47+
1. **Machine Scheculing**:
48+
The MachineScheduler controller continuously watches for machines without an assigned MachinePool and tries to schedule it on available and matching MachinePool.
49+
- **Monitor Unassigned Machines**: The scheduler continuously watches for machines without an assigned `machinePoolRef`.
50+
- **Retrieve Available Machine Pools**: The scheduler fetches the list of available machine pools from the cache.
51+
- **Make Scheduling Decisions**: The scheduler selects the most suitable machine pool based on resource availability and other policies.
52+
- **Update Cache**: The scheduler updates the cache with recalculated allocatable `machineClass` quantities.
53+
- **Assign MachinePoolRef**: The scheduler assigns the selected `machinePoolRef` to the machine object.
54+
55+
2. **IRI Machine creation**: Once the Machine is allocated to particular pool, the `MachineController` processes the `Machine` resource and it extracts the `IgnitionData`, `NetworkInterface` and `Volume` information from the `spec` and prepares IRI machine resource.
56+
57+
3. **Machine Brokering**: Once IRIMachine object is prepared create/update machine request is sent to broker via IRI interface(via GRPC call). Actual VM is created when request reaches compute provider. Once the response is recieved from IRI call Machine status is updated with status recieved.
58+
59+
4. **Network Intreface handling**: MachineControllerNetworkinterface takes care of attach/dettach of Network interfaces defined for machine. Once the attachment is successful status is updated from `Pending` to `Attached`.
60+
61+
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`.
62+
63+
6. **Ephemeral resource handling**: If `NetworkIntreface` or `Volume` is defined as ephemeral(i.e. coupled to the lifetime of the machine object) in the machine spec, MachineEphemeralControllers takes care of creating and destroying respective objects on creation/deletion of machine.
64+
65+
## Lifecycle and States
66+
67+
A Machine can be in a following states:
68+
1. **Pending**: A Machine is in 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.
69+
2. **Running**: A Machine in Running state when the machine is running on a MachinePool.
70+
2. **Shutdown**: A Machine is in Shutdown state.
71+
3. **Terminating**: A Machine is in Terminating state.
72+
2. **Terminated**: A Machine is in 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 a `IronCore` resource used to represent a class/flavor of a Machine. It serves as a means to define an amount of resources a `Machine` object can have as capabilities(For eg, CPU, memory) if associated with particular class. The `MachineClassController` reconciler leverages this information create `MachineClass`.
4+
5+
## Example Machine Resource
6+
7+
An example of how to define an 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 is 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 its 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`.
4+
5+
## Example MachinePool Resource
6+
7+
An example of how to define an 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 machine (MachineClasses) are available in the `Ironcore` Infrastructure
28+
- **Compatibility Check**: Evaluating whether the MachinePool can manage available machine class 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)