MIC: Add support for full OS initramfs when creating ISO/PXE artifacts (#260)

<!-- Description: Please provide a summary of the changes and the
motivation behind them. -->

---

### **Checklist**
- [x] Tests added/updated
- [x] Documentation updated (if needed)
- [x] Code conforms to style guidelines

Author: gmileka

docs/imagecustomizer/api/cli.md

@@ -60,6 +60,12 @@ The file path to write the final customized image to.
 
 Added in v0.3.
 
+## --output-path=FILE-PATH
+
+An alias to `--output-image-file`.
+
+Added in v0.15.
+
 ## --output-image-format=FORMAT
 
 Required, unless
@@ -70,7 +76,7 @@ value is used.
 
 The image format of the final customized image.
 
-Options: vhd, vhd-fixed, vhdx, qcow2, raw, iso, and [cosi](./cosi.md).
+Options: vhd, vhd-fixed, vhdx, qcow2, raw, iso, pxe-dir, pxe-tar, and [cosi](./cosi.md).
 
 The vhd-fixed option outputs a fixed size VHD image. This is the required format for
 VMs in Azure.
@@ -145,15 +151,6 @@ installation.
 
 Added in v0.3.
 
-## --output-pxe-artifacts-dir
-
-Create a folder containing the artifacts to be used for PXE booting.
-
-For an overview of Image Customizer support for PXE, see the
-[PXE support page](../concepts/pxe.md).
-
-Added in v0.8.
-
 ## --log-level=LEVEL
 
 Default: `info`
@@ -181,6 +178,7 @@ This flag enables snapshot-based package filtering during installation or update
 ensuring only packages available at that point in time are considered.
 
 Supports:
+
 - A date in `YYYY-MM-DD` format (interpreted as UTC midnight)
 - A full RFC 3339 timestamp (e.g., `2024-05-20T23:59:59Z`)
 

docs/imagecustomizer/api/cli/inject-files.md

@@ -60,13 +60,19 @@ is modified at `--image-file`.
 
 Added in v0.14.
 
+## --output-path=FILE-PATH
+
+An alias to `--output-image-file`
+
+Added in v0.15.
+
 ## --output-image-format=FORMAT
 
 Optional.
 
 The image format of the final image written to `--output-image-file`.
 
-Options: `vhd`, `vhd-fixed`, `vhdx`, `qcow2`, `raw`, `iso`, and `cosi`.
+Options: `vhd`, `vhd-fixed`, `vhdx`, `qcow2`, `raw`, `pxe-dir`, `pxe-tar`, `iso`, and `cosi`.
 
 If this option is not provided, the format of the input image is preserved.
 

docs/imagecustomizer/api/configuration.md

@@ -83,11 +83,8 @@ The top level type for the YAML file is the [config](./configuration/config.md)
 22. If a ([verity](./configuration/storage.md#verity-verity)) device is specified, then
     create the hash tree and update the grub config.
 
-23. If the output format is set to `iso`, copy additional iso media files.
-    ([iso](./configuration/iso.md))
-
-24. If [--output-pxe-artifacts-dir](./cli.md#--output-pxe-artifacts-dir) is specified,
-    then export the ISO image contents to the specified folder.
+23. If the output format is set to `iso` or `pxe`, copy additional iso media files.
+    ([iso](./configuration/iso.md) or [pxe](./configuration/pxe.md))
 
 ## /etc/resolv.conf
 
@@ -166,9 +163,19 @@ os:
         - [permissions](./configuration/additionalfile.md#permissions-string)
     - [kernelCommandLine](./configuration/iso.md#kernelcommandline-kernelcommandline) ([kernelCommandLine type](./configuration/kernelcommandline.md))
       - [extraCommandLine](./configuration/kernelcommandline.md#extracommandline-string)
+    - [initramfsType](./configuration/iso.md#initramfstype-string)
   - [pxe](./configuration/config.md#pxe-pxe) ([pxe type](./configuration/pxe.md))
-    - [isoImageBaseUrl](./configuration/pxe.md#isoimagebaseurl-string)
-    - [isoImageFileUrl](./configuration/pxe.md#isoimagefileurl-string)
+    - [additionalFiles](./configuration/pxe.md#additionalfiles-additionalfile)
+      - [additionalFile type](./configuration/additionalfile.md)
+        - [source](./configuration/additionalfile.md#source-string)
+        - [content](./configuration/additionalfile.md#content-string)
+        - [destination](./configuration/additionalfile.md#destination-string)
+        - [permissions](./configuration/additionalfile.md#permissions-string)
+    - [kernelCommandLine](./configuration/pxe.md#kernelcommandline-kernelcommandline) ([kernelCommandLine type](./configuration/kernelcommandline.md))
+      - [extraCommandLine](./configuration/kernelcommandline.md#extracommandline-string)
+    - [initramfsType](./configuration/pxe.md#initramfstype-string)
+    - [bootstrapBaseUrl](./configuration/pxe.md#bootstrapbaseurl-string)
+    - [bootstrapFileUrl](./configuration/pxe.md#bootstrapfileurl-string)
   - [os](./configuration/config.md#os-os) ([os type](./configuration/os.md))
     - [bootloader](./configuration/os.md#bootloader-bootloader) ([bootloader type](./configuration/bootloader.md))
       - [resetType](./configuration/bootloader.md#resettype-string)

docs/imagecustomizer/api/configuration/iso.md

@@ -4,7 +4,8 @@ parent: Configuration
 
 # iso type
 
-Specifies the configuration for the generated ISO media.
+Specifies the configuration for the generated ISO image when the `--output-format`
+is set to `iso`.
 
 Example:
 
@@ -17,6 +18,8 @@ iso:
   kernelCommandLine:
     extraCommandLine:
     - rd.info
+
+  initramfsType: bootstrap
 ```
 
 See also: [ISO Support](../../concepts/iso.md)
@@ -32,3 +35,28 @@ Added in v0.3.
 Adds files to the ISO.
 
 Added in v0.7.
+
+## initramfsType [string]
+
+Specifies the initramfs type to generate and include in the ISO image.
+
+Supported options:
+
+- `bootstrap`: Creates a minimal Dracut-based initramfs image that later
+  transitions to the full OS. The full OS is packaged in a separate image
+  and is included on the media. This option allows the generated ISO to boot
+  on hardware that has memory restrictions on the initramfs image size.
+- `full-os`: Creates a full OS initramfs image.
+
+The default value for `initramfsType` is `bootstrap`.
+
+Note that SELinux cannot be enabled if `initramfsType` is set to `full-os`.
+
+Example:
+
+```yaml
+iso:
+  initramfsType: full-os
+```
+
+Added in v0.15.

docs/imagecustomizer/api/configuration/pxe.md

@@ -4,76 +4,122 @@ parent: Configuration
 
 # pxe type
 
-Specifies the PXE-specific configuration for the generated OS artifacts.
+Specifies the configuration for the generated PXE artifacts when the `--output-format`
+is set to `pxe-dir` or `pxe-tar`.
 
-Added in v0.8.
+If the `--output-format` is set to `pxe-dir`, `--output-path` will point to a
+directory where the customized PXE artifacts will be placed.
 
-## isoImageBaseUrl [string]
+If the `--output-format` is set to `pxe-tar`, `--output-path` will point to a
+`.tar.gz` file where the customized PXE artifacts will be archived in.
 
-Specifies the base URL for the ISO image to download at boot time. The Azure
-Linux Image Customizer will append the output image name to the specified base
-URL to form the full URL for downloading the image. The output image name is
-specified on the command-line using the `--output-image file` argument (see the
-  [command-line interface](../cli.md) document for more details).
+Example:
 
-This can be useful if the ISO image name changes with each build and the
-script deploying the artifacts to the PXE server does not update grub.cfg with
-the ISO image name.
+```yaml
+pxe:
+  additionalFiles:
+  - source: files/a.txt
+    destination: /a.txt
 
-For example,
+  kernelCommandLine:
+    extraCommandLine:
+    - rd.info
+
+  initramfsType: bootstrap
+
+  bootstrapBaseUrl: http://my-pxe-server
+```
+
+See also the [PXE Support](../../concepts/pxe.md) page.
+
+## kernelCommandLine [[kernelCommandLine](./kernelcommandline.md)]
+
+Specifies extra kernel command line options.
+
+Added in v0.15.
+
+## additionalFiles [[additionalFile](./additionalfile.md)[]]
+
+Adds files to the PXE artifacts.
+
+Added in v0.15.
+
+## initramfsType [string]
 
-- If the user has the following content in the configuration file:
+Specifies the initramfs type to generate and include in the PXE artifacts.
 
-  ```yaml
-  pxe:
-    isoImageBaseUrl: http://hostname-or-ip/iso-publish-path
-  ```
+Supported options:
 
-- and specifies the following on the command line:
+- `bootstrap`: Creates a minimal Dracut-based initramfs image that later
+  transitions to the full OS. The full OS is packaged in a separate image
+  and is included on in the PXE artifacts folder for the initramfs to find it.
+  This option allows the generated PXE artifacts to boot on hardware that has
+  memory restrictions on the initramfs image size.
+- `full-os`: Creates a full OS initramfs image.
 
-  ```bash
-  sudo imagecustomizer \
-    --image-file "./input/azure-linux.vhdx" \
-    --config-file "./input/customization-config.yaml" \
-    --rpm-source "./input/rpms" \
-    --build-dir "./build" \
-    --output-image-format "iso" \
-    --output-image-file "./build/output/output.iso" \
-    --output-pxe-artifacts-dir "./build/output/pxe-artifacts"
-  ```
+The default value for `initramfsType` is `full-os`.
 
-- then, during PXE booting, the ISO image will be downloaded from:
+Note that SELinux cannot be enabled if `initramfsType` is set to `full-os`.
 
-  ```bash
-  http://hostname-or-ip/iso-publish-path/output.iso
-  ```
+Example:
 
-This field is mutually exclusive with `isoImageFileUrl`.
+```yaml
+pxe:
+  initramfsType: bootstrap
+```
 
-For an overview of Image Customizer support for PXE, see the 
-[PXE support page](../../concepts/pxe.md).
+For an overview of the Image Customizer tool support for PXE, see the
+[PXE support](../../concepts/pxe.md) page.
 
-Added in v0.8.
+Added in v0.15.
 
-## isoImageFileUrl [string]
+## bootstrapBaseUrl [string]
 
-Specifies the URL of the ISO image to download at boot time.
-The ISO image must be a LiveOS ISO image generated by the Azure Linux Image
-Customizer. The booting process will pivot to the root file system embedded
-in the ISO image after downloading it.
+Specifies the base URL for the bootstrap ISO image to download at boot time.
+The bootstrap ISO image is generated by the Image Customizer tool along with the
+rest of the PXE artifacts. The Image Customizer tool will append the
+default image name (`image.iso`) to the specified base URL to form the full URL
+for downloading the image.
+
+For example, if the user has the following content in the configuration file:
+
+```yaml
+pxe:
+  bootstrapBaseUrl: http://hostname-or-ip/iso-publish-path
+```
+
+Then the download URL becomes `http://hostname-or-ip/iso-publish-path/image.iso`.
+
+This field is mutually exclusive with `bootstrapFileUrl`.
+
+For an overview of the Image Customizer tool support for PXE, see the
+[PXE support](../../concepts/pxe.md) page.
+
+Added in v0.15.
+
+## bootstrapFileUrl [string]
+
+Specifies the URL of the bootstrap ISO image to download at boot time.
+The bootstrap ISO image is generated by the Image Customizer tool along with the
+rest of the PXE artifacts. The generated ISO will always be placed at the root
+of the PXE artifacts folder (archive) and will be have the same name as the file
+name specified by `bootstrapFileUrl`.
+
+For example,
 
-PXE Configuration Example:
+```yaml
+pxe:
+  bootstrapFileUrl: http://hostname-or-ip/iso-publish-path/my-bootstrap.iso
+```
 
-- ```yaml
-  pxe:
-    isoImageFileUrl: http://hostname-or-ip/iso-publish-path/my-liveos.iso
-  ```
+A file named `my-bootstrap.iso` will be placed at the root of the PXE artifacts
+folder.
 
 The supported download protocols are: nfs, http, https, ftp, torent, tftp.
 
-This field is mutually exclusive with `isoImageBaseUrl`.
+This field is mutually exclusive with `bootstrapBaseUrl`.
 
-For an overview of Image Customizer support for PXE, see the 
-[PXE support page](../../concepts/pxe.md).
+For an overview of the Image Customizer tool support for PXE, see the
+[PXE support](../../concepts/pxe.md) page.
 
-Added in v0.8.
+Added in v0.15.

docs/imagecustomizer/concepts/README.md

@@ -12,6 +12,7 @@ provides basic functionality, more comprehensive documentation is provided for t
 following scenarios:
 
 * Image History: Record the customization history of images. See [Image History](./imagehistory.md) for more info
+* Live OS: What is a Live OS? More details in [Live OS](./liveos.md)
 * ISO: Live-ISO creation. More details in [ISO Support](./iso.md)
 * PXE: Creating a PXE bootable image. More details in [PXE Support](./pxe.md)
 * Verity protected images: [Guidelines for creating a verity-protected root filesystem](./verity.md)