Skip to content

Latest commit

 

History

History
138 lines (110 loc) · 5.59 KB

iso.md

File metadata and controls

138 lines (110 loc) · 5.59 KB

Azure Linux Image Customizer ISO Support

Overview

The Azure Linux Image Customizer can customize an input image and package the output as a LiveOS iso image. The input image can be a full disk image (vhd/vhdx/qcow2/raw) or another LiveOS iso image. The LiveOS iso output format is specified by setting the --output-image-format command line parameter to iso.

The LiveOS iso image is a bootable image that boots into a rootfs image included on the iso media without the need to have anything pre-installed on the target machine. The rootfs is kept read-only and an overlay in memory is created so that processes can successfully write state.

Customizations are made to the input rootfs as usual using the Azure Linux Image Customizer, and will naturally carry over into the LiveOS iso image. This includes customizations for kernel modules, dracut, and other early boot-time actions.

While converting the input full disk image into a LiveOS iso involves copying almost all the artifacts unchanged - some artifacts are changed as follows:

  • grub.cfg is modified by updating the kernel command-line arguments as follows:
    • the root is updated to the LiveOS root file system image.
    • the LiveOS dracut parameters are appended.
    • the user-specified new parameters are appended.
    • SELinux is disabled.
  • /etc/fstab is dropped from the rootfs as it typically conflicts with the overlay setup required by the LiveOS.
  • initrd.img is regenerated to serve the LiveOS boot flow. This should have no impact as long as the included rootfs is where the original initrd.img was generated using dracut. The use of such rootfs guarantees that the same dracut configuration that got used before will be re-used again when we are re-generating the initrd.img and hence the original behavior is retained.

The current implementation for the LiveOS iso does not support the following:

  • persistent storage.
    • The machine loses all its state on reboot or shutdown.
  • dm-verity.
    • The iso image cannot run dm-verity for the LiveOS partitions.
  • disk layout.
    • There is always one disk generated when an iso output format is specified.
  • SELinux
    • No SELinux configuration is supported for the generated iso image.
  • non-"Azure Linux toolkit" images
    • images generated by tools other than the Azure Linux toolkit may fail to be converted to a LiveOS iso. This is due to certain assumptions on the input image layout that may not be satisfied. See the section titled "Input Image Layout Assumptions" for more details.

ISO Specific Customizations

  • The user can specify one or more files to be copied to the iso media.
  • The user can add kernel parameters.

For a full list of capabilities, see Azure Linux Image Customizer's iso configuration section: Config.ISO.

cloud-init Support

In some user scenarios, it desired to embed the cloud-init data files into the iso media. The easiest way is to include the data files on the media, and then the cloud-init ds kernel parameter to where the files are.

The files can be placed directly within the iso file system or they can be placed within the LiveOS root file system.

Placing those files directly on the iso file system will allow a more efficient replacement flow in the future (i.e. when it is desired to only replace the cloud-init data files).

Example 1

If cloud-init data is to be placed directly within the iso file system:

scripts:
  postCustomization:
  - content: |
      set -e
      mkdir -p /var/lib/cloud/seed/
      ln -s -T /run/initramfs/live/cloud-init-data /var/lib/cloud/seed/nocloud 

iso:
  additionalFiles:
    cloud-init-data/user-data: /cloud-init-data/user-data
    cloud-init-data/network-config: /cloud-init-data/network-config
    cloud-init-data/meta-data: /cloud-init-data/meta-data

  kernelCommandLine:
    extraCommandLine: "ds=nocloud"

Note: It is tempting to specify extraCommandLine: "'ds=nocloud;seedfrom=file://run/initramfs/live/cloud-init-data'", instead of using a symbolic link. But cloud-init ignores the network-config file when you use seedfrom. See, cloud-init issue #3307.

Example 2

If cloud-init data is to be placed within the LiveOS root file system:

os:
  kernelCommandLine:
    extraCommandLine: "ds=nocloud"

  additionalFiles:
    cloud-init-data/user-data: /var/lib/cloud/seed/nocloud/user-data
    cloud-init-data/network-config: /var/lib/cloud/seed/nocloud/network-config
    cloud-init-data/meta-data: /var/lib/cloud/seed/nocloud/meta-data

Input Image Layout Assumptions

Full Disk Image

The input full disk image must satisfy the following requirements in order for the Azure Linux Image Cuztomizer to be able to generate an iso image out of it:

  • File layout (after all partitions have been mounted):
    • /boot/grub2/grub.cfg must exist and is the 'main' grub configuration (not a redirection grub configuration file for example).
    • The bootloader and the shim must exist under the /boot folder or any of its subdirectories.
      • For x64, bootx64.efi and grubx64.efi (or grubx64-noprefix.efi).
      • For ARM64, bootaa64.efi and grubaa64.efi (or grubaa64-noprefix.efi).
    • All grub configurations and related files must be stored under the /boot folder. For example, grub.cfg cannot reference files outside that folder. If it does, those referenced files will not be copied to the iso and may cause grub to fail booting the desired operating system.

LiveOS ISO Image

The input LiveOS iso image must be previously generated by the Azure Linux Image Customizer.