Upgrading OSTree-based images¶
When you update your image and run automotive-image-builder
, the newly created image overwrites the one you previously built. However, when you
create an OSTree repo to manage images, the repo preserves each new version of your image with a unique commit ID.
In this procedure, you create unique versions of your image, publish them to an OSTree repo, and use the latest version of your OS image to perform a basic system upgrade.
Prerequisites
- Automotive Image Builder installed, see Introducing Automotive Image Builder
- An OSTree-based image, such as the image that you created in Building OSTree-based images
netcat
available on the host
Procedure
-
Include the
--publish-dir
option when you launch the image withautomotive-image-runner
to expose theostree-repo
directory from your host to the VM:Note
If you receive a message similar to
Command 'netcat' not found in path, ignoring publish-dir
, installnetcat
on your host machine and run the image again. -
After the image boots, log in as
root
using the passwordpassword
. -
Try to update the system:
# rpm-ostree upgrade 1 metadata, 0 content objects fetched; 469 B transferred in 0 seconds; 0 bytes content written No upgrade available.
The system is already running on the latest version of the branch, so no upgrades are available.
-
Update your manifest by changing the version to
1.1
and adding extra RPMs (“vim-enhanced” and “wget”) to the image: -
Build your updated image:
$ automotive-image-builder build \ --target qemu \ --mode image \ --ostree-repo <ostree-repo-name> \ --export qcow2 \ <path>/<manifest-name>.aib.yml \ <image-name>.repo
Using the
.repo
extension instead of.qcow2
indicates to OSTree that you are updating or iterating on an image rather than creating a new image. The updated image is added to the OSTree repo as a new ref with a unique commit ID. -
Run
ostree log
again to see the new commit ID and its parent commit, which form the commit history for the ref:$ ostree log --repo=<ostree-repo-name> <distro>/<architecture>/<target>-<manifest-name> commit 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee Parent: 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae ContentChecksum: 8c82a9801802d726e546bf9475f719c3760e660f8165bd034876e04aa84092d1 Date: 2025-05-06 18:28:23 +0000 Version: 1.1 (no subject) commit 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae ContentChecksum: 422d0de2ea20a009a754b699d3ca65ea7db1881bfa7c6c254258b84fa3c9ce9b Date: 2025-05-06 18:11:26 +0000 Version: 1.0 (no subject)
-
Run the image:
-
After the image boots, log in as
root
using the passwordpassword
. -
Upgrade the system to fetch updates from the OSTree repo, create a new deployment, and install the changes:
-
Check the status of the OS image deployment:
# rpm-ostree status State: idle Deployments: auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade Version: 1.1 (2025-05-06T18:28:23Z) Commit: 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee Diff: 5 added ● auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade Version: 1 (2025-05-06T18:11:26Z) Commit: 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
The
rpm-ostree status
command exposes the incremental image update located on the VM’s remote OSTree repo directory. -
Notice that the
wget
RPM you added is not found, because a reboot is required to complete the upgrade: -
Reboot the system to deploy the new version of your image:
-
After the system reboots, log in as
root
using the passwordpassword
. -
Check the status of the OS image deployment:
# rpm-ostree status State: idle Deployments: ● auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade Version: 1.1 (2025-05-06T18:28:23Z) Commit: 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade Version: 1 (2025-05-06T18:11:26Z) Commit: 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
-
Verify that the upgrade worked:
The output of the verification command shows that the upgrade was success because
wget
is available and the VM can access the OSTree repo.