CanvOS is designed to leverage the Spectro Cloud Edge Forge architecture to build Edge artifacts. Edge artifacts are used by Palette when creating Edge clusters with little to no touch by end users.
CanvOS, uses Earthly to build all of the required artifacts for an Edge deployments. The Edge artifacts include the installer ISO to the Kubernetes Provider images. CanvOS enables you to customize images to fit your needs.
To learn more about building Edge artifacts, checkout the Build Edge Artifacts guide.
The base image definitions reside in the Earthfile located in this repo. The Earthfile defines all of the elements that are required for building the artifacts that can be used by Palette for Edge deployments.
If customized packages need to be added, add the pagekage to the Dockerfile as you would for any Docker image. When the build command is invoked, the Earthfile will merge the custom packages into the final image.
Checkout the Build Edge Artifacts guide for detailed instructions.
From the Kairos project, this is derived from the operating system distribution chosen (currently Ubuntu and OpenSuse-Leap supported). It is pulled down as the base image and some adjustments are made to better support Palette. Those adjustments are used to clean and update the image as well as install some required packages.
From the Base Image, the provider image is used to package in the Kubernetes distribution and version(s) that are part of the build. This layer is required to initialize the system and prepare it for configuration to build the Kubernetes cluster.
From the base image, this image is used to provide the initial flashing of a device (bare-metal or virtual machine). This image contains the user-data configuration that has been provided in user-data
. It will also contain the contents of any content bundle for pre-staged builds. Pre-staged builds can be used to embed all of the artifacts that are required to build a cluster. These artifacts include Helm charts, manifests, and container images. These images are loaded into containerd when the cluster is initialized elminating the need for the initial download. For more information on how to build pre-loaded content checkout the Palette Docs at Build your Own Content.
For advanced use cases, there may be a need to add additional packages not included in the Base Images. If those packages or configuration elements need to be added, they can be included in the empty Dockerfile
located in this repo and they will be included in the build process and output artifacts.
- Clone the repo at CanvOS
git clone https://github.com/spectrocloud/CanvOS.git
Sample Output
Cloning into 'CanvOS'...
remote: Enumerating objects: 133, done.
remote: Counting objects: 100% (133/133), done.
remote: Compressing objects: 100% (88/88), done.
Receiving objects: 100% (133/133), 40.16 KiB | 5.02 MiB/s, done.
Resolving deltas: 100% (60/60), done.
remote: Total 133 (delta 60), reused 101 (delta 32), pack-reused 0
- Change into the
CanvOS
directory that was created.
cd CanvOS
- View Available tags
git tag
v3.3.3
v3.4.0
v3.4.1
v3.4.3
- Checkout the desired tag
git checkout <tag version>
Sample Output
git checkout v3.4.3
Note: switching to 'v3.4.3'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
- Copy the .arg.template file to .arg
cp .arg.template .arg
- Modify the
.arg
file as needed. Primarily, you must define the tag you want to use for your images. For example, if the operating system isubuntu
and the tag isdemo
, the image artefact will name asttl.sh/ubuntu:k3s-1.25.2-v3.4.3-demo
. The .arg file defines the following variables:
Parameter | Description | Type | Default Value |
---|---|---|---|
CUSTOM_TAG | Environment name for provider image tagging. The default value is demo . |
String | demo |
IMAGE_REGISTRY | Image registry name that will store the image artifacts. The default value points to the ttl.sh image registry, an anonymous and ephemeral Docker image registry where images live for a maximum of 24 hours by default. If you wish to make the images exist longer than 24 hours, you can use any other image registry to suit your needs. | String | ttl.sh |
OS_DISTRIBUTION | OS distribution of your choice. For example, it can be ubuntu or opensuse-leap . |
String | ubuntu |
IMAGE_REPO | Image repository name in your chosen registry. | String | $OS_DISTRIBUTION |
OS_VERSION | OS version. For Ubuntu, the possible values are 20 , and 22 . Whereas for openSUSE Leap, the possible value is 15.4 . This example uses 22 for Ubuntu. |
String | 22 |
K8S_DISTRIBUTION | Kubernetes distribution name. It can be one of these: k3s , rke2 , kubeadm , or kubeadm-fips . The value kubeadm refers to Palette eXtended Kubernetes - Edge (PXK-E). Check out the PXK-E reference resource to learn more. |
String | k3s |
ISO_NAME | Name of the Edge installer ISO image. In this example, the name is palette-edge-installer. | String | palette-edge-installer |
FIPS_ENABLED | Enable to generate FIPS compliant Edge artifacts. | String | false |
ARCH | The type of platform architecture to use for the Edge artifacts build. Allowed values are: adm64 , or arm64 . |
String | amd64 |
- Build the images with the following command. Use the
system.uri
output when creating the cluster profile for the Edge host.
./earthly.sh +build-all-images
To build FIPS complaint images or ARM images, specify the BASE_IMAGE and ARCH in the .arg file
k3s
does not FIPS and rke2 is by default FIPS
compliant.
Output
###################################################################################################
PASTE THE CONTENTS BELOW INTO YOUR CLUSTER PROFILE IN PALETTE BELOW THE "OPTIONS" ATTRIBUTE
###################################################################################################
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: v3.4.0
system.customTag: demo
system.osVersion: 22
- Validate the expected artifacts are created, the ISO image and the provider OS images.
ls build/ && docker images
palette-edge-installer.iso
palette-edge-installer.iso.sha256
# Output
REPOSITORY TAG IMAGE ID CREATED SIZE
ttl.sh/ubuntu k3s-1.24.6-v3.4.3-demo cad8acdd2797 17 hours ago 4.62GB
ttl.sh/ubuntu k3s-1.24.6-v3.4.3-demo_linux_amd64 cad8acdd2797 17 hours ago 4.62GB
ttl.sh/ubuntu k3s-1.25.2-v3.4.3-demo f6e490f53971 17 hours ago 4.62GB
ttl.sh/ubuntu k3s-1.25.2-v3.4.3-demo_linux_amd64 f6e490f53971 17 hours ago 4.62GB
Earthly is a multi-architecture build tool. In this example we are building images for AMD64 hardware which is reflected by the tags above. In the future we will support ARM64 builds and those tags will be included. We only need to push the image tag that DOES NOT have the architecture reference i.e linux_amd64
in the above example.
- The provider images are by default not pushed to a registry. You can push the images by using the
docker push
command and reference the created imgages.
docker push ttl.sh/ubuntu-demo:k3s-1.25.2-v3.4.3-demo && \
docker push ttl.sh/ubuntu-demo:k3s-1.24.6-v3.4.3-demo
⚠️ The default registry, ttl.sh is a short-lived registry. Images in the ttl.sh registry have a default time to live of 24 hours. Once the time limit is up, the images will automatically be removed. To use a permanent registry, set the.arg
file'sIMAGE_REGISTRY
parameter with the URL of your image registry.
-
Create a cluster profile using the command output. Use the Model Edge Cluster Profile to help you complete this step.
-
Flash VM or Baremetal device with the generated ISO. Refer to the Prepare Edge Host for Installation guide for additonal guidance.
-
Register the Edge host with Palette. Checkout the Register Edge Host guide.
-
Build a cluster in Palette.
-
Building Edge Native Artifacts - A how-to guide for using CanvOS.
-
Deploy Edge Cluster - An end-to-end tutorial for learning how to deploy an Edge cluster in VMware that simulates a bare metal environmet.