Skip to content

Latest commit

 

History

History
157 lines (109 loc) · 6.19 KB

build-trusted-iso.md

File metadata and controls

157 lines (109 loc) · 6.19 KB
sidebar_label title description hide_table_of_contents sidebar_position tags
Build Edge Installer ISO
Build Edge Installer ISO with Trusted Boot
Learn about how to build Edge Installer ISO for Trusted Boot.
false
20
edge

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. 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 as needed. You can install tools and dependencies and make other image modifications. 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.

    :::warning

    When customizing the Dockerfile to add custom binaries, install them into /usr/bin. Do not use /usr/local, as this directory is mounted from the persistent partition at boot and makes files added during image build unavailable at runtime.

    :::

    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

    Package installation commands in the Dockerfile must be non-interactive. Ensure you use the appropriate non-interactive flag for your package manager, for example, --non-interactive for Zypper or --yes for Advanced Package Tool (APT). Interactive prompts cause the image build to fail. This guidance applies to all dependencies you add through the Dockerfile.

    View the Dockerfile to ensure the instruction to install WireGuard is appended correctly.

    cat Dockerfile

    :::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.