Skip to main content

Build Provider Images

In this guide, you will use the CanvOS utility to build provider images for your Edge deployment. Provider images 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 during the cluster deployment. A provider image is used in the OS and the Kubernetes layer when creating a cluster profile. These container images are downloaded during the installation by the Edge Installer and converted to disk images for the system to boot into.

info

The provider images are one of the critical artifacts you need to build during EdgeForge. The other artifact is the Edge Installer ISO. Both are required for Edge deployment. For education purposes, we provide separate instructions for building the installer ISO and the provider images. However, these two artifacts are often built together in a single step in practice. Refer to Build Edge Artifacts for an how-to that covers how to build both artifacts at the same time.

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

Build Provider Images

Check out 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 git tag.
```
git tag
```
Check out the newest available tag. This guide uses the tag v4.4.12 as an example.
```
git checkout v4.4.12
```
Review the files relevant for this guide.
- .arg.template - A sample .arg file that defines arguments to use during the build process.
- Earthfile - Contains a series of commands to create target artifacts.
- earthly.sh - Script to invoke the Earthfile, and generate target artifacts.
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
```
Use the command below to save the image registry hostname in the IMAGE_REGISTRY argument. Before you execute the command, replace [REGISTRY-HOSTNAME] in the declaration below with your Docker ID. Your image registry hostname must comply with standard DNS rules and may not contain underscores.
```
export IMAGE_REGISTRY=[REGISTRY-HOSTNAME]
```
Issue the following command to use the Ubuntu OS distribution and use the 22.04 version.
```
export OS_DISTRIBUTION=ubuntu
export OS_VERSION=22.04
```
warning
If RHEL is the base OS for your Palette eXtended Kubernetes - Edge (PXK-E) cluster running Kubernetes v1.32.x or later, we recommend using RHEL 9.x to avoid a known kernel compatibility issue.
Issue the following command to use the K3s Kubernetes distribution and use the 1.32.3 version.
```
export K8S_DISTRIBUTION=k3s
export K8S_VERSION=1.32.3
```
Issue the command below to create an .arg file. The .arg file uses the default values for the remaining arguments.
```
cat << EOF > .arg
IMAGE_REGISTRY=$IMAGE_REGISTRY
OS_DISTRIBUTION=$OS_DISTRIBUTION
OS_VERSION=$OS_VERSION
IMAGE_REPO=$OS_DISTRIBUTION
CUSTOM_TAG=$CUSTOM_TAG
K8S_DISTRIBUTION=$K8S_DISTRIBUTION
K8S_VERSION=$K8S_VERSION
ARCH=amd64
HTTPS_PROXY=
HTTP_PROXY=
PROXY_CERT_PATH=
UPDATE_KERNEL=false
EOF
```
warning
If you want your host eligible to become part of a two-node high availability cluster, you must set TWO_NODE to true. This setting cannot be changed later. A two-node provider image cannot be used to provision regular etcd clusters. We recommend you clearly mark two-node provider images in the custom tag argument. For more information about two-node high availability architecture, refer to Two-Node Architecture.

Refer to Edge Artifact Build Configurations for all available configuration parameters.

tech preview
The K8S_DISTRIBUTION argument, defined in the .arg file, accepts canonical as a valid value. This value corresponds to the Palette Optimized Canonical pack, which is a Tech Preview feature and is subject to change. Do not use this feature in production workloads.
(Optional) If you want to build multiple versions of provider images using different Kubernetes versions, remove the K8S_VERSION argument from the .arg file. Open the k8s_version.json file in the CanvOS directory. Remove the Kubernetes versions that you don't need from the JSON object corresponding to your Kubernetes distribution.
(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.
(Optional) You can embed a public key in your provider image. If you choose to add a public key to your provider image, after you create a cluster with the provider image, only content that is signed by the corresponding private key can be uploaded to the Edge host through Local UI. This includes both the content bundle and cluster definition. For more information, refer to Embed Public Key in Edge Artifacts.

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

Earthly Installed
Earthly Not Installed

earthly +build-provider-images

sudo ./earthly.sh +build-provider-images

# Output condensed for readability
===================== Earthly Build SUCCESS =====================
Share your logs with an Earthly account (experimental)! Register for one at https://ci.earthly.dev.

To use the provider images in your cluster profile, push them to your image registry mentioned in the .arg file. Issue the following command to log in to Docker Hub. Provide your Docker ID and password when prompted.
```
docker login
```
Use the following commands to push the provider images to the Docker Hub image registry you specified. Replace the [REGISTRY-HOSTNAME] and version numbers in the command below.
```
docker push [REGISTRY-HOSTNAME]/ubuntu:k3s-1.28.2-v4.4.12-palette-learn
```

Validate

List the Docker images to review the provider images 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'
```

Verify that the provider images were created successfully.

REPOSITORY                            TAG                                   IMAGE ID       CREATED         SIZE
docker.io/[DOCKER-ID]/ubuntu          k3s-1.28.2-v4.4.12-palette-learn       075134ad5d4b   10 minutes ago   4.11GB

Next Steps

Provider images are only one the artifacts you need to provision an Edge deployment. You also need to build the Edge Installer ISO that matches your provider image settings. Refer to Build Edge Installer ISO for more information.

If you have built both provider images and the installer ISO, refer to Site Deployment to learn how to deploy your Edge cluster.

Prerequisites
Build Provider Images
Validate
Next Steps