diff --git a/README.md b/README.md index 95541d6..93c06a7 100644 --- a/README.md +++ b/README.md @@ -44,4 +44,4 @@ Host and Guest images are constructed in GitHub Workflows via [`mkosi`](https:// [hardware-tables]: ./docs/certifications.md#certification-levels-by-hardware [cert-definitions]: ./docs/certifications.md#certification-level-definitions - +Users who are new to create new host and guest images with mkosi tool to add new OS support can follow our guide [here](./docs/how-to-add-mkosi-images.md). diff --git a/docs/how-to-add-mkosi-images.md b/docs/how-to-add-mkosi-images.md new file mode 100644 index 0000000..687c20b --- /dev/null +++ b/docs/how-to-add-mkosi-images.md @@ -0,0 +1,128 @@ +# Create, test and publish new guest/host images + +Users can create and publish new host or guest images in sev-certify with mkosi tool in the following steps: + +- [**System Set Up:**](#system-set-up) Install mkosi on your system. +- [**Build mkosi image:**](#how-to-build-hostguest-mkosi-images) Configure mkosi config and make host/guest images in sev-certify using mksoi tool. +- [**Test Images:**](#how-to-test-hostguest-images) Launch the built host/guest images using a QEMU tool. +- [**Publish new guest/host images:**](#add-new-hostguest-mkosi-images-as-gh-artifacts) Add a new OS image in the sev-certify workflow to create GH artifacts for host/guest image + +## System Set Up +Install mkosi-v25.3 on the system to match mkosi version present in sev-certify GH project: + +- **Option 1:** Install mkosi version 25.3 directly on the supported operating systems using package manager +List of supported operating systems for mkosi version 25.3 can be tracked in the mkosi landing page [here](https://github.com/systemd/mkosi/tree/v25.3), or follow the instructions given in Option 2. +- **Option 2:** Build and install mkosi-v25.3 from the source mkosi GH repository + ``` + cd /tmp + git clone https://github.com/systemd/mkosi.git + cd mkosi + git checkout v25.3 + ``` + Install it manually since mkosi might not be in all package managers by default. + Inside the /tmp/mkosi directory, run the following: + ``` + sudo make install + ``` + Alternatively, move the mkosi script to your local bin directory: + ``` + sudo cp mkosi /usr/local/bin/ + ``` + Check if mkosi version 25.3 is installed correctly: + ``` + mkosi --version + ``` + Ensure QEMU and OVMF guest firmwares are installed to test the launch of built mkosi images on the system. + +## How to build host/guest mkosi images + +### Configure and Build new Host Image + The new host image for the sev-certify can be built using the following steps: + +1. **Create a mkosi config for the new host image:** New mkosi configuration to make new host image should be created under `sev-certify/images/host--` folder: + ``` + [Include] + # Include required modules in the host image + Include=../../modules/host + + [Distribution] + Distribution= + Release= + + [Content] + # Add required host os packages + Packages= + ``` + 2. **Build new host image using mkosi:** New guest image can be built in the system from sev-certify root directory using mkosi tool as follows: + ``` + mkosi --image-id=host-- \ + -C images/host-- build + ``` + +### Configure and Build a new Guest Image + The new guest images for the sev-certify can be built using the following steps: + +1. **Create a mkosi config for the new guest image:** New mkosi configuration for the new guest image should be created under `sev-certify/images/guest--` folder using the similar guest mkosi template: + + ``` + [Include] + # Include required modules in the guest image + Include=../../modules/guest + + [Distribution] + Distribution= + Release= + + [Content] + # Add required guest os packages + Packages= + ``` + +2. **Build new host image using mkosi:** New guest image can be built from sev-certify root directory in the system using mkosi tool as follows: + ``` + mkosi --image-id=guest-- \ + -C images/host-- build + ``` + +## How to test host/guest images + +Create launch-mkosi-image script to launch the built mkosi image using QEMU: + ``` + cat <<'EOF' > launch-mkosi-image.sh + #!/bin/bash + + # Check if a guest image is provided + if [ -z "$1" ]; then + echo "Usage: $0 [ovmf_path]" + exit 1 + fi + + guest_image="$1" + + ovmf_path="${2:-/usr/share/edk2/ovmf/OVMF_CODE.fd}" + + sudo qemu-system-x86_64 \ + -cpu EPYC-v4 \ + -nographic \ + -m 2G \ + -bios "${ovmf_path}" \ + -kernel "${guest_image}" + +EOF +``` + +Launch the built host/guest image using QEMU on the QEMU enabled KVM hypervisor host: + ``` + bash launch-mkosi-image.sh + ``` + +## Add new host/guest mkosi images as GH Artifacts + Once the launch of host/guest images works, users can release these new images to the GH artifacts by adding the new OS release support to the distro matrix in the build-and-release.yml workflow under the sev-certify/.github/workflows: + ``` + - distro: + release: + ``` + +## References +- PR to add Ubuntu 25.04 Support into the sev-certify project is present in this [link](https://github.com/AMDEPYC/sev-certify/pull/222) +