Document bootc customizations (RHEL-238209)

Makefile

@@ -17,7 +17,8 @@ test: ## test pulling the readmes from the other projects
 	python3 test_pull_image_descriptions.py
 
 .PHONY: generate
-generate: pull-readmes pull-image-builder pull-koji-image-builder pull-osbuild-modules pull-image-descriptions ## generate all external content (PULL_IMAGE_DESCRIPTIONS_JOBS=N for parallel describe)
+generate: pull-readmes pull-image-builder pull-koji-image-builder pull-osbuild-modules pull-image-descriptions ## generate all external content (package mode + bootc / image mode; PULL_IMAGE_DESCRIPTIONS_JOBS=N)
+
 
 .PHONY: install-dependencies
 install-dependencies: ## install all dependencies
@@ -73,18 +74,26 @@ pull-osbuild-modules: ## pull the documentation of the osbuild modules
 # Pull image descriptions for subset of supported distributions
 # Documentation is generated in docs/user-guide/09-image-descriptions/
 # This generates documentation for:
+# - Bootc (from bootc-generic/imagetypes.yaml; see README)
 # - 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
 # - Selected AlmaLinux / Rocky versions
+# Optional: BOOTC_IMAGETYPES=/path/to/imagetypes.yaml
 .PHONY: pull-image-descriptions
-pull-image-descriptions: ## pull image descriptions (PULL_IMAGE_DESCRIPTIONS_JOBS=N for parallel describe)
+pull-image-descriptions: ## pull image descriptions incl. bootc (PULL_IMAGE_DESCRIPTIONS_JOBS=N; optional BOOTC_IMAGETYPES=)
 	python3 scripts/pull_image_descriptions.py \
+		$(if $(BOOTC_IMAGETYPES),--bootc-imagetypes "$(BOOTC_IMAGETYPES)",) \
 		--distro-filter "fedora-4[2-4]" \
 		--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: pull-bootc-image-descriptions
+pull-bootc-image-descriptions: ## regenerate bootc 09 pages only (needs BOOTC_IMAGETYPES or fetches from GitHub)
+	python3 scripts/pull_image_descriptions.py --bootc-only \
+		$(if $(BOOTC_IMAGETYPES),--bootc-imagetypes "$(BOOTC_IMAGETYPES)",)

README.md

@@ -39,3 +39,26 @@ When using relative links, please make sure they are path-based, and not URL-bas
 ```
 
 This follows Docusaurus' guidance, see [their docs](https://docusaurus.io/docs/markdown-features/links) for more information.
+
+### Generated image descriptions (package mode + bootc / image mode)
+
+`docs/user-guide/09-image-descriptions/` is **generated** — do not hand-edit those pages.
+
+```bash
+make generate                    # all external content, including image descriptions
+make pull-image-descriptions     # package-mode distros + bootc only
+# bootc-only (no CLI container / describe):
+make pull-bootc-image-descriptions
+# or:
+python3 scripts/pull_image_descriptions.py --bootc-only \
+  --bootc-imagetypes /path/to/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml
+```
+
+**Freshness depends on upstream Image Builder being up to date:**
+
+| Path | Source |
+|------|--------|
+| Package mode | [`ghcr.io/osbuild/image-builder-cli:latest`](https://github.com/osbuild/image-builder/pkgs/container/image-builder-cli) via `list-images` + `describe` (`CONTAINER_IMAGE` in `scripts/pull_image_descriptions.py`). Pull the image before regenerating or docs lag. |
+| Image mode (bootc) | [`data/distrodefs/bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder) (same project that builds the CLI image; distrodefs are `go:embed`’d, so not loose files inside the container). Pass `--bootc-imagetypes` / `BOOTC_IMAGETYPES`, or the script fetches from `main` on GitHub. |
+
+**CI:** [`.github/workflows/pull.yml`](.github/workflows/pull.yml) does **not** call `make generate` by name, but it runs `make pull-image-descriptions` (after installing podman). That target regenerates package-mode pages **and** bootc (`00-bootc/`), then `git add .` commits any drift — so bootc docs update **implicitly** on the daily schedule / workflow_dispatch.

docs/user-guide/09-image-descriptions/00-bootc/ami.md

@@ -0,0 +1,57 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# ami
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Bootc **artifact** image type **ami**.
+
+The bootable container is an **input**; Image Builder turns it into this output artifact.
+Customize via a blueprint / `config.toml` using only the options listed below
+(see [Blueprint Reference](../../01-blueprint-reference.md)).
+
+:::note[`raw` and `ami` are identical]
+
+`raw` and `ami` are identical for bootc (same definition in [imagetypes.yaml](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml)); `ami` is an alias of `raw`. See also [`raw`](./raw.md).
+
+:::
+
+## Supported blueprint customizations
+
+Blueprint fields accepted for this bootc image type (from [`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder)). 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:**
+
+- [`customizations.bootloader`](../../01-blueprint-reference.md#bootloader)
+- [`customizations.directories`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.disk`](../../01-blueprint-reference.md#disk)
+- [`customizations.files`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.ignition`](../../01-blueprint-reference.md#ignition)
+- [`customizations.kernel.append`](../../01-blueprint-reference.md#kernel)
+- [`customizations.sshd`](../../01-blueprint-reference.md#sshd)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+
+:::note[Container input, not package sets]
+
+Bootc images are built from a container reference (`--bootc-ref`), not from a distribution
+RPM base package set. Package content comes from the container image itself.
+
+:::
+
+:::warning[Do not rely on the image description format]
+
+The format of these pages is not guaranteed to be stable. It is published for informational purposes only.
+
+:::
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*

docs/user-guide/09-image-descriptions/00-bootc/anaconda-iso.md

@@ -0,0 +1,53 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# anaconda-iso
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Bootc **artifact** image type **anaconda-iso**.
+
+The bootable container is an **input**; Image Builder turns it into this output artifact.
+Customize via a blueprint / `config.toml` using only the options listed below
+(see [Blueprint Reference](../../01-blueprint-reference.md)).
+
+:::warning[Compatibility image type]
+
+`anaconda-iso` is kept for compatibility with older bootc-image-builder workflows and is on its way out. Prefer `bootc-generic-iso` or `bootc-installer` for new ISO work.
+
+:::
+
+## Supported blueprint customizations
+
+Blueprint fields accepted for this bootc image type (from [`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder)). 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:**
+
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.installer`](../../01-blueprint-reference.md#installer)
+- [`customizations.kernel.append`](../../01-blueprint-reference.md#kernel)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+
+:::note[Container input, not package sets]
+
+Bootc images are built from a container reference (`--bootc-ref`), not from a distribution
+RPM base package set. Package content comes from the container image itself.
+
+:::
+
+:::warning[Do not rely on the image description format]
+
+The format of these pages is not guaranteed to be stable. It is published for informational purposes only.
+
+:::
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*

docs/user-guide/09-image-descriptions/00-bootc/bootc-generic-iso.md

@@ -0,0 +1,47 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# bootc-generic-iso
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Bootc **artifact** image type **bootc-generic-iso**.
+
+The bootable container is an **input**; Image Builder turns it into this output artifact.
+Customize via a blueprint / `config.toml` using only the options listed below
+(see [Blueprint Reference](../../01-blueprint-reference.md)).
+
+## Supported blueprint customizations
+
+Blueprint fields accepted for this bootc image type (from [`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder)). 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:**
+
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.installer`](../../01-blueprint-reference.md#installer)
+- [`customizations.kernel.append`](../../01-blueprint-reference.md#kernel)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+
+:::note[Container input, not package sets]
+
+Bootc images are built from a container reference (`--bootc-ref`), not from a distribution
+RPM base package set. Package content comes from the container image itself.
+
+:::
+
+:::warning[Do not rely on the image description format]
+
+The format of these pages is not guaranteed to be stable. It is published for informational purposes only.
+
+:::
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*

docs/user-guide/09-image-descriptions/00-bootc/bootc-installer.md

@@ -0,0 +1,47 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# bootc-installer
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Bootc **artifact** image type **bootc-installer**.
+
+The bootable container is an **input**; Image Builder turns it into this output artifact.
+Customize via a blueprint / `config.toml` using only the options listed below
+(see [Blueprint Reference](../../01-blueprint-reference.md)).
+
+## Supported blueprint customizations
+
+Blueprint fields accepted for this bootc image type (from [`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder)). 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:**
+
+- [`customizations.fips`](../../01-blueprint-reference.md#fips)
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.installer`](../../01-blueprint-reference.md#installer)
+- [`customizations.kernel.append`](../../01-blueprint-reference.md#kernel)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+
+:::note[Container input, not package sets]
+
+Bootc images are built from a container reference (`--bootc-ref`), not from a distribution
+RPM base package set. Package content comes from the container image itself.
+
+:::
+
+:::warning[Do not rely on the image description format]
+
+The format of these pages is not guaranteed to be stable. It is published for informational purposes only.
+
+:::
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*

docs/user-guide/09-image-descriptions/00-bootc/gce.md

@@ -0,0 +1,51 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# gce
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Bootc **artifact** image type **gce**.
+
+The bootable container is an **input**; Image Builder turns it into this output artifact.
+Customize via a blueprint / `config.toml` using only the options listed below
+(see [Blueprint Reference](../../01-blueprint-reference.md)).
+
+## Supported blueprint customizations
+
+Blueprint fields accepted for this bootc image type (from [`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml) in [osbuild/image-builder](https://github.com/osbuild/image-builder)). 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:**
+
+- [`customizations.bootloader`](../../01-blueprint-reference.md#bootloader)
+- [`customizations.directories`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.disk`](../../01-blueprint-reference.md#disk)
+- [`customizations.files`](../../01-blueprint-reference.md#files-and-directories)
+- [`customizations.group`](../../01-blueprint-reference.md#additional-groups)
+- [`customizations.ignition`](../../01-blueprint-reference.md#ignition)
+- [`customizations.kernel.append`](../../01-blueprint-reference.md#kernel)
+- [`customizations.sshd`](../../01-blueprint-reference.md#sshd)
+- [`customizations.user`](../../01-blueprint-reference.md#additional-users)
+
+:::note[Container input, not package sets]
+
+Bootc images are built from a container reference (`--bootc-ref`), not from a distribution
+RPM base package set. Package content comes from the container image itself.
+
+:::
+
+:::warning[Do not rely on the image description format]
+
+The format of these pages is not guaranteed to be stable. It is published for informational purposes only.
+
+:::
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*

docs/user-guide/09-image-descriptions/00-bootc/index.md

@@ -0,0 +1,38 @@
+---
+custom_edit_url: https://github.com/osbuild/osbuild.github.io/blob/main/scripts/pull_image_descriptions.py
+---
+
+# Bootc
+
+<!--
+[//]: # ( DO NOT MODIFY THIS FILE! )
+[//]: # ( This content is generated by `scripts/pull_image_descriptions.py` )
+[//]: # ( Generated on: 2026-08-17 10:08:26 UTC )
+-->
+
+Image types for **bootc** builds (container input → disk/ISO/PXE artifact).
+
+These types are **not** tied to a Fedora/RHEL distro id. Allowlists come from
+[`bootc-generic/imagetypes.yaml`](https://github.com/osbuild/image-builder/blob/main/data/distrodefs/bootc-generic/imagetypes.yaml).
+
+## Image Types
+
+- [ami](./ami.md)
+- [anaconda-iso](./anaconda-iso.md)
+- [bootc-generic-iso](./bootc-generic-iso.md)
+- [bootc-installer](./bootc-installer.md)
+- [gce](./gce.md)
+- [iso](./iso.md)
+- [oci](./oci.md)
+- [ova](./ova.md)
+- [pxe-tar-xz](./pxe-tar-xz.md)
+- [qcow2](./qcow2.md)
+- [raw](./raw.md)
+- [vhd](./vhd.md)
+- [vmdk](./vmdk.md)
+
+
+---
+*Generated using: `github.com/osbuild/image-builder/data/distrodefs/bootc-generic/imagetypes.yaml`*
+
+*Last updated on: 2026-08-17 10:08:26 UTC*