Skip to main content
Version: latest

Build FIPS-Compliant Edge Artifacts

Palette Edge supports Federal Information Processing Standards (FIPS)-compliant Edge clusters. To deploy a FIPS-compliant Edge cluster, you need to build FIPS-enabled Edge artifacts. Both the Edge Installer ISO and the provider images must be FIPS-compliant.

This page guides you through the process of building FIPS-compliant Edge Installer ISO and provider images.

Limitations​

  • FIPS-compliant Edge installer does not work with secure boot. You need to disable secure boot first before installing Palette on your device. The process to disable secure boot varies by device, but generally, you can press F2 upon powering up the Edge host, and find the option to disable secure boot in the Basic Input/Output System (BIOS) interface.

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
    • 8 GB memory
    • 150 GB storage. If you plan on using a content bundle, the actual storage will depend on the size of the content bundle you will use to build the Edge installer ISO image.

  • Depending on the Operating System (OS) you want to use on your Edge host, you will need the following subscription credentials:

    • Red Hat Enterprise Linux (RHEL): RHEL subscription token.
    • Ubuntu Pro: Ubuntu Pro subscription token.

    Contact your system administrator for access to the subscription credentials.

  • 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 VerteX or Palette account. Refer to Palette VerteX for information on how to set up a VerteX account.

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

warning

You can deploy a FIPS-compliant Edge host to Palette, but this solution will not be FIPS-compliant end-to-end because Palette is not FIPS compliant. If you need a FIPS-compliant solution, you need to use VerteX.

Build FIPS-Enabled Edge Artifacts​

Clone CanvOS Repository​

  1. Clone 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 tags and check out the latest tag or any specific version of your choosing. This guide uses v4.4.12 as an example.

    git tag
    git checkout v4.4.12

Build FIPS-Compliant Base OS Image​

Before you can build the Edge Installer ISO or the provider images, you need to build a FIPS-compliant OS base image with the Kairos framework. This base image is then used to build the final Edge artifacts.

Palette supports the RHEL and Ubuntu for FIPS-compliant base OS images. Choose the OS that you want to build the base image with.

warning

When you create a cluster with an Edge host that operates the FIPS-compliant RHEL Operating System (OS), you may encounter an error where the systemd-resolved.service service enters the failed state. This prevents the nameserver from being configured, which will result in cluster deployment failure. Refer to TroubleShooting for a workaround.

  1. Change into the rhel-fips directory.

  2. In the file Dockerfile, provide your RHEL subscription username and password.

    ARG USERNAME=name@spectrocloud.com
    ARG PASSWORD=***********

  3. Issue the following command to start building the provider images.

    bash build.sh
    info

    If you experience issues with the script not recognizing the RHEL credentials, try searching Dockerfile for the following line and replacing the credentials directly:

    RUN rm /etc/rhsm-host && subscription-manager register --username 'your-username' --password '*******' \

  4. When the build finishes, issue docker images and confirm there is an image named rhel-byoi-fips:latest. This is the base image that you will use to build provider images and the Edge installer ISO later on.

  5. Tag the image with a repository that is accessible by your Linux machine. For example, the following command uses the publicly accessible ttl.sh repository.

    docker tag rhel-byoi-fips:latest ttl.sh/rhel/rhel-byoi-fips:latest

  6. Push the image to the repository.

    docker push ttl.sh/rhel/rhel-byoi-fips:latest

Build Edge Installer ISO​

  1. Return to the CanvOS directory.

    cd ..

  2. Create a file named .arg. This file will contain parameters that customize the Edge Installer ISO build.

  3. In the .arg file, provide the following required information. Refer to Edge Artifact Build Configuration for more information.

    ArgumentDescription
    IMAGE_REGISTRYThe image registry to use for tagging the generated provider images.
    OS_DISTRIBUTIONThe OS distribution in your provider image.
    IMAGE_REPOThe image repository to use for tagging the generated provider images.
    OS_VERSIONThe OS version in your provider image. This applies to Ubuntu only.
    K8S_DISTRIBUTIONThe Kubernetes distribution for your provider image. Allowed values are rke2 (RKE2) and kubeadm-fips (PXK-E). The other distributions are not FIPS-compliant.
    FIPS_ENABLEDWhether to enable FIPS compliance. This parameter must be set to true.
    ARCHThe architecture of the image. Allowed values are amd64 and arm64.
    BASE_IMAGEThe base image used by EdgeForge to build the Edge Installer and provider images. This must be the same image that you build in the previous step.
    ISO_NAMEThe file name of the ISO file that will be generated.

  4. (Optional) This step is only required if your builds occur in a proxied network environment, and your proxy servers require client certificates or if your base image is in a registry that requires client certificates.

    You can provide the base-64 encoded certificates in PEM format in the certs folder at the root directory of the CanvOS repository. You can provide as many certificates as you need in the folder.

    If you are using a CanvOS tag that is earlier than 4.5.15, you need to use the PROXY_CERT_PATH build argument to provide a path to the certificate. This approach only allows you to specify one certificate. For more information, refer to Earthly Build Arguments.

    warning

    These proxy settings are only configured for the build process itself, when your builder machine needs to pull certain images to build the Edge artifacts. These certificates will not be present on the host after it has been deployed. To configure the proxy network settings for a host, refer to Configure HTTP Proxy or Configure Proxy in User Data.

  5. Create a file named user-data. It must have the #cloud-init header at the top of the file. Ensure you have the following blocks at the root level of the user-data file. Replace the value for edgeHostToken with your VerteX registration token, and replace the value paletteEndPoint with the URL of your Palette instance. Replace the user kairos and its password with your desired username and password.

    #cloud-init
    install:
       grub_options:
         extra_cmdline: "fips=1 selinux=0"

    stylus:
       site:
         edgeHostToken: ********
         paletteEndpoint: https://vertex.palette-devx.spectrocloud.com
         projectName: Default

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

    The command in the install block is required for FIPS installations. Configurations in the stylus block provide the Edge Host with the registration token and the Palette endpoint. And the configurations in the stage block create a system user that you can use to log in to the Operating System (OS).

  6. Add further customization to the user-data file as needed. This file configures the Edge Installer. Refer to Installer Reference for more information.

  7. Issue the following command to build the Edge Installer ISO.

    earthly +iso

    When the build finishes, the ISO file will be generated in the build directory under the name you specified in your .arg file.

Build Provider Images​

Provider images are Kairos-based container images for a supported OS and Kubernetes distribution combination. FIPS-complaint provider images are built on top of the base OS image you have built previously.

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

  2. Review the .arg file again to ensure the parameters are correct. Issue the following command to build the provider images.

      ./earthly +build-provider-images-fips
    warning

    For the Kubernetes distribution set in your .arg file, only rke2 and kubeadm-fips will produce FIPS-compliant provider images.

Validate​

  1. Follow the Site Installation guide to install the Palette Edge on your Edge host.

  2. Press Fn + Ctrl + Cmd + F1 or Ctrl + Cmd + F1 keys on a mac keyboard and provide user credentials to log in to the OS.

  3. Issue the following command and ensure that the output is 1. This means the OS is FIPS enabled.

    cat /proc/sys/crypto/fips_enabled