From 5956f961a63c1b9e3002fe98577093e650a77ee7 Mon Sep 17 00:00:00 2001
From: k8s-bot <angelos.kolaitis@canonical.com>
Date: Wed, 26 Jun 2024 21:07:49 +0300
Subject: [PATCH] document custom LXD images

---
 tests/integration/README.md | 83 +++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/tests/integration/README.md b/tests/integration/README.md
index 063019f7d..b16d964e0 100644
--- a/tests/integration/README.md
+++ b/tests/integration/README.md
@@ -53,9 +53,86 @@ Then, run the tests with:
 export TEST_SNAP=$PWD/k8s.snap
 export TEST_SUBSTRATE=lxd
 
-export TEST_LXD_IMAGE=ubuntu:22.04          # (optionally) specify which image to use for LXD containers
-export TEST_LXD_PROFILE=k8s-integration     # (optionally) specify profile name to configure
-export TEST_SKIP_CLEANUP=1                  # (optionally) do not destroy machines after tests finish
+export TEST_LXD_IMAGE=ubuntu:22.04               # (optionally) specify which image to use for LXD containers
+export TEST_LXD_PROFILE_NAME=k8s-integration     # (optionally) specify profile name to configure
+export TEST_SKIP_CLEANUP=1                       # (optionally) do not destroy machines after tests finish
+
+cd tests/integration && tox -e integration
+```
+
+When using LXD, it is possible to reduce the amount of steps needed to setup each container and sideload all OCI images. See [./lxd/setup-image.sh](./lxd/setup-image.sh) for details. For example, to build an image `k8s-e2e/ubuntu` based on `ubuntu:24.04`:
+
+```bash
+# build custom image 'k8s-e2e/ubuntu'
+export TEST_SNAP=$PWD/k8s.snap
+export BASE_IMAGE=ubuntu:24.04
+export OUT_IMAGES_DIR=$PWD/k8s-e2e-images
+export OUT_IMAGE_ALIAS=k8s-e2e/ubuntu
+./tests/integration/lxd/setup-image.sh
+
+# run tests using custom image
+export TEST_SUBSTRATE=lxd
+export TEST_LXD_IMAGE=k8s-e2e/ubuntu
+export TEST_LXD_SIDELOAD_IMAGES_DIR=$PWD/k8s-e2e-images
+cd tests/integration && tox -e integration
+```
+
+#### Running end to end tests on LXD containers for non-Ubuntu distributions
+
+It is possible to use LXD to run the end to end tests with non-Ubuntu distributions, e.g. Debian or Alma Linux.
+
+These distributions come without snapd installed out of the box, therefore they require building a custom image with snapd installed.
+
+##### Debian 12
+
+Build an image called `k8s-e2e/debian-12` with:
+
+```bash
+export TEST_SNAP=$PWD/k8s.snap
+export BASE_IMAGE=images:debian/12
+export BASE_DISTRO=debian
+export OUT_IMAGES_DIR=$PWD/k8s-e2e-images
+export OUT_IMAGE_ALIAS=k8s-e2e/debian-12
+
+./tests/integration/lxd/setup-image.sh
+```
+
+Then, run the end to end tests with:
+
+```bash
+export TEST_SNAP=$PWD/k8s.snap
+export TEST_SUBSTRATE=lxd
+export TEST_LXD_IMAGE=k8s-e2e/debian-12
+export TEST_LXD_SIDELOAD_IMAGES_DIR=$PWD/k8s-e2e-images
+
+cd tests/integration && tox -e integration
+```
+
+##### AlmaLinux 9
+
+Build an image called `k8s-e2e/almalinux-9` with:
+
+```bash
+export TEST_SNAP=$PWD/k8s.snap
+export BASE_IMAGE=images:almalinux/9
+export BASE_DISTRO=almalinux
+export OUT_IMAGES_DIR=$PWD/k8s-e2e-images
+export OUT_IMAGE_ALIAS=k8s-e2e/almalinux-9
+
+./tests/integration/lxd/setup-image.sh
+```
+
+Then, run the end to end tests with:
+
+```bash
+export TEST_SNAP=$PWD/k8s.snap
+export TEST_SUBSTRATE=lxd
+export TEST_LXD_SIDELOAD_IMAGES_DIR=$PWD/k8s-e2e-images
+export TEST_LXD_IMAGE=k8s-e2e/almalinux-9
+
+# AlmaLinux needs a separate LXD profile
+export TEST_LXD_PROFILE_NAME=k8s-integration-almalinux
+export TEST_LXD_PROFILE="$(cat tests/integration/lxd/almalinux/lxd-profile.yaml)"
 
 cd tests/integration && tox -e integration
 ```