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.

If you want to build the ISO image and the provider images individually, refer to Build Provider Images and Build Installer ISO.

info

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, ttl.sh.

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.

Prerequisites​

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.

  • (Optional) Earthly is installed and available. If you do not install Earthly, you can still build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the root user.

  • An image management tool such as Docker or crane is installed and available.

    info

    If you do not install Earthly, you must install Docker.

  • A Spectro Cloud account. If you have not signed up, you can sign up for an account here.

  • 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​

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 https://github.com/spectrocloud/CanvOS.git

  2. Change to the CanvOS/ directory.

    cd CanvOS

  3. View the available git tag.

    git tag

  4. Check out the newest available tag. This guide uses the tag v4.4.12 as an example.

    git checkout v4.4.12

  5. 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.
    • earthly.sh - Script to invoke the Earthfile, and generate target artifacts.
    • user-data.template - A sample user-data file.

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

  7. 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 ttl.sh 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.

    info

    The default ttl.sh image registry is free and does not require a sign-up. Images pushed to ttl.sh 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 on this page.

    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 ttl.sh/ubuntu:k3s-1.27.2-v4.4.12-palette-learn.

    cat << EOF > .arg
    CUSTOM_TAG=$CUSTOM_TAG
    IMAGE_REGISTRY=ttl.sh
    OS_DISTRIBUTION=ubuntu
    IMAGE_REPO=ubuntu
    OS_VERSION=22.04
    K8S_DISTRIBUTION=k3s
    ISO_NAME=palette-edge-installer
    ARCH=amd64
    HTTPS_PROXY=
    HTTP_PROXY=
    PROXY_CERT_PATH=
    UPDATE_KERNEL=false
    EOF

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

    cat .arg

  8. 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]

  9. Use the following command to create the user-data file containing the tenant registration token.

    cat <<EOF > user-data
    #cloud-config

    stylus:
       site:
         edgeHostToken: $token

    install:
       poweroff: true

    stages:
       initramfs:
       - name: "Core system setup"
         users:
           kairos:
             groups:
               - admin
             passwd: kairos
    EOF

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

    cat user-data

  10. Open the k8s_versions.json file in the CanvOS directory. Remove the Kubernetes versions that you don't need from the JSON object corresponding to your Kubernetes distribution.

    If you are using a tag that is earlier than v4.4.12, the k8s_versions.json file does not exist in those tags. Instead, open the Earthfile in the CanvOS directory. In the file, find the block that starts with build-provider-images-fips: and delete the Kubernetes versions that you do not want. This will speed up the build process and save storage space.

  11. Issue the following command to start the build process.

    earthly +build-all-images
    ===================== Earthly Build SUCCESS =====================
    Share your logs with an Earthly account (experimental)! Register for one at https://ci.earthly.dev.
    info

    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 ./earthly.sh +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.

    pack:
      content:
        images:
          - image: "{{.spectro.pack.edge-native-byoi.options.system.uri}}"
      # Below config is default value, please uncomment if you want to modify default values
      # drain:
      #cordon: true
      #timeout: 60 # The length of time to wait before giving up, zero means infinite
      #gracePeriod: 60 # Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used
      #ignoreDaemonSets: true
      #deleteLocalData: true # Continue even if there are pods using emptyDir (local data that will be deleted when the node is drained)
      #force: true # Continue even if there are pods that do not declare a controller
      #disableEviction: false # Force drain to use delete, even if eviction is supported. This will bypass checking PodDisruptionBudgets, use with caution
      #skipWaitForDeleteTimeout: 60 # If pod DeletionTimestamp older than N seconds, skip waiting for the pod. Seconds must be greater than 0 to skip.
    options:
      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.registry: ttl.sh
      system.repo: ubuntu
      system.k8sDistribution: k3s
      system.osName: ubuntu
      system.peVersion: v4.4.12
      system.customTag: palette-learn
      system.osVersion: 22

  12. 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'
    REPOSITORY             TAG                                   IMAGE ID       CREATED         SIZE
    ttl.sh/ubuntu          k3s-1.27.2-v4.4.12-palette-learn       075134ad5d4b   10 minutes ago   4.11GB
    ttl.sh/ubuntu          k3s-1.25.2-v4.4.12-palette-learn       02424d29fcac   10 minutes ago   4.09GB
    ttl.sh/ubuntu          k3s-1.26.4-v4.4.12-palette-learn       4e373ddfb53f   10 minutes ago   4.11GB

  13. 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 ttl.sh image registry. This image registry is free to use and does not require a sign-up. Images pushed to ttl.sh are ephemeral and will expire after the 24 hrs time limit. Use the following commands to push the provider images to the ttl.sh image registry.

    docker push ttl.sh/ubuntu:k3s-1.25.2-v4.4.12-palette-learn
    docker push ttl.sh/ubuntu:k3s-1.26.4-v4.4.12-palette-learn
    docker push ttl.sh/ubuntu:k3s-1.27.2-v4.4.12-palette-learn
    warning

    As a reminder, ttl.sh is a short-lived image registry. If you do not use these provider images in your cluster profile within 24 hours of pushing to ttl.sh, 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.

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

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

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

  17. Replace the cluster profile's BYOOS pack manifest with the following custom manifest so that the cluster profile can pull the provider image from the ttl.sh 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.

    pack:
      content:
        images:
          - image: "{{.spectro.pack.edge-native-byoi.options.system.uri}}"
      # Below config is default value, please uncomment if you want to modify default values
      # drain:
      #cordon: true
      #timeout: 60 # The length of time to wait before giving up, zero means infinite
      #gracePeriod: 60 # Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used
      #ignoreDaemonSets: true
      #deleteLocalData: true # Continue even if there are pods using emptyDir (local data that will be deleted when the node is drained)
      #force: true # Continue even if there are pods that do not declare a controller
      #disableEviction: false # Force drain to use delete, even if eviction is supported. This will bypass checking PodDisruptionBudgets, use with caution
      #skipWaitForDeleteTimeout: 60 # If pod DeletionTimestamp older than N seconds, skip waiting for the pod. Seconds must be greater than 0 to skip.
    options:
      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.registry: ttl.sh
      system.repo: ubuntu
      system.k8sDistribution: k3s
      system.osName: ubuntu
      system.peVersion: v4.4.12
      system.customTag: palette-learn
      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

    info

    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.

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

    Pack TypeRegistryPack NamePack Version
    KubernetesPublic RepoPalette Optimized k3s1.27.x

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

  20. Add add-on layers and manifests to your cluster profile per your requirements.

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

Validate​

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

ls build/
palette-edge-installer.iso
palette-edge-installer.iso.sha256

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.

Resources​