Document supported blueprint customizations on image description pages (HMS-11019)

Makefile

@@ -11,6 +11,7 @@ help:
 test: ## test pulling the readmes from the other projects
 	cd scripts
 	python3 test_pull_readmes.py
+	python3 test_pull_image_descriptions.py
 
 .PHONY: pull-readmes
 pull-readmes: ## pull the readmes from other projects given in `readme-list`
@@ -29,26 +30,26 @@ pull-osbuild-modules: ## pull the documentation of the osbuild modules
 	python3 scripts/pull_osbuild_modules.py
 
 # Pull image descriptions for subset of supported distributions
-# Documentation is generated in docs/user-guide/09-image-definitions/
+# Documentation is generated in docs/user-guide/09-image-descriptions/
 # This generates documentation for:
-# - Fedora 41+
-# - Latest RHEL-10 GA version - 10.0
-# - Latest RHEL-9 GA version - 9.6
+# - Fedora 42+
+# - Latest RHEL-10 GA version - 10.2
+# - Latest RHEL-9 GA version - 9.8
 # - Latest RHEL-8 GA version - 8.10
 # - All CentOS Stream versions
-# - All AlmaLinux versions
+# - Selected AlmaLinux / Rocky versions
 .PHONY: pull-image-descriptions
 pull-image-descriptions:
 	python3 scripts/pull_image_descriptions.py \
 		--distro-filter "fedora-4[2-4]" \
-		--distro-filter "rhel-(10.1|9.7|8.10)" \
+		--distro-filter "rhel-(10.2|9.8|8.10)" \
 		--distro-filter "rocky-(10.1|9.7|8.10)" \
 		--distro-filter "centos-*" \
 		--distro-filter "almalinux-(10.1|9.7|8.10)" \
 		--distro-filter "almalinux_kitten-*"
 
 .PHONY: generate
-generate: pull-readmes pull-osbuild-modules pull-image-descriptions ## generate all external content
+generate: pull-readmes pull-image-builder pull-koji-image-builder pull-osbuild-modules pull-image-descriptions ## generate all external content
 
 .PHONY: install-dependencies
 install-dependencies: ## install all dependencies

docs/user-guide/01-blueprint-reference.md

@@ -16,7 +16,13 @@ Not all customizations are supported in the API but those existing, are highligh
 
 Additionally, there is <Highlight colorVar="bootc">🟣&nbsp;bootc</Highlight> which is supposed to be used from within podman desktop.
 
-> An important thing to note is that these customizations are not applicable to all image types. `osbuild-composer` currently has no good validation or warning system in place to tell you if a customization in your blueprint is not supported for the image type you're building. The customization may be silently dropped.
+:::note[Not every customization applies to every image type]
+Which blueprint fields are accepted depends on the image type. Image Builder
+validates blueprints against per-type `supported_options` from the image
+definitions (see [`image-builder describe`](../developer-guide/02-projects/image-builder/01-usage.md#image-builder-describe)).
+Each [image description](./09-image-descriptions/index.md) page lists the supported
+blueprint customizations for that image type.
+:::
 
 A very basic blueprint with just the required attributes at the root looks like:
 

docs/user-guide/09-image-descriptions/00-rhel-10.1/ami.md → docs/user-guide/09-image-descriptions/00-rhel-10.2/ami.md

@@ -7,14 +7,50 @@ custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/
 <!--
 [//]: # ( DO NOT MODIFY THIS FILE! )
 [//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
-[//]: # ( Generated on: 2026-07-30 09:34:54 UTC )
+[//]: # ( Generated on: 2026-07-30 11:44:58 UTC )
 -->
 
-Image description for **ami** on **Red Hat Enterprise Linux 10.1**.
+Image description for **ami** on **Red Hat Enterprise Linux 10.2**.
 
 The descriptions below describe the base image version,
 that can be further customized by the user using the [Blueprint customizations](../../01-blueprint-reference.md).
 
+## Supported blueprint customizations
+
+Blueprint fields accepted for this image type (from [`image-builder describe`](../../../developer-guide/02-projects/image-builder/01-usage.md#image-builder-describe)). See the [Blueprint Reference](../../01-blueprint-reference.md) for syntax and examples. The metadata fields `name`, `version`, and `description` are always accepted and omitted below.
+
+**Supported options:**
+
+- [`containers`](../../01-blueprint-reference.md#containers)
+- `customizations.cacerts`
+- [`customizations.directories`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.disk`](../../01-blueprint-reference.md#disk)
+- `customizations.dnf`
+- [`customizations.files`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.filesystem`](../../01-blueprint-reference.md#filesystems)
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.firewall`](../../01-blueprint-reference.md#firewall)
+- `customizations.firstboot`
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.hostname`](../../01-blueprint-reference.md#hostname)
+- [`customizations.kernel`](../../01-blueprint-reference.md#kernel)
+- [`customizations.locale`](../../01-blueprint-reference.md#locale)
+- [`customizations.openscap`](../../01-blueprint-reference.md#openscap)
+- [`customizations.partitioning_mode`](../../01-blueprint-reference.md#partitioning-mode)
+- [`customizations.repositories`](../../01-blueprint-reference.md#repositories)
+- [`customizations.rhsm`](../../01-blueprint-reference.md#rhsm)
+- [`customizations.rpm`](../../01-blueprint-reference.md#rpm)
+- [`customizations.services`](../../01-blueprint-reference.md#systemd-services)
+- `customizations.sshd`
+- [`customizations.sshkey`](../../01-blueprint-reference.md#ssh-keys)
+- [`customizations.timezone`](../../01-blueprint-reference.md#timezone)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+- [`distro`](../../01-blueprint-reference.md#distribution-selection-with-blueprints)
+- [`enabled_modules`](../../01-blueprint-reference.md#packages)
+- [`groups`](../../01-blueprint-reference.md#groups)
+- [`modules`](../../01-blueprint-reference.md#packages)
+- [`packages`](../../01-blueprint-reference.md#packages)
+
 :::note[Package sets]
 
 Each image description contains a list of base packages that make up the image.
@@ -38,10 +74,10 @@ The format of the image description is not guaranteed to be stable. It is publis
 ## aarch64 {#aarch64}
 
 ```yaml
-distro: rhel-10.1
+distro: rhel-10.2
 type: ami
 arch: aarch64
-os_version: "10.1"
+os_version: "10.2"
 bootmode: uefi
 partition_type: gpt
 default_filename: image.raw
@@ -181,10 +217,10 @@ blueprint:
 ## x86_64 {#x86-64}
 
 ```yaml
-distro: rhel-10.1
+distro: rhel-10.2
 type: ami
 arch: x86_64
-os_version: "10.1"
+os_version: "10.2"
 bootmode: hybrid
 partition_type: gpt
 default_filename: image.raw
@@ -329,4 +365,4 @@ blueprint:
 ---
 *Generated using: `ghcr.io/osbuild/image-builder-cli:latest@sha256:f78aec12d5272ab1aff66426ea9501fba0b3b02632bcd7b798b77ac1cd3d7ca5`*
 
-*Last updated on: 2026-07-30 09:34:54 UTC*
+*Last updated on: 2026-07-30 11:44:58 UTC*

docs/user-guide/09-image-descriptions/00-rhel-10.1/azure-cvm.md → docs/user-guide/09-image-descriptions/00-rhel-10.2/azure-cvm.md

@@ -7,14 +7,48 @@ custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/
 <!--
 [//]: # ( DO NOT MODIFY THIS FILE! )
 [//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
-[//]: # ( Generated on: 2026-07-30 09:34:54 UTC )
+[//]: # ( Generated on: 2026-07-30 11:44:58 UTC )
 -->
 
-Image description for **azure-cvm** on **Red Hat Enterprise Linux 10.1**.
+Image description for **azure-cvm** on **Red Hat Enterprise Linux 10.2**.
 
 The descriptions below describe the base image version,
 that can be further customized by the user using the [Blueprint customizations](../../01-blueprint-reference.md).
 
+## Supported blueprint customizations
+
+Blueprint fields accepted for this image type (from [`image-builder describe`](../../../developer-guide/02-projects/image-builder/01-usage.md#image-builder-describe)). See the [Blueprint Reference](../../01-blueprint-reference.md) for syntax and examples. The metadata fields `name`, `version`, and `description` are always accepted and omitted below.
+
+**Supported options:**
+
+- [`containers`](../../01-blueprint-reference.md#containers)
+- `customizations.cacerts`
+- [`customizations.directories`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.disk`](../../01-blueprint-reference.md#disk)
+- `customizations.dnf`
+- [`customizations.files`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.filesystem`](../../01-blueprint-reference.md#filesystems)
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.firewall`](../../01-blueprint-reference.md#firewall)
+- `customizations.firstboot`
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.hostname`](../../01-blueprint-reference.md#hostname)
+- [`customizations.locale`](../../01-blueprint-reference.md#locale)
+- [`customizations.openscap`](../../01-blueprint-reference.md#openscap)
+- [`customizations.partitioning_mode`](../../01-blueprint-reference.md#partitioning-mode)
+- [`customizations.repositories`](../../01-blueprint-reference.md#repositories)
+- [`customizations.rhsm`](../../01-blueprint-reference.md#rhsm)
+- [`customizations.rpm`](../../01-blueprint-reference.md#rpm)
+- [`customizations.services`](../../01-blueprint-reference.md#systemd-services)
+- [`customizations.sshkey`](../../01-blueprint-reference.md#ssh-keys)
+- [`customizations.timezone`](../../01-blueprint-reference.md#timezone)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+- [`distro`](../../01-blueprint-reference.md#distribution-selection-with-blueprints)
+- [`enabled_modules`](../../01-blueprint-reference.md#packages)
+- [`groups`](../../01-blueprint-reference.md#groups)
+- [`modules`](../../01-blueprint-reference.md#packages)
+- [`packages`](../../01-blueprint-reference.md#packages)
+
 :::note[Package sets]
 
 Each image description contains a list of base packages that make up the image.
@@ -33,10 +67,10 @@ The format of the image description is not guaranteed to be stable. It is publis
 ## x86_64 {#x86-64}
 
 ```yaml
-distro: rhel-10.1
+distro: rhel-10.2
 type: azure-cvm
 arch: x86_64
-os_version: "10.1"
+os_version: "10.2"
 bootmode: uefi
 partition_type: gpt
 default_filename: disk.vhd.xz
@@ -71,6 +105,7 @@ packages:
       - NetworkManager
       - NetworkManager-cloud-setup
       - WALinuxAgent
+      - azure-vm-utils
       - bzip2
       - cloud-init
       - cloud-utils-growpart
@@ -114,6 +149,7 @@ packages:
       - grub2-tools
       - grub2-tools-minimal
       - grubby
+      - initscripts-rename-device
       - iprutils
       - ivtv-firmware
       - iwl100-firmware
@@ -205,4 +241,4 @@ blueprint:
 ---
 *Generated using: `ghcr.io/osbuild/image-builder-cli:latest@sha256:f78aec12d5272ab1aff66426ea9501fba0b3b02632bcd7b798b77ac1cd3d7ca5`*
 
-*Last updated on: 2026-07-30 09:34:54 UTC*
+*Last updated on: 2026-07-30 11:44:58 UTC*

docs/user-guide/09-image-descriptions/00-rhel-10.1/azure-rhui.md → docs/user-guide/09-image-descriptions/00-rhel-10.2/azure-rhui.md

@@ -7,14 +7,50 @@ custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/
 <!--
 [//]: # ( DO NOT MODIFY THIS FILE! )
 [//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
-[//]: # ( Generated on: 2026-07-30 09:34:54 UTC )
+[//]: # ( Generated on: 2026-07-30 11:44:58 UTC )
 -->
 
-Image description for **azure-rhui** on **Red Hat Enterprise Linux 10.1**.
+Image description for **azure-rhui** on **Red Hat Enterprise Linux 10.2**.
 
 The descriptions below describe the base image version,
 that can be further customized by the user using the [Blueprint customizations](../../01-blueprint-reference.md).
 
+## Supported blueprint customizations
+
+Blueprint fields accepted for this image type (from [`image-builder describe`](../../../developer-guide/02-projects/image-builder/01-usage.md#image-builder-describe)). See the [Blueprint Reference](../../01-blueprint-reference.md) for syntax and examples. The metadata fields `name`, `version`, and `description` are always accepted and omitted below.
+
+**Supported options:**
+
+- [`containers`](../../01-blueprint-reference.md#containers)
+- `customizations.cacerts`
+- [`customizations.directories`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.disk`](../../01-blueprint-reference.md#disk)
+- `customizations.dnf`
+- [`customizations.files`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.filesystem`](../../01-blueprint-reference.md#filesystems)
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.firewall`](../../01-blueprint-reference.md#firewall)
+- `customizations.firstboot`
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.hostname`](../../01-blueprint-reference.md#hostname)
+- [`customizations.kernel`](../../01-blueprint-reference.md#kernel)
+- [`customizations.locale`](../../01-blueprint-reference.md#locale)
+- [`customizations.openscap`](../../01-blueprint-reference.md#openscap)
+- [`customizations.partitioning_mode`](../../01-blueprint-reference.md#partitioning-mode)
+- [`customizations.repositories`](../../01-blueprint-reference.md#repositories)
+- [`customizations.rhsm`](../../01-blueprint-reference.md#rhsm)
+- [`customizations.rpm`](../../01-blueprint-reference.md#rpm)
+- [`customizations.services`](../../01-blueprint-reference.md#systemd-services)
+- `customizations.sshd`
+- [`customizations.sshkey`](../../01-blueprint-reference.md#ssh-keys)
+- [`customizations.timezone`](../../01-blueprint-reference.md#timezone)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+- [`distro`](../../01-blueprint-reference.md#distribution-selection-with-blueprints)
+- [`enabled_modules`](../../01-blueprint-reference.md#packages)
+- [`groups`](../../01-blueprint-reference.md#groups)
+- [`modules`](../../01-blueprint-reference.md#packages)
+- [`packages`](../../01-blueprint-reference.md#packages)
+
 :::note[Package sets]
 
 Each image description contains a list of base packages that make up the image.
@@ -38,10 +74,10 @@ The format of the image description is not guaranteed to be stable. It is publis
 ## aarch64 {#aarch64}
 
 ```yaml
-distro: rhel-10.1
+distro: rhel-10.2
 type: azure-rhui
 arch: aarch64
-os_version: "10.1"
+os_version: "10.2"
 bootmode: uefi
 partition_type: gpt
 default_filename: disk.vhd.xz
@@ -76,6 +112,7 @@ packages:
       - NetworkManager
       - NetworkManager-cloud-setup
       - WALinuxAgent
+      - azure-vm-utils
       - bzip2
       - chrony
       - cloud-init
@@ -115,6 +152,7 @@ packages:
       - dnf-plugin-spacewalk
       - dracut-config-rescue
       - glibc-all-langpacks
+      - initscripts-rename-device
       - iprutils
       - ivtv-firmware
       - iwl100-firmware
@@ -245,10 +283,10 @@ blueprint:
 ## x86_64 {#x86-64}
 
 ```yaml
-distro: rhel-10.1
+distro: rhel-10.2
 type: azure-rhui
 arch: x86_64
-os_version: "10.1"
+os_version: "10.2"
 bootmode: hybrid
 partition_type: gpt
 default_filename: disk.vhd.xz
@@ -284,6 +322,7 @@ packages:
       - NetworkManager
       - NetworkManager-cloud-setup
       - WALinuxAgent
+      - azure-vm-utils
       - bzip2
       - chrony
       - cloud-init
@@ -324,6 +363,7 @@ packages:
       - dnf-plugin-spacewalk
       - dracut-config-rescue
       - glibc-all-langpacks
+      - initscripts-rename-device
       - iprutils
       - ivtv-firmware
       - iwl100-firmware
@@ -458,4 +498,4 @@ blueprint:
 ---
 *Generated using: `ghcr.io/osbuild/image-builder-cli:latest@sha256:f78aec12d5272ab1aff66426ea9501fba0b3b02632bcd7b798b77ac1cd3d7ca5`*
 
-*Last updated on: 2026-07-30 09:34:54 UTC*
+*Last updated on: 2026-07-30 11:44:58 UTC*