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. -
Docker Engine version 18.09.x or later. You can use the
docker --version
command to check the existing Docker version. You should have root-level orsudo
privileges on your Linux machine to create privileged containers. -
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.
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
-
Clone the CanvOS GitHub repository containing the starter code.
git clone https://github.com/spectrocloud/CanvOS.git
-
Change to the CanvOS/ directory.
cd CanvOS
-
View the available tags and check out the latest tag or any specific version of your choosing. This guide uses v4.3.2 as an example.
git tag
git checkout v4.3.2
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.
- Red Hat Enterprise Linux
- Ubuntu
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.
-
Change into the rhel-fips directory.
-
In the file Dockerfile, provide your RHEL subscription username and password.
ARG USERNAME=name@spectrocloud.com
ARG PASSWORD=*********** -
Issue the following command to start building the provider images.
bash build.sh
infoIf 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 '*******' \
-
When the build finishes, issue
docker images
and confirm there is an image namedrhel-byoi-fips:latest
. This is the base image that you will use to build provider images and the Edge installer ISO later on. -
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
-
Push the image to the repository.
docker push ttl.sh/rhel/rhel-byoi-fips:latest
-
Change into the ubuntu-fips directory.
-
In the file pro-attach-config.yaml, provide your Ubuntu Pro subscription token.
token: *******
-
Issue the following command to start building the provider images.
bash build.sh
-
When the build finishes, issue
docker images
and confirm there is an image namedubuntu-focal-fips:latest
. This is the base image that you will use to build provider images and the Edge installer ISO later on. -
Tag the image with a repository that is accessible by your Linux machine. For example, use the publicly accessible
ttl.sh
repository.docker tag ubuntu-focal-fips:latest ttl.sh/ubuntu/ubuntu-focal-fips:latest
-
Push the image to the repository.
docker push ttl.sh/ubuntu/ubuntu-focal-fips:latest
Build Edge Installer ISO
-
Return to the CanvOS directory.
cd ..
-
Create a file named .arg. This file will contain parameters that customize the Edge Installer ISO build.
-
In the .arg file, provide the following required information. Refer to Edge Artifact Build Configuration for more information.
Argument Description IMAGE_REGISTRY The image registry to use for tagging the generated provider images. OS_DISTRIBUTION The OS distribution in your provider image. IMAGE_REPO The image repository to use for tagging the generated provider images. OS_VERSION The OS version in your provider image. This applies to Ubuntu only. K8S_DISTRIBUTION The Kubernetes distribution for your provider image. Allowed values are rke2
(RKE2) andkubeadm-fips
(PXK-E). The other distributions are not FIPS-compliant.FIPS_ENABLED Whether to enable FIPS compliance. This parameter must be set to true
.ARCH The architecture of the image. Allowed values are amd64
andarm64
.BASE_IMAGE The 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_NAME The file name of the ISO file that will be generated. -
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 foredgeHostToken
with your VerteX registration token, and replace the valuepaletteEndPoint
with the URL of your Palette instance. Replace the userkairos
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: kairosThe command in the
install
block is required for FIPS installations. Configurations in thestylus
block provide the Edge Host with the registration token and the Palette endpoint. And the configurations in thestage
block create a system user that you can use to log in to the Operating System (OS). -
Add further customization to the user-data file as needed. This file configures the Edge Installer. Refer to Installer Reference for more information.
-
Issue the following command to build the Edge Installer ISO.
./earthly.sh +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.
-
Locate 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. -
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
warningFor the Kubernetes distribution set in your .arg file, only
rke2
andkubeadm-fips
will produce FIPS-compliant provider images.
Validate
-
Follow the Site Installation guide to install the Palette Edge on your Edge host.
-
Press Fn + Ctrl + Cmd + F1 or Ctrl + Cmd + F1 keys on a mac keyboard and provide user credentials to log in to the OS.
-
Issue the following command and ensure that the output is
1
. This means the OS is FIPS enabled.cat /proc/sys/crypto/fips_enabled