s390x: Add documentation for buildextend-secex

Document both possible paths for buildextend-secex.
Add secex to buildextend-metal artifacts.

Signed-off-by: Jan Schintag <[email protected]>
Co-authored-by: Silke Niemann <[email protected]>

cmd/remote-session.go

@@ -138,6 +138,9 @@ func runCreate(c *cobra.Command, args []string) error {
 		"--pull=always", "--privileged", "--security-opt=label=disable",
 		"--volume", remoteSessionOpts.CreateWorkdir,
 		"--workdir", remoteSessionOpts.CreateWorkdir,
+		// Mount required volume for buildextend-secex, it will be empty on
+		// non-s390x builders.
+		// See: https://github.com/coreos/coreos-assembler/blob/main/docs/cosa/buildextend-secex.md
 		"--volume=secex-data:/data.secex:ro",
 		"--uidmap=1000:0:1", "--uidmap=0:1:1000", "--uidmap=1001:1001:64536",
 		"--device=/dev/kvm", "--device=/dev/fuse", "--tmpfs=/tmp",

docs/cosa.md

@@ -42,7 +42,7 @@ other platforms or cloud providers:
 | Name | Description |
 | ---- | ----------- |
 | [buildextend-live](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-live) | Generate the Live ISO
-| [buildextend-{dasd,metal,metal4k,qemu}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-metal) | Generate artifacts for the given platforms
+| [buildextend-{dasd,metal,metal4k,qemu,secex}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-metal) | Generate artifacts for the given platforms
 | [buildextend-{aliyun,aws,azure,digitalocean,exoscale,gcp,vultr}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-ore-wrapper) | Generate artifacts for the given platforms
 | [buildextend-{azurestack,ibmcloud,openstack,vmware}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-artifact-disk) | Generate artifacts for the given platforms
 | [{aliyun,aws}-replicate](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-ore-wrapper) | Replicate images on the platforms (AMIs for AWS)

docs/cosa/buildextend-secex.md

@@ -0,0 +1,43 @@
+---
+parent: CoreOS Assembler Command Line Reference
+nav_order: 1
+---
+
+# cosa buildextend-secex
+
+This buildextend command is used to build QEMU images that are enabled for IBM Secure Execution on IBM Z.
+In order to build a QEMU image protected by IBM Secure Execution, you need to provide a host key to encrypt it.
+
+For more information on IBM Secure Execution on IBM Z, refer to the [IBM Documentation](https://www.ibm.com/docs/en/linux-on-systems?topic=ibmz-secure-execution).
+
+The command is intended to be used in the RHCOS CI together with the universal host key, such that the image can be booted on any IBM Z machine that supports IBM Secure Execution.
+This results in a few specifics to note:
+- The resulting image will only be encrypted with a single host key, to enable firstboot.
+- The host key will not be written to the image.
+- The host key(s) need to be provided later during firstboot through Ignition.
+    - The firstboot service will fail when no host key is provided, as the sdboot-image can not be recreated.
+    - Write the host key(s) to: `/etc/se-hostkeys/ibm-z-hostkey-<hostkey-name>.crt`
+
+To facilitate this, `buildextend-secex` can take 2 mutually exclusive additional arguments: `--genprotimgvm <path>` and `--hostkey <path>`.
+If none is provided, `--genprotimgvm` is used with default values.
+
+## `--genprotimgvm <path>` (default)
+
+Default Value: `/data.secex/genprotimgvm.qcow2`
+
+This path is the default behavior. It assumes that the host key is not directly available, but is supplied through an IBM Secure Execution protected VM only.
+
+The QEMU image will be built normally. However, it will not run `genprotimg` or `zipl`, but instead save the required input for the command to a temporary location.
+After the build, the provided VM will run.  The VM is used to isolate and protect the `genprotimg` command, so that the universal host key is not exposed.
+A provided bash script is called before and after the `genprotimg` command, to fullfil the following steps:
+1. Copy the required kernel, initramfs, and parmfile to the VM
+2. Move the sdboot-image to the disk
+3. Call `zipl`to make the image bootable.
+This enables us to copy the required kernel, initramfs and parmfile to the VM and afterwards move the sdboot-image to the disk, as well as calling `zipl` to make the image bootable.
+
+## `--hostkey <path>`
+
+This path is intended for local development, but can be used for custom builds. The path takes a singe host key file, which is used to build the image.
+
+Instead of running `genprotimg` and `zipl` in a separate VM, they run during the build process. Otherwise, the build is identical to the `--genprotimgvm`.
+Note: It is still assumed that the host key is provided via Ignition during firstboot.