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

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.3.0 as an example.
```
git checkout v4.3.0
```
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
```
Open the Earthfile in the CanvOS directory. Under build-provider-images, remove the lines containing Kubernetes versions that you do not need.

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=k3s
ARCH=amd64
HTTPS_PROXY=
HTTP_PROXY=
PROXY_CERT_PATH=
UPDATE_KERNEL=false
EOF

Refer to Edge Artifact Build Configurations for all available arguments.

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

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