Write images README with instructions on how to build constellation images locally (#181)

Write images README with instructions on how to build constellation images locally

Co-authored-by: Daniel Weiße <66256922+daniel-weisse@users.noreply.github.com>

.gitignore

@@ -31,6 +31,7 @@ image/dependencies/coordinator
 image/dependencies/cilium
 image/images/*
 image/cosa.lock
+image/config.mk
 
 # Terraform
 *.tfstate

image/Makefile

@@ -46,6 +46,8 @@ AZURE_IMAGE_VERSION              ?= 0.0.1
 AZURE_PUBLISHER                  ?= edgelesssys
 AZURE_SKU                        ?= constellation-coreos
 
+-include $(CURDIR)/config.mk
+
 .PHONY: clean all kernel coreos run shell cosa-init cosa-fetch images image-gcp upload-gcp image-azure upload-azure-non-cvm $(COORDINATOR_OVERRIDE_PATH) $(DISK_MAPPER_OVERRIDE_PATH) $(CILIUM_CLI_OVERRIDE_PATH)
 SHELL := /bin/bash
 
@@ -163,4 +165,5 @@ endif
 clean:
 	-rm $(COSA_LOCKFILE)
 	-rm $(IMAGES_PATH)/*
-	-. $(COSA_ENV) && cd $(COREOS_BUILD_PATH) && cosa clean
+	-rm -r $(COREOS_BUILD_PATH)
+	mkdir -p $(COREOS_BUILD_PATH)

image/README.md

@@ -0,0 +1,95 @@
+# Constellation images
+
+We use the [Fedora CoreOS Assembler](https://coreos.github.io/coreos-assembler/) to build the base image for Constellation nodes.
+
+## Setup
+
+1. Install prerequisites:
+   - [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/getting-started/installation)
+   - [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-linux)
+   - [azcopy](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10)
+   - [Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
+   - [gsutil](https://cloud.google.com/storage/docs/gsutil_install#linux)
+   - Ubuntu:
+
+        ```shell-session
+        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
+
+   ```shell-session
+   gcloud auth login
+   az login
+   ```
+
+3. [Log in to the ghcr.io package registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry)
+4. Ensure read and write access to `/dev/kvm` (and repeat after every reboot)
+
+    ```shell-session
+    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](Makefile).
+Important settings are:
+
+- `COORDINATOR_BINARY`: path to a coordinator 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 wat 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 wat 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`:
+
+```Makefile
+COORDINATOR_BINARY = ../build/debugd
+CONTAINER_ENGINE = docker
+GCP_IMAGE_NAME = my-custom-image
+AZURE_IMAGE_NAME = my-custom-image
+```
+
+## Build an 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!):
+
+```shell-session
+sudo make clean
+```
+
+- Build QEMU image (for local testing only)
+
+  ```shell-session
+  make coreos
+  ```
+
+- Build Azure image (without upload)
+
+  ```shell-session
+  make image-azure
+  ```
+
+- Build Azure image (with upload)
+
+  ```shell-session
+  make image-azure upload-azure
+  ```
+
+- Build GCP image (without upload)
+
+  ```shell-session
+  make image-gcp
+  ```
+
+- Build GCP image (with upload)
+
+  ```shell-session
+  make image-gcp upload-gcp
+  ```
+
+Resulting images for the CSPs can be found under [images](images/). QEMU images are stored at `build/builds/latest/` with a name ending in `.qcow2`.