Image Customizer configuration

The Image Customizer is configured using a YAML (or JSON) file.

Top-level

The top level type for the YAML file is the config type.

Operation ordering

1. If partitions were specified in the config, customize the disk partitions.

   Otherwise, if the resetPartitionsUuidsType value is specified, then the partitions’ UUIDs are changed.

2. Override the /etc/resolv.conf file with the version from the host OS.

3. Update packages:

   1. Remove packages (removeLists, remove)

   2. Update base image packages (updateExistingPackages).

   3. Install packages (installLists, install)

   4. Update packages (updateLists, update)

4. Update hostname. (hostname)

5. Add/update users. (users)

6. Copy additional directories. (additionalDirs)

7. Copy additional files. (additionalFiles)

8. Enable/disable services. (services)

9. Configure kernel modules. (modules)

10. Write the /etc/image-customizer-release file.

11. Write the image history file.

12. If the bootloader resetType is set to hard-reset, then reset the boot-loader.

    If the bootloader resetType is not set, then append the extraCommandLine value to the existing grub.cfg file.

13. Update the SELinux mode. mode

14. If (overlays) are specified, then add the overlay driver and update the fstab file with the overlay mount information.

15. If a (verity) device is specified, then add the dm-verity dracut driver and update the grub config.

16. Regenerate the initramfs file (if needed).

17. Run (postCustomization) scripts.

18. Restore the /etc/resolv.conf file.

19. If SELinux is enabled, call setfiles.

20. Run finalize image scripts. (finalizeCustomization)

21. If --output-image-format is cosi, then shrink the file systems.

22. If a (verity) device is specified, then create the hash tree and update the grub config.

23. If the output format is set to iso or pxe, copy additional iso media files. (iso or pxe)

/etc/resolv.conf

The /etc/resolv.conf file is overridden during customization so that the package installation and customization scripts can have access to the network.

Near the end of customization, the /etc/resolv.conf file is restored to its original state.

However, if the /etc/resolv.conf did not exist in the base image and systemd-resolved service is enabled, then the /etc/resolv.conf file is symlinked to the /run/systemd/resolve/stub-resolv.conf file. (This would happen anyway during first-boot. But doing this during customization is useful for verity enabled images where the filesystem is readonly.)

If you want to explicitly set the /etc/resolv.conf file contents, you can do so within a finalizeCustomization script, since those scripts run after the /etc/resolv.conf is deleted.

Replacing packages

If you wish to replace a package with conflicting package, then you can remove the existing package using remove and then install the new package with install.

Example:

os:
  packages:
    remove:
    - kernel

    install:
    - kernel-uvm

Schema Overview

• config type
  • input (input type)
    • image (inputImage type)
      • path
  • storage
    • bootType
    • disks (disk type)
      • partitionTableType
      • maxSize
      • partitions (partition type)
        • id
        • label
        • start
        • end
        • size
        • type
    • verity (verity type)
      • id
      • name
      • dataDeviceId
      • hashDeviceId
      • corruptionOption
    • filesystems (filesystem type)
      • deviceId
      • type
      • mountPoint (mountPoint type)
        • idType
        • options
        • path
    • resetPartitionsUuidsType
    • reinitializeVerity
  • iso (iso type)
    • additionalFiles
      • additionalFile type
        • source
        • content
        • destination
        • permissions
    • kdumpBootFiles
    • kernelCommandLine (kernelCommandLine type)
      • extraCommandLine
    • initramfsType
  • pxe (pxe type)
    • additionalFiles
      • additionalFile type
        • source
        • content
        • destination
        • permissions
    • kdumpBootFiles
    • kernelCommandLine (kernelCommandLine type)
      • extraCommandLine
    • initramfsType
    • bootstrapBaseUrl
    • bootstrapFileUrl
  • os (os type)
    • bootloader (bootloader type)
      • resetType
    • hostname
    • kernelCommandLine (kernelCommandLine type)
      • extraCommandLine
    • packages (packages type)
      • updateExistingPackages
      • installLists
      • install
      • removeLists
      • remove
      • updateLists
      • update
      • snapshotTime
    • additionalFiles (additionalFile type)
      • source
      • content
      • destination
      • permissions
    • additionalDirs (dirConfig type)
      • source
      • destination
      • newDirPermissions
      • mergedDirPermissions
      • childFilePermissions
    • groups (group type)
      • name
      • gid
    • users (user type)
      • name
      • uid
      • password (password type)
        • type
        • value
      • passwordExpiresDays
      • sshPublicKeyPaths
      • primaryGroup
      • secondaryGroups
      • startupCommand
    • selinux (selinux type)
      • mode
    • services (selinux type)
      • enable
      • disable
    • modules (module type)
      • name
      • loadMode
      • options
    • overlays (overlay type)
    • uki (uki type)
      • kernels
    • imageHistory
  • scripts (scripts type)
    • postCustomization (script type)
      • path
      • content
      • interpreter
      • arguments
      • environmentVariables
      • name
    • finalizeCustomization (script type)
      • path
      • content
      • interpreter
      • arguments
      • environmentVariables
      • name
  • previewFeatures type
  • output (output type)
    • image (outputImage type)
      • path
      • format
    • artifacts (outputArtifacts type)
      • path
      • items