Build AWS Cloud Images

In this guide, you will use the CanvOS utility to build provider images that enable deploying Edge clusters on Amazon Elastic Compute Cloud (Amazon EC2). The aws-cloud-image target takes a CanvOS raw disk image and imports it into Amazon Web Services (AWS), creating and registering an Amazon Machine Image (AMI) that you can use to launch EC2 instances. This target automates the workflow from raw image creation through AMI registration in AWS.

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.

• An Amazon S3 bucket for image storage and the credentials to access it. Refer to the Getting started with Amazon S3 guide for further information on S3 usage. Your AWS credentials must have the following permissions:

  • s3:PutObject
  • s3:GetObject
  • s3:ListBucket
  • ec2:ImportSnapshot
  • ec2:DescribeImportSnapshotTasks
  • ec2:DescribeSnapshots
  • ec2:RegisterImage
  • ec2:DescribeImages
  • ec2:CreateTags

Build AWS Cloud Images

1. Check out 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 git tag.

   git tag

4. Check out the newest available tag. This guide uses the tag v4.8.5 as an example.

   git checkout v4.8.5

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

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

7. 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 Domain Name System (DNS) rules and may not contain underscores.

   export IMAGE_REGISTRY=[REGISTRY-HOSTNAME]

8. Issue the following command to use the Ubuntu OS distribution and use the 24.04 version.

   export OS_DISTRIBUTION=ubuntu
   export OS_VERSION=24.04

9. Issue the following command to use the Palette eXtended Kubernetes - Edge (PXK-E) Kubernetes distribution and use the 1.33.5 version.

   export K8S_DISTRIBUTION=kubeadm
   export K8S_VERSION=1.33.5

10. Use the command below to save the image S3 bucket region in the REGION argument and the S3 bucket name in the S3_BUCKET argument. Before you execute the command, replace [S3-BUCKET-REGION] with your bucket region and [S3-BUCKET-NAME] with your bucket name.

    export REGION=[S3-BUCKET-REGION]
    export S3_BUCKET=[S3-BUCKET-NAME]

11. Optionally, you can set an S3 object key for your image. Replace the [IMAGE-KEY] with a custom image key and execute the command. If you do not set a key, the image tag you set in Step 6 will be used.

    export S3_KEY=[IMAGE-KEY]

12. Use the command below to save your AWS access key in the AWS_ACCESS_KEY_ID argument and the AWS secret access key in the AWS_SECRET_ACCESS_KEY argument. Before you execute the command, replace [ACCESS-KEY] with your access key and [SECRET_ACCESS_KEY] with your secret access key.

    export AWS_ACCESS_KEY_ID=[ACCESS-KEY]
    export AWS_SECRET_ACCESS_KEY=[SECRET_ACCESS_KEY]

13. 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
    REGION=$REGION
    S3_BUCKET=$S3_BUCKET
    S3_KEY=$S3_KEY
    EOF

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

14. (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 do not need from the JSON object corresponding to your Kubernetes distribution.

15. Issue the command below to create a .secret file containing your AWS credentials.

    cat << EOF > .secret
    AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
    EOF

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

    ./earthly.sh +aws-cloud-image --ARCH=amd64

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

Validate

1. Sign in to the AWS Management Console.

2. Navigate to Amazon S3.

3. Open the bucket you configured in Step 10.

4. Verify that the provider image file appears in the object list.