From 916121bb0903404a6e4e876fddb715ee631c4ac7 Mon Sep 17 00:00:00 2001 From: Andrea Mazzotti Date: Wed, 19 Jun 2024 15:13:03 +0200 Subject: [PATCH] Document yip syntax support on elemental-operator resources (#346) Signed-off-by: Andrea Mazzotti --- docs/cloud-config-reference.md | 64 +++++++++++++++++++++++++-- docs/machineregistration-reference.md | 3 +- docs/managedosimage-reference.md | 6 +-- docs/seedimage-reference.md | 2 +- 4 files changed, 66 insertions(+), 9 deletions(-) diff --git a/docs/cloud-config-reference.md b/docs/cloud-config-reference.md index d13050f0c..99b2c84a2 100644 --- a/docs/cloud-config-reference.md +++ b/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. + +
+ MachineRegistration example + +```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 +``` + +
+ ## 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.
diff --git a/docs/machineregistration-reference.md b/docs/machineregistration-reference.md index e52e35c35..445df7ae3 100644 --- a/docs/machineregistration-reference.md +++ b/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 . diff --git a/docs/managedosimage-reference.md b/docs/managedosimage-reference.md index 8f0512f08..c1b2bc3bb 100644 --- a/docs/managedosimage-reference.md +++ b/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 diff --git a/docs/seedimage-reference.md b/docs/seedimage-reference.md index 5ee56136a..037043359 100644 --- a/docs/seedimage-reference.md +++ b/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.