v1.4.0

Breaking changes

None

Breaking changes for preview features

None

New preview features

• Azure Container Linux 3.0 support: Add customization support under the azure-container-linux-3 preview feature, including qcow2, raw, vhd-fixed, vhd, and vhdx output formats; and input.image.path, os.hostname, os.kernelCommandLine, os.additionalFiles, os.additionalDirs, os.groups, os.users, os.modules, os.services, os.uki, os.selinux, os.imageHistory, scripts, output.image, and output.artifacts config API endpoints.

New features

• Azure Linux 4.0 support: Add customization support for all CLI commands and configuration endpoints as stable APIs, except the iso, pxe-dir, and pxe-tar output formats and their iso and pxe config API counterparts; and the customize --package-snapshot-time CLI flag and its os.packages.snapshotTime config API counterpart.
• Single-partition verity: Add support for placing the data and hash tree on the same partition.
• Expanded mkfs.btrfs support: Add support for v6.17.1 through v6.19.1.

Bug fixes

• UKI addon .cmdline is no longer silently truncated: Build UKI addons with systemd's addonx64.efi.stub instead of linuxx64.efi.stub, so systemd versions with a large linuxx64.efi.stub file do not silently cause truncated .cmdline sections.
• Verity reinit no longer drops format settings: Carry over the original verity format settings when reinitializing verity.
• setfiles no longer skipped on SELinux-enabled images: On Fedora, Azure Linux 3.0+, and other distributions where SELinux is loaded by default, fall back to /etc/selinux/config to determine mode when selinux= and enforcing= are absent from the kernel command line, instead of assuming SELinux is disabled.
• Stale or wrong packages no longer silently installed: Force skip_if_unavailable=False for dnf and tdnf so package operations fail loudly on repo metadata errors instead of silently skipping unreachable repos.
• Boot no longer fails on XFS: Use cp --sparse=auto instead of --sparse=always when repartitioning, so legitimate zero runs in vmlinuz aren't converted to sparse holes (which GRUB can't read on XFS).
• Kernel cmdline updates no longer fail on images without GRUB_CMDLINE_LINUX: Treat the variable as empty instead of erroring when it's missing from /etc/default/grub.
• output.artifacts.items rejects uki-addons value: Now errors on uki-addons, which was previously accepted but had no effect.

Doc fixes and improvements

• Edit-on-GitHub links: Add an "Edit this page on GitHub" link to every doc page, so readers can jump straight to the source markdown to propose improvements.

Links

Official docs: Image Customizer
Version docs: README.md
Commit: db5bef62ad3768d4f814d42727959d9893581a63
Branch: release/v1.4
Container:

• MCR: mcr.microsoft.com/azurelinux/imagecustomizer:1.4
• GHCR: ghcr.io/microsoft/imagecustomizer:1.4.0

v1.3.0

Breaking changes

None

Breaking changes for preview features

• In .output.artifacts.items API, remove the systemd-boot option and add the bootloader option.

New preview features

• Ubuntu support for removing and updating packages

New features

• Add option to output logs in JSON format (--log-format json).

Bug fixes

• During partition discovery, don't try to read kernel cmdline unless it is actually needed.
• Ensure that the partitions have a consistent ordering in a COSI file.
• Fix command path lookup of script's 'interpreter' value.
• Gracefully handle Azure data disks.
• Lots of fixes for hierarchical configs:
  • Report an error when .storage is specified in a base config.
  • Validate the .os values in the base configs.
  • Ensure packages installLists, removeLists, and updateLists are used from base configs.
  • Merge the .os.imageHistory enum from base configs.
  • Ensure base configs .os.kernelCommandLine is used when bootloader is hard-reset.
  • Run the .scripts from base configs.
• Make sure "Success!" log happens at the very end.
• When creating UKIs, don't create the /boot/efi/EFI/systemd/systemd-bootx64.efi file.
• For inject-files, create build directory if it doesn't exist.
• Trim filesystems after OS customization. For some scenarios, this can substantially reduce the size of a disk.

Doc fixes and improvements

• Remove stale references to cosi-compression preview feature.
• Add missing create, kdump-boot-files, and fedora-42 preview features previews.
• Breakout output image formats in distro support documentation.

v1.2.0

Breaking changes

None

Breaking changes for preview features

• The UKI API has changed. .os.uki.kernels was removed and .os.uki.mode was added.
• If you want to leave an existing UKI from the base image, you must now explicitly specify .os.uki.mode=passthrough.
• Kernel command-line args are now placed in a UKI addon instead of the main UKI file.

New preview features

• You can now control the COSI zstd compression level using the .output.image.cosi.compression.level API.
• Expanded hierarchical configs API to include ISO and PXE.
• Added support for btrfs filesystem, including creating subvolumnes and setting quotas.
• Added create subcommand for creating OS images from scratch.
• Added UKI mode of modify for modifying the kernel args through a UKI addon.
• Added initial support for customizing Ubuntu cloud images. Many features are not yet implemented.

New features

• Added support for COSI v1.2.
• Added convert subcommand, for converting OS images without customizing them. This is useful for creating fixed-sized VHDs and creating COSI images.
• Added validate-config subcommand.

Bug fixes

• Fixed boot failures when using the .storage.verity[].hashSignaturePath API.

Doc fixes and improvements

• Fixed a bunch of spelling and grammar issues.
• Fixed example for .output.image API.
• Gave the customize subcommand its own page.
• Cleaned up output image formats docs.
• Call out the need to specify --image-cache-dir when using the OCI APIs.

v1.1.0

Breaking changes

None

Breaking changes for preview features

• When inject-files outputs to COSI, the non-verity filesystems will be shrunk.
• The output artifacts behavior and the inject-files config API has changed:
  • unsignedSource has been removed from inject-files.yaml. Instead, the unsigned and signed file paths are now the same.
  • Unsigned files are now placed in <artifacts-dir>/<artifact-type>/<file> (previously <artifacts-dir>/<file>).
    • For example: ./artifacts/ukis/vmlinuz-6.6.96.2-2.azl3.efi instead of ./artifacts/vmlinuz-6.6.96.2-2.azl3.efi.
  • A new type field has been added to inject-files.yaml.

New preview features

• Partial support has been added for Hierarchical Configs.
  • This feature is still a work in progress. It is not recommended for use yet.
  • Currently implemented features: .os.services, .os.packages, .os.users, .os.groups, .os.additionalFiles, .os.modules, .input.image, .output.image, .output.artifacts, .os.overlays, .os.selinux, .os.bootLoader, .os.uki, .os.kernelCommandLine.
• Added API for downloading base images from an OCI artifact (oras).
• Added API for downloading Azure Linux base images from MCR.
• Added partial support for customizing Fedora 42 images.
  • This feature is still a work in progress. It is not recommended for use yet.
• Added support for customizing base images that have a rootfs formatted as btrfs.
  • Creating new partition layouts with btrfs partitions is not supported yet.
• Added API for extracting SELinux policy from image during customization.

Bug fixes

• For Azure Linux 3.0, don't enable the nrext64 feature on an /boot partitions formatted with xfs since GRUB 2.06 doesn't support that feature.
• Remove requirement for having a /boot partition when /usr verity is used.
• Bump golang.org/x/crypto from v0.41.0 to v0.45.0.
• Be more resilient when the user changes the /etc/fstab file during custom scripts.

Doc fixes and improvements

• Fixed typo in Things to avoid page.
• Added details on the format of ISO files generated by Image Customizer.
• Fix example in the user type page.

v1.0.0

Breaking changes

None

Breaking changes for preview features

None

New features

• Added ukify command to ARM64 container.

Bug fixes

• Fix grub2-mkconfig log level.
• Improve some error messages, including when a non-disk file is passed as the input image.

Doc fixes and improvements

None

v0.19.0

Notices

• This is the second release candidate for v1.

Breaking changes

• The /tmp directory is now mounted as tmpfs during customization.
• The file paths in the container have changed:
  • imagecustomizer: /usr/bin/imagecustomizer
  • run.sh: /usr/lib/imagecustomizer/run.sh
  • entrypoint.sh: /usr/lib/imagecustomizer/entrypoint.sh

Breaking changes for preview features

None

New features

None

Bug fixes

None

Doc fixes and improvements

None

v0.18.0

Notices

This will likely be the last release before v1.

Breaking changes

• Reject VHDs (i.e. vpc) images made with qemu-img where the force_size=on option was omitted.
• When calling the container, the name of the program (imagecustomizer) no longer needs to be specified.
  • If you are using run.sh, then you should pass --entrypoint /usr/local/bin/run.sh to docker.

Breaking changes for preview features

None

New features

• Telemetry now collects error names.

Bug fixes

• Fix UKI stub path for ARM64.
• Fix failure when producing COSI images with overlays added.

Doc fixes and improvements

None

v0.17.0

Breaking changes

None

Breaking changes for preview features

• When customizing a base image with existing verity partitions, the verity partitions will be read-only during customization by default.
  • Set reinitializeVerity to all to recustomize verity partitions.

New features

• Added the reinitializeVerity API that controls whether existing verity partitions can be recustomized.

Bug fixes

• Added support for --help CLI arg in container's run.sh script.
• Modifying an existing user will no longer remove the user's password.

Doc fixes and improvements

• Added docs regarding telemetry collection.

v0.16.0

Breaking changes

• When generating UKI images, the /boot directory is no longer emptied.
  • This enables recustomizing UKI images.
• Do not include efiboot.img file in PXE image output.
• UKI EFI files no longer have .unsigned or .signed in the name.
  • This means that signed images will no longer have both an unsigned and signed version of the UKI files.
• Don't copy SSH public key files specified through sshPublicKeyPaths into the .ssh directory. Instead, only append the keys to the authorized_keys file.
• Adding/updating users now happens before additionalFiles and additionalDirs are processed.

New features

• Added telemetry that tracks timing, success/fail, etc.
  • Use --disable-telemetry CLI flag to disable upload.
• For PXE/ISO, added initramfsType API that that can enable storing the full OS in the initramfs, instead of having a separate squashfs.
• Added support for the COSI v1.1 image format.
• The inject-files sub-command now supports outputting COSI images.
• Added verity-hash as an artifact output type, to support verity hash signing.
• PXE and ISO image output now supports having multiple kernels installed.
• For ISO/PXE image output, add kdumpBootFiles flag that allows keeping kernel files within the OS image for use with kdump.
• Added API for adding user groups.

Bug fixes

• Do not require efibootmgr package when UKI is used.
• Do not require lvm2 package when verity is used and instead require device-mapper package.
• Do not apply noexec mount flag while customizing. Flag will still be included in the /etc/fstab file.
• Add pre-validation that the sshPublicKeyPaths files exist.
• Fix the permissions of the .ssh directory and its files.

Doc fixes and improvements

• Docs for primaryGroup has been clarified and expanded.

v0.15.0

Breaking changes

• Enable GPG checking for package installation by default.
  • GPG checking can be explicitly disabled in .repo files passed to --rpm-source. GPG checking is also disabled for directories.
• Don't copy extended file ACLs for additionalFiles, etc.

New features

• Add support for reinitializing verity. (Reading verity settings from base image and reapplying them.)
• Add support for specifying package snapshot time.

Bug fixes

• Remove unnecessary/duplicate files from ISO.
• Ensure no files are left in build directory.
• Ensure correct UUID is used when verity hashDeviceMountIdType or hashDeviceMountIdType is set to uuid.
• Don't overwrite shim EFI when UKIs are configured.

Doc fixes and improvements

• Remove deprecated doc: "Partition Metadata JSON Format"