Skip to main content
Version: latest

Build Edge Artifacts

Palette's Edge solution requires Edge hosts to be ready with the required dependencies and user data configurations before deploying a Kubernetes cluster. An Edge host requires the following artifacts to prepare for successful cluster deployment:

  • Edge installer ISO image - This bootable ISO image installs the necessary dependencies and configurations on a bare host machine. During installation, the host machine will boot from the Edge installer ISO, partition the disk, copy the image content to the disk, install the Palette Edge host agent and metadata, and perform several configuration steps. These configuration steps include registering the host with Palette, setting user privileges, and configuring network or security settings.

  • Provider Images - These are Kairos-based images containing the OS and the desired Kubernetes versions. These images install an immutable Operating System (OS) and software dependencies compatible with a specific Kubernetes version at runtime, i.e., during the cluster deployment. A provider image is used in the OS and the Kubernetes layer when creating a cluster profile.

In this guide, you will use the utility, CanvOS, to build an Edge installer ISO image and provider images for all the Palette-supported Kubernetes versions. The utility builds multiple provider images, so you can use either one that matches the desired Kubernetes version you want to use with your cluster profile.


CanvOS is a utility that helps you build Edge artifacts. CanvOS is part of the EdgeForge workflow.

The diagram below shows the high-level steps to building the Edge artifacts and pushing the provider images to an image registry.

Overarching diagram showing the workflow in the current guide.

This guide presents two workflows - Basic and Advanced.

The basic workflow has minimal customizations and offers a quick start to build Edge artifacts. This workflow builds an Ubuntu based Edge installer ISO and provider images. You will also push the provider images to the default image registry,

The advanced workflow uses more customization options. This workflow builds an openSUSE based Edge installer ISO and provider images. You will push the provider images to your Docker Hub image registry.

You can follow either of the workflows below that suits your use case.


To complete this basic guide, you will need the following items:

  • 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
    • 8 GB memory
    • 50 GB storage
  • Git. You can ensure git installation by issuing the git --version command.
  • Docker Engine version 18.09.x or later. You can use the docker --version command to view the existing Docker version. You should have root-level or sudo privileges on your Linux machine to create privileged containers.
  • 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.


Use the following instructions on your Linux machine to create all the required Edge artifacts with minimal customization.

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

    git clone
  1. Change to the CanvOS/ directory.

    cd CanvOS
  1. View the available git tag.

    git tag
  1. Check out the newest available tag. This guide uses v3.4.3 tag as an example.

    git checkout v3.4.3
  1. Review the files relevant for this guide.
    • .arg.template - A sample .arg file that defines arguments to use during the build process.
    • Dockerfile - Embeds the arguments and other configurations in the image.
    • Earthfile - Contains a series of commands to create target artifacts.
    • - Script to invoke the Earthfile, and generate target artifacts.
    • user-data.template - A sample user-data file.
  1. Issue the command below to assign an image tag value that will be used when creating the provider images. This guide uses the value palette-learn as an example. However, you can assign any lowercase and alphanumeric string to the CUSTOM_TAG argument.

    export CUSTOM_TAG=palette-learn

  2. Issue the command below to create the .arg file containing the custom tag. The remaining arguments in the .arg file will use the default values. For example, ubuntu is the default operating system, demo is the default tag, and is the default image registry. Refer to the existing .arg.template file in the current directory or the README to learn more about the available customizable arguments.


    The default image registry is free and does not require a sign-up. Images pushed to are ephemeral and will expire after the 24 hrs time limit. Should you need to use a different image registry, refer to the Advanced workflow in the Build Edge Artifacts guide.

    Using the arguments defined in the .arg file, the final provider images you generate will have the following naming convention, [IMAGE_REGISTRY]/[IMAGE_REPO]:[CUSTOM_TAG]. For example, one of the provider images will be

    cat << EOF > .arg
    PE_VERSION=$(git describe --abbrev=0 --tags)

    View the newly created file to ensure the customized arguments are set correctly.

    cat .arg
  1. Issue the command below to save your tenant registration token to an environment variable. Replace [your_token_here] with your actual registration token.

    export token=[your_token_here]
  2. Use the following command to create the user-data file containing the tenant registration token. Also, you can click on the Points of Interest numbers below to learn more about the main attributes relevant to this example.

    cat << EOF > user-data
    edgeHostToken: $token
    poweroff: true
    - name: kairos
    passwd: kairos

    View the newly created user data file to ensure the token is set correctly.

    cat user-data

  3. The CanvOS utility uses Earthly to build the target artifacts. Issue the following command to start the build process.

    sudo ./ +build-all-images
    ===================== Earthly Build SUCCESS ===================== 
    Share your logs with an Earthly account (experimental)! Register for one at

    If you plan to build Edge artifacts using a content bundle, use the +build-provider-images option instead of the +build-all-images option in the command above. The command, sudo ./ +build-provider-images, will build the provider images but not the Edge installer ISO.

    This command may take up to 15-20 minutes to finish depending on the resources of the host machine. Upon completion, the command will display the manifest, as shown in the example below, that you will use in your cluster profile later in this tutorial. Note that the system.xxxxx attribute values in the manifest example are the same as what you defined earlier in the .arg file.

    Copy and save the output attributes in a notepad or clipboard to use later in your cluster profile.

    - image: "{{.spectro.pack.edge-native-byoi.options.system.uri}}"
    system.uri: "{{ .spectro.pack.edge-native-byoi.options.system.registry }}/{{ .spectro.pack.edge-native-byoi.options.system.repo }}:{{ .spectro.pack.edge-native-byoi.options.system.k8sDistribution }}-{{ .spectro.system.kubernetes.version }}-{{ .spectro.pack.edge-native-byoi.options.system.peVersion }}-{{ .spectro.pack.edge-native-byoi.options.system.customTag }}"
    system.repo: ubuntu
    system.k8sDistribution: k3s
    system.osName: ubuntu
    system.peVersion: v3.4.3
    system.customTag: demo
    system.osVersion: 22

  1. List the Docker images to review the provider images created. By default, provider images for all the Palette's Edge-supported Kubernetes versions are created. You can identify the provider images by reviewing the image tag value you used in the .arg file's CUSTOM_TAG argument.

    docker images --filter=reference='*/*:*palette-learn'
    # Output
    REPOSITORY TAG IMAGE ID CREATED SIZE k3s-1.25.2-v3.4.3-palette-learn b3c4956ccc0a 6 minutes ago 2.49GB k3s-1.24.6-v3.4.3-palette-learn fe1486da25df 6 minutes ago 2.49GB

  1. To use the provider images in your cluster profile, push them to the image registry mentioned in the .arg file. The current example uses the image registry. This image registry is free to use and does not require a sign-up. Images pushed to are ephemeral and will expire after the 24 hrs time limit. Use the following commands to push the provider images to the image registry.

    docker push
    docker push


    As a reminder, is a short-lived image registry. If you do not use these provider images in your cluster profile within 24 hours of pushing to, they will expire and must be re-pushed. Refer to the Advanced workflow in the current guide to learn how to use another registry, such as Docker Hub, and tag the docker images accordingly.

  1. After pushing the provider images to the image registry, open a web browser and log in to Palette. Ensure you are in the Default project scope before creating a cluster profile.
  1. Navigate to the left Main Menu and select Profiles. Click on the Add Cluster Profile button, and fill out the required basic information fields to create a cluster profile for Edge.
  1. Add the following BYOS Edge OS pack to the OS layer in the Profile Layers section.

    Pack TypeRegistryPack NamePack Version
    OSPublic RepoBYOS Edge OS1.0.0
  1. Replace the the cluster profile's BYOOS pack manifest with the following custom manifest so that the cluster profile can pull the provider image from the image registry.

    The system.xxxxx attribute values below refer to the arguments defined in the .arg file. If you modified the arguments in the .arg file, you must modify the attribute values below accordingly.

    - image: "{{.spectro.pack.edge-native-byoi.options.system.uri}}"
    system.uri: "{{ .spectro.pack.edge-native-byoi.options.system.registry }}/{{ .spectro.pack.edge-native-byoi.options.system.repo }}:{{ .spectro.pack.edge-native-byoi.options.system.k8sDistribution }}-{{ .spectro.system.kubernetes.version }}-{{ .spectro.pack.edge-native-byoi.options.system.peVersion }}-{{ .spectro.pack.edge-native-byoi.options.system.customTag }}"
    system.repo: ubuntu
    system.k8sDistribution: k3s
    system.osName: ubuntu
    system.peVersion: v3.4.3
    system.customTag: demo
    system.osVersion: 22

    The screenshot below displays how to reference a provider image in the BYOOS pack of your cluster profile.

    Screenshot of a sample cluster profile&#39;s OS layer


    The BYOOS pack's system.uri attribute references the Kubernetes version selected in the cluster profile by using the {{ .spectro.system.kubernetes.version }} macro. This is how the provider images you created and pushed to a registry are tied to the OS and Kubernetes version you selected in the .arg file.

  2. Add the following Palette Optimized K3s pack to the Kubernetes layer of your cluster profile. Select the k3s version 1.25.x because earlier in this how-to guide, you pushed a provider image compatible with k3s v1.25.2 to the image registry.

    Pack TypeRegistryPack NamePack Version
    KubernetesPublic RepoPalette Optimized k3s1.25.x
  1. Add the network layer to your cluster profile, and choose a Container Network Interface (CNI) pack that best fits your needs, such as Calico, Flannel, Cilium, or Custom CNI. For example, you can add the following network layer. This step completes the core infrastructure layers in the cluster profile.

    Pack TypeRegistryPack NamePack Version
    NetworkPublic RepoCalico3.25.x
  1. Add add-on layers and manifests to your cluster profile per your requirements.
  1. If there are no errors or compatibility issues, Palette displays the newly created complete cluster profile for review. Verify the layers you added, and finish creating the cluster profile.


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

ls build/
# Output

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.

Next Steps

After building the Edge artifacts and creating an Edge cluster profile, the next step is to use the Edge installer ISO image to prepare your Edge host. To learn more about utilizing Edge artifacts to prepare Edge hosts and deploy Palette-managed Edge clusters, we encourage you to check out the reference resources below.