Skip to content

Doc consistency and release version updates (HMS-11192) #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
schuellerf merged 10 commits into from
Aug 13, 2026
Merged

Doc consistency and release version updates (HMS-11192) #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bb56f24
partitioning: add hint for btrfs limitation
schuellerf Aug 11, 2026
c5e9825
user-guide: typos
schuellerf Aug 11, 2026
2a8f642
user-guide: version updates
schuellerf Aug 11, 2026
094ce45
Update OpenSCAP documentation
schuellerf Aug 12, 2026
b57a4e3
update image builder output formats
schuellerf Aug 12, 2026
3404467
Fix whitespaces
schuellerf Aug 12, 2026
9e34b2c
use fedora 44 in the examples
schuellerf Aug 12, 2026
444412c
drop btrfs hint for custom kernel
schuellerf Aug 12, 2026
b9a757f
rephrase policy_id for clarity
schuellerf Aug 12, 2026
a20c03f
drop confusing comment on OpenSCAP "RHEL clones"
schuellerf Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 29 additions & 22 deletions docs/user-guide/00-introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,43 +23,50 @@ Customizations are specifications for the image that are not packages. This incl

### Image Builder output formats

Image Builder can create images in multiple output formats shown in the following table.
Image Builder can create images in multiple output formats shown in the following table. Availability depends on the distribution; for the full per-distro catalog (including cloud RHUI/SAP/CVM variants and Fedora desktop/atomic types), see [Image descriptions](./09-image-descriptions/index.md). Type names can differ by distribution (for example Fedora uses `generic-vagrant-libvirt` while RHEL/CentOS use `vagrant-libvirt`); always check `image-builder list` for the distro you are building.

**Table 1. Image Builder output formats**

| Name | CLI name | File extension | Description |
|-----------------------------------|:------------------------------------------------------:|----------------|------------------------------------------------------------------------------------------------------|
| QEMU Image | qcow2 | `.qcow2` | QCOW2 formatted disk image for use with QEMU/Libvirt. |
| Disk Archive | tar | `.tar` | Archive of the root filesystem without any bootloader or partition table. |
| Amazon Machine Image | ami | `.ami` | Disk image for use with AWS EC2. |
| Microsoft Azure | vhd | `.vhd` | Disk image for use with Microsoft Azure. |
| Google Cloud Platform | gce | `.tar.gz` | Disk image for use with Google Cloud Platform. |
| VMware vSphere | vmdk | `.vmdk` | VMDK formatted disk image for use with VMware vSphere. |
| VMware vSphere | ova | `.ova` | OVA formatted disk image for use with VMware vSphere. |
| Openstack | openstack | `.qcow2` | QCOW2 formatted disk image for use with OpenStack. |
| Edge/IoT[^1] Commit | edge-commit<br/>iot-commit | `.tar` | OSTree commit archive. |
| Edge/IoT[^1] Container | edge-container<br/>iot-container | `.tar` | Web server container that embeds and serves an ostree repository with the given single commit. |
| Edge/IoT[^1] Installer | edge-installer<br/>iot-installer | `.iso` | OSTree-based Anaconda installer ISO for deploying IoT images. |
| Edge/IoT[^1] Raw Image | edge-raw-image<br/>iot-raw-image | `.raw.xz` | Compressed raw disk image for OSTree-based IoT devices. |
| Edge/IoT[^1] Simplified Installer | edge-simplified-installer<br/>iot-simplified-installer | `.iso` | OSTree-based installer ISO using coreos-installer for direct disk deployment using FIDO or ignition. |
| Edge/IoT[^1] AMI | edge-ami<br/>iot-ami | `.ami` | OSTree-based Amazon Machine Image tailored for IoT deployments on AWS EC2. |
| Name | CLI name | File extension | Description |
|-----------------------------------|:------------------------------------------------------:|----------------|------------------------------------------------------------------------------------------------------|
| QEMU Image | qcow2 | `.qcow2` | QCOW2 formatted disk image for use with QEMU/Libvirt. |
| Disk Archive | tar | `.tar` | Archive of the root filesystem without any bootloader or partition table. |
| Amazon Machine Image | ami | `.ami` | Disk image for use with AWS EC2. |
| Microsoft Azure | vhd | `.vhd` | Disk image for use with Microsoft Azure. |
| Google Cloud Platform | gce | `.tar.gz` | Disk image for use with Google Cloud Platform. |
| VMware vSphere | vmdk | `.vmdk` | VMDK formatted disk image for use with VMware vSphere. |
| VMware vSphere | ova | `.ova` | OVA formatted disk image for use with VMware vSphere. |
| Openstack | openstack | `.qcow2` | QCOW2 formatted disk image for use with OpenStack. |
| Edge/IoT[^1] Commit | edge-commit<br/>iot-commit | `.tar` | OSTree commit archive. |
| Edge/IoT[^1] Container | edge-container<br/>iot-container | `.tar` | Web server container that embeds and serves an ostree repository with the given single commit. |
| Edge/IoT[^1] Installer | edge-installer<br/>iot-installer | `.iso` | OSTree-based Anaconda installer ISO for deploying IoT images. |
| Edge/IoT[^1] Raw Image | edge-raw-image<br/>iot-raw-xz | `.raw.xz` | Compressed raw disk image for OSTree-based IoT devices. |
| Edge/IoT[^1] Simplified Installer | edge-simplified-installer<br/>iot-simplified-installer | `.iso` | OSTree-based installer ISO using coreos-installer for direct disk deployment using FIDO or ignition. |
| Edge AMI | edge-ami | `.ami` | OSTree-based Amazon Machine Image tailored for IoT deployments on AWS EC2. |
| Edge vSphere | edge-vsphere | `.vmdk` | OSTree-based VMDK formatted disk image for IoT deployments on VMware vSphere. |
| Image installer | image-installer | `.iso` | Anaconda ISO with an embedded pre-built OS archive. |
| Live installer | live-installer | `.iso` | Anaconda ISO with a live operating system. |
| Oracle Cloud Infrastructure Image | oci | `.qcow2` | QCOW2 formatted disk image for use with Oracle Cloud. This is identical to the qcow2 image. |
| Image installer | image-installer | `.iso` | Anaconda ISO with an embedded pre-built OS archive. |
| Live installer | workstation-live-installer | `.iso` | Anaconda ISO with a live operating system. |
| Oracle Cloud Infrastructure Image | oci | `.qcow2` | QCOW2 formatted disk image for use with Oracle Cloud. This is identical to the qcow2 image. |
| WSL | wsl | `.wsl` | Root filesystem archive for use with Windows Subsystem for Linux. |
| Minimal raw | minimal-raw<br/>minimal-raw-xz | `.raw` / `.raw.xz` | Raw disk image (optionally xz-compressed) for bare-metal or generic virtualization. |
| PXE | pxe-tar-xz | `.tar.xz` | Kernel, initramfs, and rootfs archive for network (PXE) boot. |
| Container | container<br/>container-minimal | `.tar` | OCI container image tarball. |
| Vagrant[^2] | vagrant-libvirt<br/>vagrant-virtualbox<br/>generic-vagrant-libvirt<br/>generic-vagrant-virtualbox | `.box` | Vagrant box for libvirt or VirtualBox. |
| Network installer | network-installer | `.iso` | Anaconda network install ISO. |

To check the supported types, run the command:

Using the `image-builder` CLI:
Using the `image-builder` CLI:

```
$ image-builder list
```

Using the `composer-cli` CLI:
Using the `composer-cli` CLI:

```
$ composer-cli compose types
```

[^1]: Edge is the variant for CentOS and RHEL, while it's called IoT on Fedora. Technically the output format is the same for both.
[^2]: RHEL, CentOS, and similar use `vagrant-libvirt` / `vagrant-virtualbox`. Fedora's canonical names are `generic-vagrant-libvirt` / `generic-vagrant-virtualbox` (no short alias).
29 changes: 16 additions & 13 deletions docs/user-guide/01-blueprint-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Note that **osbuild-composer prior to version 100** didn't use a dot `.` to sepa
name = "tmux"
description = "tmux image with openssh"
version = "1.2.16"
distro = "fedora-38"
distro = "fedora-44"

[[packages]]
name = "tmux"
Expand All @@ -94,9 +94,7 @@ version = "*"
name = "tmux"
description = "tmux image with openssh"
version = "1.2.16"
# for osbuild-composer version < 100
# distro = "rhel-84"
distro = "rhel-8.4"
distro = "rhel-10.2"

[[packages]]
name = "tmux"
Expand All @@ -112,7 +110,7 @@ version = "*"
{
"image_name": "tmux",
"image_description": "tmux image with openssh",
"distribution": "fedora-38",
"distribution": "fedora-44",
"customizations": {
"packages": ["tmux", "openssh-server"]
}
Expand All @@ -123,7 +121,7 @@ version = "*"
{
"image_name": "tmux",
"image_description": "tmux image with openssh",
"distribution": "rhel-8.4",
"distribution": "rhel-10.2",
"customizations": {
"packages": ["tmux", "openssh-server"]
}
Expand Down Expand Up @@ -1366,6 +1364,9 @@ Supported modes (when the image type allows them):
- `lvm` — always LVM
- `btrfs` — always Btrfs for root (extra mountpoints become subvolumes; see [Partitioning](./07-partitioning.md))

> :warning: **Note**
> `partitioning_mode = "btrfs"` is **not supported on CentOS or RHEL** with the stock kernel. Use it on Fedora (and similar) distributions.

<Tabs values={tabValues} >
<TabItem value="on-premises" >
```toml
Expand Down Expand Up @@ -1395,7 +1396,7 @@ _See the section of the guide on [Partitioning](./07-partitioning.md) for more d

_See also the [Disk](#disk) section below for more advanced partitioning control._

The blueprints can be extended to provide filesytem support. Currently the `mountpoint` and minimum partition `minsize` can be set. On `RHEL-8`, custom mountpoints are supported only since version `8.5`. For older `RHEL` versions, only the root mountpoint, `/`, is supported, the size argument being an alias for the image size.
The blueprints can be extended to provide filesystem support. Currently the `mountpoint` and minimum partition `minsize` can be set. On `RHEL-8`, custom mountpoints are supported only since version `8.5`. For older `RHEL` versions, only the root mountpoint, `/`, is supported, the size argument being an alias for the image size.

<Tabs values={tabValuesAll} >
<TabItem value="on-premises" >
Expand Down Expand Up @@ -1485,7 +1486,7 @@ The disk customizations are an alternative to the [filesystem](#filesystems) cus

The two customizations are incompatible with each other; you may use one or the other, but not both in the same blueprint.

The examples below are illustrative but not comprehensive. The [Partitioning](./07-partitioning.md) guide should be consulted to understand all the ways in which this customization can be used.
The examples below are illustrative but not comprehensive. The [Partitioning](./07-partitioning.md) guide should be consulted to understand all the ways in which this customization can be used, including advanced GPT/DOS partition-table fields such as `part_type`, `part_label`, and `part_uuid`.

<Tabs values={tabValuesAll} >
<TabItem value="on-premises" >
Expand Down Expand Up @@ -1620,11 +1621,11 @@ The same mountpoint restrictions apply as described for [Filesystems](#filesyste

### OpenSCAP 🔵 🟤 {#openscap}

From `RHEL 8.7` & `RHEL 9.1` support has been added for `OpenSCAP` build-time remediation. The blueprints accept two fields:
- the `datastream` path to the remediation instructions (optional)
- the `profile_id` of the desired security profile
From `RHEL 8.7`, `RHEL 9.1`, and `RHEL 10` / CentOS Stream 10, support has been added for `OpenSCAP` build-time remediation. Blueprint fields:

If the datastream parameter is not provided, `osbuild-composer` will now provide a sensible default based on the selected distro.
- `datastream` — path to the remediation instructions (optional). If omitted, Image Builder / `osbuild-composer` picks a sensible default for the selected distro.
- `profile_id` — ID of the desired security profile (required for remediation).
- `policy_id` — (optional) UUID of a compliance policy. Puts the policy ID in the RHSM facts so instances registered to Insights are automatically connected to that compliance policy in the console (hosted / Insights use case; also accepted in on-premises blueprint TOML).

Please see [the OpenSCAP page](./03-oscap-remediation.md) for the list of available security profiles.

Expand All @@ -1637,14 +1638,16 @@ Building OpenSCAP hardened images for `ostree` based images not supported.
[customizations.openscap]
datastream = "/usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml"
profile_id = "xccdf_org.ssgproject.content_profile_cis"
policy_id = "00000000-0000-0000-0000-000000000000" # optional — Insights compliance policy UUID
```
</TabItem>
<TabItem value="hosted" >
```json
{
"customizations": {
"openscap": {
"profile_id": "xccdf_org.ssgproject.content_profile_cis"
"profile_id": "xccdf_org.ssgproject.content_profile_cis",
"policy_id": "00000000-0000-0000-0000-000000000000"
}
}
}
Expand Down
8 changes: 7 additions & 1 deletion docs/user-guide/02-repository-customizations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,13 @@ to use custom repositories for installing third-party packages, continue reading
## 2. Save repository configurations
In the second scenario, to make third-party repository configurations persistent and make the repositories available to users on the system, one would use the blueprint `custom repository`
configurations to enable this. The repository will be configured and saved to `/etc/yum.repos.d` as a `.repo` file. GPG keys are not imported at build time, but are imported when first
installing a third-party package from the desired repository. You can find the blueprint reference for custom repositories [here](./01-blueprint-reference.md).
installing a third-party package from the desired repository.

Blueprint schema:

- On-premises TOML: [`customizations.repositories`](./01-blueprint-reference.md#repositories)
- Hosted JSON: `custom_repositories` (same section; see the hosted tab)
- Related: optional [`customizations.dnf`](./01-blueprint-reference.md#dnf) for DNF configuration persisted on the image

## 3. Install a third-party package and save configurations
In this case it is necessary to use a combination of payload repositories and custom repositories in order to achieve the desired outcome. This will ensure that the package is installed during
Expand Down
Loading