Skip to main content

Build Edge Installer ISO with Trusted Boot

This document guides you through the process of producing Edge Installer ISOs that are secured by Trusted Boot.

Limitation​

  • Trusted Boot is only supported for clusters with a connection to a Palette instance. Therefore, you cannot set managementMode to local in the user-data file.

Prerequisites​

  • A physical or virtual Linux machine with AMD64 (also known as x86_64) processor architecture to build the Edge artifacts. You can issue the following command in the terminal to check your processor architecture.

    uname -m

  • Minimum hardware configuration of the Linux machine:

    • 4 CPU
    • 32 GB memory
    • 100 GB storage

  • You have generated secure boot keys in the secure-boot/enrollment folder.

  • Both the db.key file and the tpm2-pcr-private.pem file are located in the CanvOS/secure-boot/private-keys directory. For more information, refer to Generate Trusted Boot Keys.

  • Familiarity with the EdgeForge Workflow.

  • Git. You can ensure git installation by issuing the git --version command.

  • Palette registration token for pairing Edge hosts with Palette. You will need tenant admin access to Palette to generate a new registration token. For detailed instructions, refer to the Create Registration Token guide.

Instructions​

  1. Check out the CanvOS GitHub repository containing the starter code.

    git clone https://github.com/spectrocloud/CanvOS.git

  2. Change to the CanvOS directory.

    cd CanvOS

  3. View the available git tag.

    git tag

  4. (Optional) If you are using a self-hosted instance of Palette, you need to build the ISO using the corresponding CanvOS version. Use the following command to identify the agent version for your Palette instance. Replace <palette-endpoint> with your Palette endpoint and <api-key> with your Palette API key.

    curl --location --request GET 'https://<palette-endpoint>/v1/services/stylus/version' --header 'Content-Type: application/json' --header 'Apikey: <api-key>'  | jq --raw-output '.spec.latestVersion.content | match("version: ([^\n]+)").captures[0].string'

    The output is the version number you must use to build the ISO. For example, if the output is 4.5.15, you must check out the v4.5.15 tag in the CanvOS repository to build the ISO.

    Example output
    4.5.15

  1. If you are using a self-hosted instance of Palette and have determined a specific CanvOS version, check out the corresponding tag.

    Otherwise, check out the newest available tag. This guide uses v4.4.0 tag as an example.

    git checkout v4.4.0

  2. Create a file named .arg. You can use the .arg.template file in the repository as a starting point. Refer to Edge Artifact Build Configurations for available configuration parameters.

    To build an ISO image that supports Trusted Boot, include the following parameters in the .arg file.

    OS_DISTRIBUTION=ubuntu
    OS_VERSION=23.10
    IS_UKI=true
    AUTO_ENROLL_SECUREBOOT_KEYS=true
    info

    It is not necessary to include AUTO_ENROLL_SECUREBOOT_KEYS=true. If you do not include it, you will need to manually confirm the enrollment of the keys during install time. For more information, refer to Installation with Trusted Boot.

  3. Create a file named user-data. You can use the user-data.template file in the repository as a starting point. This is the file with which you can configure the Edge installer. Refer to Edge Installer Configuration for available configuration parameters.

    warning

    Ensure you have generated the Trusted Boot keys in the secure-boot/enrollment folder before proceeding to the next step. If you build an ISO without the keys in the folder, the key enrollment will not happen. For more information, refer to Generate Trusted Boot Keys.

  4. Customize the Dockerfile. You can install tools and dependencies and configure the image to meet your needs. Add your customizations below the line tagged with the Add any other image customizations here comment in the Dockerfile. Do not edit or add any lines before this tagged comment. For example, you can add the following line to the Dockerfile to install WireGuard.

    ...
    ###########################Add any other image customizations here #######################

    RUN sudo zypper refresh && sudo zypper install --non-interactive wireguard-tools
    warning

    Adding software dependencies in the Dockerfile will cause the size of the Extensible Firmware Interface (EFI) file to grow. Most hardware has a limit on the size of the EFI that it can boot. Make sure you do not include too many dependencies that can cause the EFI file to grow larger than the boot limit. For more information, refer to Check EFI Boot Limit.

    Instead of adding software packages through the Dockerfile to the OS layer, you can add compiled static binaries to the persistent partition instead, which does not increase the size of the EFI file. Refer to Add Static Binaries to Persistent Partition for more information.

  5. Issue the following command to build the ISO image.

    ./earthly.sh +iso

Validate​

List the Edge installer ISO image and checksum by issuing the following command from the CanvOS/ directory.

ls build/
kairos_uki_v3.0.4-2-g3fba4f4.tar  kairos_v3.0.4-2-g3fba4f4.iso

You can validate the ISO image by creating a bootable USB flash drive using any third-party software and attempting to flash a bare host machine. Most software that creates a bootable USB drive will validate the ISO image. Here, the flash process means installing the necessary tools and configurations on a host machine.