constellation/image/README.md

Constellation images

We use the Fedora CoreOS Assembler to build the base image for Constellation nodes.

Setup

1. Install prerequisites:

   • Docker or Podman

   • Azure CLI

   • azcopy

   • Google Cloud CLI

   • gsutil

   • Ubuntu:

     sudo apt install -y bash coreutils cryptsetup-bin grep libguestfs-tools make parted pv qemu-system qemu-utils sed tar util-linux wget
     

2. Log in to GCP and Azure

   gcloud auth login
   az login
   

3. Log in to the ghcr.io package registry

4. Ensure read and write access to /dev/kvm (and repeat after every reboot)

   sudo chmod 666 /dev/kvm
   

Configuration

Create a configuration file in image/config.mk to override any of the variables found at the top of the Makefile. Important settings are:

• BOOTSTRAPPER_BINARY: path to a bootstrapper binary. Can be substituted with a path to a debugd binary if a debug image should be built. The binary has to be built before!
• CONTAINER_ENGINE: container engine used to run COSA. either podman or docker.
• COSA_INIT_REPO: Git repository containing CoreOS config. Cloned in cosa-init target.
• COSA_INIT_BRANCH: Git branch checked out from COSA_INIT_REPO. Can be used to test out changes on another branch before merging.
• NETRC path to a netrc file containing a GitHub PAT. Used to authenticate to GitHub from within the COSA container.
• GCP_IMAGE_NAME: Image name for the GCP image. Set to include a timestamp when using the build pipeline. Can be set to a custom value if you want to upload a custom image for testing on GCP.
• AZURE_IMAGE_NAME: Image name for the Azure image. Can be set to a custom value if you want to upload a custom image for testing on Azure.

Example config.mk to create a debug image with docker and name it my-custom-image:

BOOTSTRAPPER_BINARY = ../build/debugd
CONTAINER_ENGINE = docker
GCP_IMAGE_NAME = my-custom-image
AZURE_IMAGE_NAME = my-custom-image

Build an image

Ensure you have the modified cosa container image installed:

docker image ls | grep localhost/coreos-assembler

or

podman image ls | grep localhost/coreos-assembler

If not present, install with

make cosa-image

It is always advisable to create an image from a clean build dir.

Clean up the build dir and remove old images (⚠ this will undo any local changes to the CoreOS configuration!):

sudo make clean

• Build QEMU image (for local testing only)

  make coreos
  

• Build Azure image (without upload)

  make image-azure
  

• Build Azure image (with upload)

  make image-azure upload-azure
  

• Build GCP image (without upload)

  make image-gcp
  

• Build GCP image (with upload)

  make image-gcp upload-gcp
  

Resulting images for the CSPs can be found under images. QEMU images are stored at build/builds/latest/ with a name ending in .qcow2.