first draft of the testing guide (#24)

suse-edge · Oct 30, 2023 · 700bd5d · 700bd5d
1 parent bc64192
commit 700bd5d
Show file tree

Hide file tree

Showing 15 changed files with 187 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -12,31 +12,88 @@ podman build -t eib:dev .
 
 ## Running
 
-At runtime, a volume must be mounted to the container. This serves as both the mechanism to introduce image
-configuration files and provide a way to get the built image out of the container and onto the host machine.
-
 **NOTE:** These docs are incomplete and will be fleshed out as the project matures. Below is an example that
 is being used for dev purposes. At some point when it's more mature, an example configuration directory will be
 added to this repository.
 
-Example image configuration directory:
+### Image Definition
+
+Two things are necessary to build an image using EIB:
+1. A configuration file that describes the image to build
+1. A directory that contains the base SLE Micro image to modify, along with any other custom files that
+   will be included in the built image
+
+#### Image Configuration File
+
+The image configuration file is a YAML document describing a single image to build. The file is specified using
+the `-config-file` argument. Only a single image may be built at a time, however the same image configuration
+directory may be used to build multiple images by creating multiple configuration files.
+
+The following can be used as the minimum configuration required to create an image:
+```yaml
+apiVersion: 1.0
+image:
+  imageType: iso
+  baseImage: SLE-Micro.x86_64-5.5.0-Default-SelfInstall-GM.install.iso
+  outputImageName: eib-image.iso
+```
+
+* `imageType` - Must be either `iso` or `raw`.
+* `baseImage` - Indicates the name of the image file used as the base for the built image. This file must be located
+  under the `images` directory of the image configuration directory (see below for more information). This image will
+  **not** directly be modified by EIB; a new image will be created each time EIB is run.
+* `outputImageName` - Indicates the name of the image that EIB will build. This may only be a filename; the image will
+  be written to the root of the image configuration directory.
+
+#### Image Configuration Directory
+
+The image configuration directory contains all the files necessary for EIB to build an image. As the project matures,
+the structure of this directory will be better fleshed out. For now, the required structure is described below:
+
 ```shell
 .
-├── eib-config.yaml
+├── eib-config-iso.yaml
+├── eib-config-raw.yaml
 └── images
     └── SLE-Micro.x86_64-5.5.0-Default-SelfInstall-GM.install.iso
+    └── SLE-Micro.x86_64-5.5.0-Default-GM.raw
 ```
 
-That directory must be attached to the container at runtime. The following command attaches the directory and runs
-EIB against the volume (replace `$IMAGE_DIR` with your local configuration directory):
+* `eib-config-iso.yaml`, `eib-config-raw.yaml` - All image configuration files should be in the root of the image 
+  configuration directory. Multiple configuration files may be included in a single configuration directory, with 
+  the specific configuration file specified as a CLI argument as described above.
+* `images` - This directory must exist and contains the base images from which EIB will build customized images. There
+  are no restrictions on the naming; the image configuration file will specify which image in this directory to use
+  for a particular build.
+
+### Running EIB
+
+The image configuration directory must be attached to the container at runtime. This serves as both the mechanism
+to introduce image configuration files and provide a way to get the built image out of the container and onto
+the host machine. 
+
+The following example command attaches the directory and runs EIB:
 ```shell
 podman run --rm -it \
 -v $IMAGE_DIR:/eib eib:dev /bin/eib \
--config-file /eib/eib-config.yaml \
+-config-file /eib/$CONFIG_FILE.yaml \
 -config-dir /eib \
 -build-dir /eib/_build
 ```
 
-The command above will write all build artifacts (such as the combustion directory) under the image configuration
-directory at `_build`. This likely won't be the default behavior and was included in the above example to ease
-debugging.
+* `-v` - Used to mount a local directory (in this example, the value of $IMAGE_DIR) into the EIB container at `/eib`.
+* `-config-file` - Specifies which image configuration file to build. **Note:** This is currently the full path to the 
+  file relative to inside the container. In this example, since the volume was mounted at `/eib`, that path information
+  needs to be included in the CLI argument.
+* `-config-dir` - Specifies the image configuration directory. Keep in mind that this is relative to the running
+  container, so its value must match the mounted volume.
+* `-build-dir` - (optional) If unspecified, EIB will use a temporary directory inside the container for
+  assembling/generating the components used in the build. This may be specified to a location within the mounted
+  volume to make the build artifacts available after the container completes. In this example, a directory named
+  `_build` will be created in the image configuration directory and will persist after EIB finished. If it already
+  exists, EIB will delete this directory at the start of a build, meaning it does not need to manually be cleaned up
+  between builds.
+
+## Testing Images
+
+For details on how to test the built images, see the [Testing Guide](docs/testing-guide.md).
diff --git a/docs/images/general-1.png b/docs/images/general-1.png
diff --git a/docs/images/libvirt-iso-1.png b/docs/images/libvirt-iso-1.png
diff --git a/docs/images/libvirt-iso-10.png b/docs/images/libvirt-iso-10.png
diff --git a/docs/images/libvirt-iso-11.png b/docs/images/libvirt-iso-11.png
diff --git a/docs/images/libvirt-iso-2.png b/docs/images/libvirt-iso-2.png
diff --git a/docs/images/libvirt-iso-3.png b/docs/images/libvirt-iso-3.png
diff --git a/docs/images/libvirt-iso-4.png b/docs/images/libvirt-iso-4.png
diff --git a/docs/images/libvirt-iso-5.png b/docs/images/libvirt-iso-5.png
diff --git a/docs/images/libvirt-iso-6.png b/docs/images/libvirt-iso-6.png
diff --git a/docs/images/libvirt-iso-7.png b/docs/images/libvirt-iso-7.png
diff --git a/docs/images/libvirt-iso-8.png b/docs/images/libvirt-iso-8.png
diff --git a/docs/images/libvirt-raw-1.png b/docs/images/libvirt-raw-1.png
diff --git a/docs/images/libvirt-raw-2.png b/docs/images/libvirt-raw-2.png
diff --git a/docs/testing-guide.md b/docs/testing-guide.md
@@ -0,0 +1,119 @@
+# Testing Built Images
+
+Images may be run on either bare metal or through virtualization. The following guide provides examples to speed
+development and testing.
+
+[libvirt](https://libvirt.org/) is a commonly available virtualization toolkit. Much of the development of EIB
+has been tested against libvirt running on an [openSUSE Tumbleweed](https://get.opensuse.org/tumbleweed/)
+installation. Other hypervisors may be used, but this guide will cover the specifics of libvirt in particular.
+
+## Testing Self-installing ISOs
+
+If you're already familiar with using libvirt to create images installed from ISOs, you can skip to the section
+about [resetting the VM between tests](#Resetting-the-VM-for-Self-install-ISO-Testing ).
+
+> :warning: libvirt may automatically remove the installation media after the first boot. Upon reboot, the installation
+> ISO, and more importantly its embedded combustion configuration, will not be present and combustion won't run. If
+> the JeOS installer begins, the first step in debugging should be to ensure the installation media is still present
+> after the initial installation writes the SLE Micro raw image to disk.
+
+Using Virtual Machine Manager, select the option to create a new VM. 
+
+Select the "Local install media (ISO image or CDROM)" option:
+
+![image](./images/libvirt-iso-1.png)
+
+Browse to the ISO built by EIB. If Virtual Machine Manager is unable to detect the operating system, type `slem5.5`
+to search for the "SUSE Linux Enterprise Micro 5.5" version:
+
+![images](./images/libvirt-iso-2.png)
+
+Enter the memory and CPU settings as appropriate for your host:
+
+![images](./images/libvirt-iso-3.png)
+
+Ensure "Enable storage for this virtual machine" is selected and enter an image size:
+
+![images](./images/libvirt-iso-4.png)
+
+Name the VM and select Finish:
+
+![images](./images/libvirt-iso-5.png)
+
+After pressing "Finish", the VM will boot. Depending on the version of the SLE Micro self-install ISO, it may
+prompt you to manually select the "Install SLE Micro" option before proceeding. In either case, stop the installation
+by using the "Shutdown -> Force Off" option under the "Virtual Machine" menu. See the next step for more information
+on what needs to happen before the installation can continue.
+
+![images](./images/libvirt-iso-6.png)
+
+Under the "View" menu, select the "Details" item. Select the "CDROM" entry on the left. If the value of "Source path"
+says "No media selected", use the "Browse" button to navigate to your ISO built by EIB. Once it is selected, press
+"Apply".
+
+![images](./images/libvirt-iso-7.png)
+
+Select the "Boot Options" entry on the left. Ensure that the "CDROM" entry is checked and press "Apply".
+
+![images](./images/libvirt-iso-8.png)
+
+Once those two configuration values have been set, navigate back to the "Console" option under "View" and power on
+the VM. If prompted, select the "Install SLE Micro" menu item and press "Yes" when prompted to delete all data on
+`/dev/vda`. The installation will then copy the SLE Micro raw image to the VM disk and reboot. Upon reboot,
+combustion should trigger and the JeOS installer should *not* appear.
+
+After combustion runs, the VM will display a message indicating it's been configured by the Edge Image Builder and
+a login screen will be shown.
+
+![images](./images/libvirt-iso-10.png)
+
+### Resetting the VM for Self-install ISO Testing 
+
+To save time, the process above does not need to be repeated for each installation. Instead, the storage file for the
+VM can be recreated, causing the installer ISO to act as if it is a fresh installation on a new disk. The path to
+the disk image file can be found under the "Details" section of the VM.
+
+![images](./images/libvirt-iso-11.png)
+
+The image can be recreated between ISO installs using `qemu-img` (make sure the VM is powered off):
+
+```bash
+qemu-img create -f qcow2 ~/.local/share/libvirt/images/eib-iso.qcow2 20G
+```
+
+The next time the VM is powered on, it will trigger the ISO installer.
+
+## Testing RAW Images
+
+Using Virtual Machine Manager, select the option to create a new VM.
+
+Select the "Import existing disk image" option:
+
+![images](./images/libvirt-raw-1.png)
+
+Navigate to the raw image built by EIB and set the OS to "SUSE Linux Enterprise Micro 5.5"
+(or type `slem5.5`):
+
+![images](./images/libvirt-raw-2.png)
+
+Continue through the creation wizard, adjusting the defaults as necessary.
+
+Once the VM is configured, simply power it on to boot into the raw image. Similar to the self-install ISO instructions,
+the JeOS installer should not appear. Instead, combustion should take over the installation and the VM will boot
+into a login screen. A message will display indicating it's been configured by the Edge Image Builder.
+
+![images](./images/libvirt-iso-10.png)
+
+### Resetting the VM for RAW Image Testing
+
+Unlike the installer ISO, there isn't anything specific that needs to be done when testing multiple iterations of
+a raw image. EIB can be used to overwrite the raw image attached to a VM and, when the VM is booted, it will use
+the newly built image.
+
+## General Notes
+
+The following messages do not indicate an issue with the installation ISO. Combustion will still look inside
+the ISO itself for the combustion configuration.
+
+![images](./images/general-1.png)
+