Document yip syntax support on elemental-operator resources (#346)

Signed-off-by: Andrea Mazzotti <[email protected]>

docs/cloud-config-reference.md

@@ -40,12 +40,13 @@ Elemental Toolkit integrates five predefined stages into the OS boot process.
 
 By default, `elemental` reads the yaml configuration files from the following paths in order: `/system/oem`, `/oem` and `/usr/local/cloud-config`.
 
+In Elemental Operator, all kubernetes resources including a `cloud-config` field can be expressed in either [yip](#configuration-syntax) or [cloud-init compatible](#compatibility-with-cloud-init-format) syntax. This includes resources such as `MachineRegistration`, `SeedImage`, and `ManagedOSImage`.
+
 :::note
 In contrast to similar projects such as _Cloud Init_, Yip does not keep records or caches of executed stages and steps,
 all stages and its associated configuration is executed at every boot.
 :::
 
-
 ## Configuration syntax
 
 Yip has its own syntax, it essentially requires to define _stages_ and a list of steps for each stage. Steps are executed in
@@ -55,6 +56,14 @@ Consider the following example:
 
 ```yaml
 stages:
+  initramfs:
+  - name: "Setup users"
+    ensure_entities:
+    - path: /etc/shadow
+      entity: |
+          kind: "shadow"
+          username: "root"
+          password: "root"
   boot:
   - files:
     - path: /tmp/script.sh
@@ -68,7 +77,9 @@ stages:
     - /tmp/script.sh
 ```
 
-In the above exaple there is one `boot` stage including two steps, one to create an executable script file and a second one
+In the above exaple there are two stages: `initramfs` and `boot`.  
+The `initramfs` stage initializes a sample user.  
+The `boot` stage includes two steps, one to create an executable script file and a second one
 that actually runs the script.
 
 Yip also supports `*.before` and `*.after` suffix modifiers to any given stage. For instance, running the `network` stage
@@ -77,6 +88,53 @@ results into running first `network.before` stages found in config files and the
 See the full reference of applicable keys in steps documented in
 [yip project](https://github.com/rancher/yip?tab=readme-ov-file#configuration-reference) itself.
 
+Below is an example of the above configuration embedded in a MachineRegistration resource.  
+
+<details>
+  <summary>MachineRegistration example</summary>
+
+```yaml showLineNumbers
+apiVersion: elemental.cattle.io/v1beta1
+kind: MachineRegistration
+metadata:
+  name: my-nodes
+  namespace: fleet-default
+spec:
+  config:
+    cloud-config:
+      name: "A registration driven config"
+      stages:
+        initramfs:
+        - name: "Setup users"
+          ensure_entities:
+          - path: /etc/shadow
+            entity: |
+                kind: "shadow"
+                username: "root"
+                password: "root"
+        boot:
+        - files:
+          - path: /tmp/script.sh
+            content: |
+              #!/bin/sh
+              echo "test"
+            permissions: 0777
+            owner: 1000
+            group: 100
+        - commands:
+          - /tmp/script.sh
+    elemental:
+      install:
+        reboot: true
+        device: /dev/sda
+        debug: true
+  machineName: my-machine
+  machineInventoryLabels:
+    element: fire
+```
+
+</details>
+
 ## Compatibility with Cloud Init format
 
 A subset of the official [cloud-config spec](http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data) is implemented by yip.
@@ -114,8 +172,6 @@ write_files:
   owner: "bar"
 ```
 
-In Elemental all kubernetes resources including a cloud-config field assume cloud-init syntax. This includes resources such as `MachineRegistration` or `SeedImage`.
-
 Below is an example of the above configuration embedded in a MachineRegistration resource.
 
 <details>

docs/machineregistration-reference.md

@@ -46,7 +46,8 @@ spec:
 
 #### config.cloud-config
 
-Contains the cloud-configuration to be injected in the node. See the [Cloud Config Reference](cloud-config-reference.md) for full information.
+Contains the cloud-configuration to be injected in the node.  
+Both yip and cloud-init syntax are supported. See the [Cloud Config Reference](cloud-config-reference.md) for full information.
 
 #### config.elemental.registration
 Contains the configuration used for the connection and the initial registration to the <Vars name="elemental_operator_name" />.

docs/managedosimage-reference.md

@@ -23,7 +23,7 @@ There are several keys that can be configured under a `ManagedOSImage` resource
 |------------------------|--------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------|
 | osImage                | string | empty         | The fully qualified image to upgrade nodes to. This value has priority over `managedOSVersionName` if both are configured.                 |
 | managedOSVersionName   | string | empty         | The name of a `ManagedOSVersion` to upgrade nodes to.                                                                                      |
-| cloudConfig            | object | null          | A cloud-init config to apply to the nodes during upgrades. See [reference](#cloudconfig).                                                  |
+| cloudConfig            | object | null          | A cloud-init or yip config to apply to the nodes during upgrades. See [reference](#cloudconfig).                                                  |
 | nodeSelector           | object | null          | This selector can be used to target specific nodes within the `clusterTargets`. See [reference](#nodeselector).                            |
 | concurrency            | int    | 1             | How many nodes within the same cluster should be upgraded at the same time.                                                                |
 | cordon                 | bool   | true          | Set this to true if the nodes should be cordoned before applying the upgrade. Ineffective when `drain` is also configured.                 |
@@ -35,8 +35,8 @@ There are several keys that can be configured under a `ManagedOSImage` resource
 
 #### cloudConfig
 
-This describes a cloud-init config that will be copied to each upgraded node to the `/oem/90_operator.yaml` path.  
-This cloud-init config will be applied by the system after reboot.  
+This describes a cloud-init or yip config that will be copied to each upgraded node to the `/oem/90_operator.yaml` path.  
+This config will be applied by the system after reboot.  
 For more information and examples, see the `MachineRegistration` `spec.config.cloud-config` [reference](./cloud-config-reference.md).  
 
 #### nodeSelector

docs/seedimage-reference.md

@@ -11,7 +11,7 @@ title: ''
 
 A `SeedImage` resource allows to build an installation media that can be used to install Elemental onto a node.
 It requires a `baseImage`, i.e., a URL to an Elemental installation ISO or node container image, and a `registrationRef` reference to a `MachineRegistration` resource, from which the registration part of the Elemental configuration is extracted and injected in the media to produce the final *seed image*.
-It is also possible to inject customizations in the `cloud-config` field.
+It is also possible to inject customizations in the `cloud-config` field. Both yip and cloud-init syntax are supported. See the [Cloud Config Reference](cloud-config-reference.md) for full information.
 
 Once the seed image is ready, the download URL is shared in the `.status.downloadURL` field.
 It stays available for download for `cleanupAfterMinutes` minutes (default is `60`, 1 hour), after which it is deleted.