MIC: Add support for full OS initramfs. 2

docs/imagecustomizer/api/cli.md

@@ -60,6 +60,16 @@ The file path to write the final customized image to.
 
 Added in v0.3.
 
+If the `--output-format` is set to `pxe`, this can be set to either:
+- a directory where the customized PXE artifacts will be placed.
+- a `.tar.gz` file name where the PXE artifacts will be compressed and stored.
+
+## --output-path=FILE-PATH
+
+An alias to `--output-image-file`
+
+Added in v0.15.
+
 ## --output-image-format=FORMAT
 
 Required, unless
@@ -70,7 +80,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, 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 +155,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`

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

@@ -60,6 +60,12 @@ 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.

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,9 +18,11 @@ iso:
   kernelCommandLine:
     extraCommandLine:
     - rd.info
+
+  initramfsType: bootstrap
 ```
 
-See also: [ISO Support](../../concepts/iso.md)
+See also the [ISO Support](../../concepts/iso.md) page.
 
 ## kernelCommandLine [[kernelCommandLine](./kernelcommandline.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 is `initramfsType` value 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,116 @@ 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`.
 
-Added in v0.8.
+Note that when the `--output-format` is set to `pxe`, `--output-image-file` can
+be set to either:
+- a directory where the customized PXE artifacts will be placed.
+- a `.tar.gz` file name where the PXE artifacts will be compressed and stored.
 
-## isoImageBaseUrl [string]
+Example:
 
-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).
+```yaml
+pxe:
+  additionalFiles:
+  - source: files/a.txt
+    destination: /a.txt
 
-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.
+  kernelCommandLine:
+    extraCommandLine:
+    - rd.info
 
-For example,
+  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.
 
-- If the user has the following content in the configuration file:
+## initramfsType [string]
 
-  ```yaml
-  pxe:
-    isoImageBaseUrl: http://hostname-or-ip/iso-publish-path
-  ```
+Specifies the initramfs type to generate and include in the PXE artifacts.
 
-- and specifies the following on the command line:
+Supported options:
 
-  ```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"
-  ```
+- `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.
 
-- then, during PXE booting, the ISO image will be downloaded from:
+The default is `initramfsType` value is `full-os`.
 
-  ```bash
-  http://hostname-or-ip/iso-publish-path/output.iso
-  ```
+Note that SELinux cannot be enabled if `initramfsType` is set to `full-os`.
 
-This field is mutually exclusive with `isoImageFileUrl`.
+Example:
+
+```yaml
+pxe:
+  initramfsType: bootstrap
+```
+
+Added in v0.15.
+
+## bootstrapBaseUrl [string]
+
+Specifies the base URL for the bootstrap ISO image to download at boot time.
+The bootstrap ISO image is generated by the Image Customizer along with the
+rest of the PXE artifacts. The Azure Linux Image Customizer 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 Image Customizer support for PXE, see the 
-[PXE support page](../../concepts/pxe.md).
+[PXE support](../../concepts/pxe.md) page.
 
-Added in v0.8.
+Added in v0.15.
 
-## isoImageFileUrl [string]
+## bootstrapFileUrl [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 URL of the bootstrap ISO image to download at boot time.
+The bootstrap ISO image is generated by the Image Customizer 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`.
 
-PXE Configuration Example:
+For 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).
+[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)