From 80167dfc1a7037b0c6abc2fbf97e1d3ea4f9cb10 Mon Sep 17 00:00:00 2001 From: David Cassany Viladomat Date: Mon, 21 Oct 2024 15:53:39 +0200 Subject: [PATCH] Add hooks docs for 1.6 and improve Next version (#421) * Add hooks docs for 1.6 and improve Next version This commit adds hooks documentation for version v1.6 and it also improves the note explaining hooks usage in MachineRegistration.config.cloud-config section Signed-off-by: David Cassany * Add after-install-chroot in MachineRegistration example Signed-off-by: David Cassany --------- Signed-off-by: David Cassany --- docs/cloud-config-reference.md | 7 +++ .../version-1.6/cloud-config-reference.md | 61 +++++++++++++++++-- 2 files changed, 64 insertions(+), 4 deletions(-) diff --git a/docs/cloud-config-reference.md b/docs/cloud-config-reference.md index d69e5bcca..d81e34421 100644 --- a/docs/cloud-config-reference.md +++ b/docs/cloud-config-reference.md @@ -97,6 +97,9 @@ the preferred option is to build a [derivative image](custom-images.md) and not Note installation hooks are not applied as part of the [MachineRegistartion.config.cloud-config](machineregistration-reference.md#configcloud-config). In order to provide installation hooks they can be included as part of the [SeedImage.cloud-config](seedimage-reference.md#seedimagespec-reference), as they need to be present in the installation media. +The only exception is `after-install-chroot` which can be provided as part of a +[MachineRegistartion.config.cloud-config](machineregistration-reference.md#configcloud-config) because the hook runs +in the deployed image chroot and by that time cloud-config is already installed into the system. ::: ## Configuration syntax @@ -156,6 +159,10 @@ spec: cloud-config: name: "A registration driven config" stages: + after-install-chroot: + - name: "Set serial console" + commands: + - grub2-editenv /oem/grubenv set extra_cmdline="console=ttyS0" initramfs: - name: "Setup users" ensure_entities: diff --git a/versioned_docs/version-1.6/cloud-config-reference.md b/versioned_docs/version-1.6/cloud-config-reference.md index b91b1b6fd..6f8357da3 100644 --- a/versioned_docs/version-1.6/cloud-config-reference.md +++ b/versioned_docs/version-1.6/cloud-config-reference.md @@ -19,9 +19,9 @@ any time as they are simply grouping a set of actions under an arbitrary name. Elemental Toolkit integrates five predefined stages into the OS boot process. -1. **`rootfs`**: this stage runs on early boot inside the init ram disk, just after mounting the root device (typically at `/sysroot`). - This stage can be used to define first-boot steps like expanding or creating persistent partitions. Ephemeral and - persistent paths are typically defined at this stage. Executed as part of the `initrd-root-fs.target`. +1. **`rootfs`**: this stage runs on early boot inside the init ram disk, just *after* mounting the root device (typically at `/sysroot`). + This stage can be used to define first-boot steps like creating new partitions. Ephemeral and persistent paths are typically defined + at this stage. Executed as part of the `initrd-root-fs.target`. 2. **`initramfs`**: this stage runs inside the init ram disk too, but on a later stage just before switching root. This stage runs in a chrooted environment to the actual root device. This stage is handy to set some system parameters that might be relevant to systemd @@ -40,13 +40,62 @@ 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`. +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. ::: + +## Elemental client cloud-config hooks + +In addition to the defined cloud-config stages at boot described in the previous section the Elemental client also +honors some specific stages, referenced as hooks, to customize the behavior of these subcommands: `install`, +`upgrade`, `reset` and `build-disk`. Each of these subcommands has it's own set of four different cloud-config stages executed at +analog phases of the specific subcommand execution. + +Hooks are essetially a way to provide permanent changes to system that can't be easily expressed as part of an OCI container or that +are not easily achievable with the `elemental` client configuration options. A good example could be handling the firmware in EFI +partition for Raspberry Pi devices. + +:::warning +Note most hooks are executed in the host environment with privileges, so they are potentially destructive operations. In most +cases regular cloud-config operations at boot time are sufficient to setup the system. Also to include additional software in an image +the preferred option is to build a [derivative image](custom-images.md) and not abuse of hooks to install additional software. +::: + + +### Hook stages + +* Before stages: `before-install`, `before-upgrade`, `before-reset`, `before-disk` + These stages are executed once the working directories and environment are prepared but before starting the actual action. In + `install`, `upgrade` and `reset` steps this happens once all the associated partitions are created and mounted, but before stating + the deployment of any image. + +* After chrooted stages: `after-install-chroot`, `after-upgrade-chroot`, `after-reset-chroot`, `after-disk-chroot` + These stages are executed after deploying the target system into the working area into a chroot environment rooted to the + actual deployed image. Since this happens in a chroot env the elemental client analyses the hooks present in the deployed image, not in the host. + Only `/oem` is shared with the host if available. + +* After stages: `after-install`, `after-upgrade`, `after-reset`, `after-disk` + These stages are executed after deploying the target system into the working area from the host environment. At this stages all + partitions are still mounted and available in RW mode. + +* Post stages: `post-install`, `post-upgrade`, `post-reset`, `post-disk` + These stages are executed at end before exiting the command and running a cleanup process. At this stage the image is already deployed + and locked in a read-only subvolume or filesystem. Partitions are still mounted at this stage. + +:::note +Note installation hooks are not applied as part of the [MachineRegistartion.config.cloud-config](machineregistration-reference.md#configcloud-config). +In order to provide installation hooks they can be included as part of the [SeedImage.cloud-config](seedimage-reference.md#seedimagespec-reference), +as they need to be present in the installation media. +The only exception is `after-install-chroot` which can be provided as part of a +[MachineRegistartion.config.cloud-config](machineregistration-reference.md#configcloud-config) because the hook runs +in the deployed image chroot and by that time cloud-config is already installed into the system. +::: + ## 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 @@ -104,6 +153,10 @@ spec: cloud-config: name: "A registration driven config" stages: + after-install-chroot: + - name: "Set serial console" + commands: + - grub2-editenv /oem/grubenv set extra_cmdline="console=ttyS0" initramfs: - name: "Setup users" ensure_entities: