diff --git a/docs/content/en/docs/Creating derivatives/build_disk.md b/docs/content/en/docs/Creating derivatives/build_disk.md index 8d892007880..0ae47af0ef7 100644 --- a/docs/content/en/docs/Creating derivatives/build_disk.md +++ b/docs/content/en/docs/Creating derivatives/build_disk.md @@ -2,64 +2,67 @@ title: "Build disk images with Elemental" linkTitle: "Build disk images with Elemental" weight: 4 -date: 2023-08-31 +date: 2024-08-20 description: > - This section documents the procedure to build disk images using elemental + This section documents the procedure to build disk images using Elemental --- -Requirements: +In order to build a RAW disk image we rely on `elemental build-disk` command. It accepts a YAML file denoting the sources to bundle in the RAW image. In addition it can also overlay custom files or use container images from a registry as packages. -* `qemu-img` utility -* `elemental` binary -* elemental runtime dependencies - -The suggested approach is based on using the Elemental installer (`elemental install` command) to run the installation -from a Linux to a loop device. The loop device can be a raw image created with `qemu-img create` that can easily be -converted to other formats after the installation by using `qemu-img convert`. - -## Prepare the loop device - -Preparing the a loop device for the installation is simple and straight forward. +To build a RAW image, just run: ```bash -# Create a raw image of 32G -> qemu-img create -f raw disk.img 32G - -# Set the disk image as a loop device -> sudo losetup -f --show disk.img - +docker run --rm -ti -v $(pwd):/build ghcr.io/rancher/elemental-toolkit/elemental-cli:latest --debug build-disk --expandable --unprivileged --squash-no-compression -o /build $SOURCE ``` -## Run elemental installation - -Execute the elemental installation as described in [installing](../../getting-started/install): - -```bash -> sudo elemental install --firmware efi --system.uri oci: +Argument `$SOURCE` might be the reference to the directory, file, container image or channel we are building the ISO for, it should be provided as uri in following format :, where: + * - might be ["dir", "file", "oci", "docker"], as default is taken "docker" + * - is path to file or directory, channel or image name with tag version (if tag was not provided then "latest" is used) + +`elemental build-disk` command also supports reading a configuration `manifest.yaml` file. It is loaded form the directory specified by `--config-dir` elemental's flag. + +An example of a yaml file using the bootloader from the contained image: + +```yaml +# Representing the RAW disk final image name without including the '.raw' +name: "Elemental-0" +# Indicates if the output image name has to contain the date +date: true +# Folder destination of the built artifacts. It attempts to create if it doesn't exist. +output: /output/dir +# Snapshotter configuration +snapshotter: + type: btrfs + maxSnaps: 2 ``` -Where `` is the Elemental derivative container image we want to use for the disk creation and `` is the -loop device previously created with `losetup` (e.g. `/dev/loop0`). - - -## Convert the RAW image to desired format - -Once the installation is done just unsetting the loop device and converting the image to the desired format is missing: - -```bash -# Unset the loop device -> sudo losetup -d - -# Convert the RAW image to qcow2 -> qemu-img convert -f raw -O qcow2 disk.img disk.qcow2 +### Usage + +```text +Usage: + elemental build-disk image [flags] + +Flags: + -c, --cloud-init strings Cloud-init config files to include in disk + --cloud-init-paths strings Cloud-init config files to run during build + --cosign Enable cosign verification (requires images with signatures) + --cosign-key string Sets the URL of the public key to be used by cosign validation + --date Adds a date suffix into the generated disk file + --deploy-command strings Deployment command for expandable images (default [elemental,--debug,reset,--reboot]) + --expandable Creates an expandable image including only the recovery image + -h, --help help for build-disk + --local Use an image from local cache + -n, --name string Basename of the generated disk file + -o, --output string Output directory (defaults to current directory) + --platform string Platform to build the image for (default "linux/amd64") + -x, --squash-compression stringArray cmd options for compression to pass to mksquashfs. Full cmd including --comp as the whole values will be passed to mksquashfs. For a full list of options please check mksquashfs manual. (default value: '-comp xz -Xbcj ARCH') + --squash-no-compression Disable squashfs compression. Overrides any values on squash-compression + -t, --type string Type of image to create (default "raw") + --unprivileged Makes a build runnable within a non-privileged container, avoids mounting filesystems (experimental) + +Global Flags: + --config-dir string Set config dir + --debug Enable debug output + --logfile string Set logfile + --quiet Do not output to stdout ``` - -QEMU supports a wide range of formats including common ones such as `vdi`, `vmdk` or `vhdx`. - -The result can be easily tested on QEMU with: - -```bash -> qemu -m 4096 -hda disk.qcow2 -bios /usr/share/qemu/ovmf-x86_64.bin -``` - -Note the firmware image path varies depending on the host distro, the path provided in this example is based on openSUSE Leap.