docs: Guide to add new mkosi images for new OS support in sev-certify… #235
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
|
||
| - [<u>**System Set Up:**</u>](#system-set-up) Install mkosi on your system. | ||
| - [<u>**Build mkosi image:**</u>](#how-to-build-hostguest-mkosi-images) Configure mkosi config and make host/guest images in sev-certify using mksoi tool. | ||
| - [<u>**Test Images:**</u>](#how-to-test-hostguest-images) Launch the built host/guest images using a QEMU tool. | ||
| - [<u>**Publish new guest/host images:**</u>](#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 | ||
|
There was a problem hiding this comment. What do we do when we move to a new version of mkosi? Will we update the docs or something else? There was a problem hiding this comment. Also - add a period (.) after the word "manager".
Contributor
Author
There was a problem hiding this comment.
As per the current
Sure, I can update the docs in future if there is any update in mkosi version.
Contributor
There was a problem hiding this comment. Would prefer not having to update manually, can we just rely on asking the user to check that link for the latest ubuntu version? |
||
| 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 | ||
|
There was a problem hiding this comment. You should show what the expected output is from the at command so that users can validate that it matches what they see. |
||
| ``` | ||
| Ensure QEMU and OVMF guest firmwares are installed to test the launch of built mkosi images on the system. | ||
|
There was a problem hiding this comment. Are there instructions some place for how the user can validate this?
Contributor
Author
There was a problem hiding this comment. Sure, I can add additional lines to validate this |
||
|
|
||
| ## 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-<new-os-name>-<new-os-release>` folder: | ||
|
There was a problem hiding this comment. I'd reword
Contributor
Author
There was a problem hiding this comment. Sure, I will update this with the filename. |
||
| ``` | ||
| [Include] | ||
| # Include required modules in the host image | ||
| Include=../../modules/host | ||
|
There was a problem hiding this comment. In the preview all of the configuration details show as underlined. Not sure if that's just a preview issue with the markdown or some other formatting issue?
Contributor
There was a problem hiding this comment. https://github.com/LakshmiSaiHarika/snpcert/blob/mkosi-doc-add-new-images/docs/how-to-add-mkosi-images.md |
||
|
|
||
| [Distribution] | ||
| Distribution=<new-distro> | ||
| Release=<new-os-release> | ||
|
|
||
| [Content] | ||
| # Add required host os packages | ||
| Packages= <add-host-os-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: | ||
|
There was a problem hiding this comment. The heading here is to build a new host image, but the sub-heading refers to building a new guest image. Is that on purpose?
Contributor
Author
There was a problem hiding this comment. Thank you so much for catching this point, it is a typo here. |
||
| ``` | ||
| mkosi --image-id=host-<new-distro>-<new-release> \ | ||
|
Contributor
There was a problem hiding this comment. not sure if other people have run into this often, but on ubuntu there are permission errors out of the box related to apparmor, documented here: systemd/mkosi#3265. Can run |
||
| -C images/host-<new-distro>-<new-release> 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-<new-os-name>-<new-os-release>` folder using the similar guest mkosi template: | ||
|
|
||
| ``` | ||
| [Include] | ||
| # Include required modules in the guest image | ||
| Include=../../modules/guest | ||
|
|
||
| [Distribution] | ||
| Distribution=<new-os-distro> | ||
| Release=<new-os-release> | ||
|
|
||
| [Content] | ||
| # Add required guest os packages | ||
| Packages= <add-guest-os-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-<new-distro>-<new-release> \ | ||
| -C images/host-<new-distro>-<new-release> 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 <guest_image> [ovmf_path]" | ||
| exit 1 | ||
| fi | ||
|
|
||
| guest_image="$1" | ||
|
|
||
| ovmf_path="${2:-/usr/share/edk2/ovmf/OVMF_CODE.fd}" | ||
|
Contributor
There was a problem hiding this comment. I would mention somewhere the other common ovmf path -
Contributor
Author
There was a problem hiding this comment.
Are we just testing builthost/guest-mkosi-images using simple guest launch?
Contributor
There was a problem hiding this comment. ah I see, I didn't realize that was the case, that's probably my other issue. My install didn't come with that version, will try to find it.
Contributor
There was a problem hiding this comment. Ok on ubuntu it appears to be at: |
||
|
|
||
| sudo qemu-system-x86_64 \ | ||
| -cpu EPYC-v4 \ | ||
| -nographic \ | ||
| -m 2G \ | ||
| -bios "${ovmf_path}" \ | ||
| -kernel "${guest_image}" | ||
|
Contributor
There was a problem hiding this comment. this qemu command fails to find the image for me on my ubuntu dev server: If I add all the sev parameters it starts working for guest images for me.
Contributor
There was a problem hiding this comment. host images appears to fail with some resources issue - tried giving it 16G memory but still got the same error. Not sure if this is some issue with my configuration or ubuntu.
Contributor
There was a problem hiding this comment. as mentioned earlier, this was b/c I was using the sev-enabled firmware. But even with the non-sev firmware, host image is still not booting for me:
Contributor
Author
There was a problem hiding this comment. Ok, on my dev box, the host image took a little longer boot time compared to the guest image, but later comes up with a login page. |
||
|
|
||
| EOF | ||
| ``` | ||
|
|
||
| Launch the built host/guest image using QEMU on the QEMU enabled KVM hypervisor host: | ||
|
|
||
| ``` | ||
| bash launch-mkosi-image.sh <built-mkosi-host-guest-image.efi file path> | ||
| ``` | ||
|
|
||
| ## 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: <new-distro> | ||
| release: <new-os-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) | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would it make sense to mention that this is for new OS support, as in the PR title?