Skip to content

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

Procedure

  1. Include the --publish-dir option when you launch the image with automotive-image-runner to expose the ostree-repo directory from your host to the VM:

    $ automotive-image-runner --publish-dir=<ostree-repo-name> <image-name>.qcow2

    Note

    If you receive a message similar to Command 'netcat' not found in path, ignoring publish-dir, install netcat on your host machine and run the image again.

  2. After the image boots, log in as root using the password password.

  3. 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.

  4. Update your manifest by changing the version to 1.1 and adding extra RPMs (“vim-enhanced” and “wget”) to the image:

    automotive image builder manifest
      rpms:
    - podman
    - vim-enhanced
    - wget

  5. 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.

  6. 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)

  7. Run the image:

    $ automotive-image-runner --publish-dir=<ostree-repo-name> <image-name>.qcow2

  8. After the image boots, log in as root using the password password.

  9. Upgrade the system to fetch updates from the OSTree repo, create a new deployment, and install the changes:

    # rpm-ostree upgrade
15 metadata, 3 content objects fetched; 6220 KiB transferred in 2 seconds; 24.3 MB content written
Scanning metadata: 1821...done
Staging deployment...done
Run "systemctl reboot" to start a reboot

  10. 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.

  11. Notice that the wget RPM you added is not found, because a reboot is required to complete the upgrade:

    # wget -V
-bash: wget: command not found

  12. Reboot the system to deploy the new version of your image:

    $ systemctl reboot

  13. After the system reboots, log in as root using the password password.

  14. 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

  15. Verify that the upgrade worked:

    # wget -V
GNU Wget 1.21.1 built on linux-gnu.
...

    The output of the verification command shows that the upgrade was success because wget is available and the VM can access the OSTree repo.

© Red Hat