Upgrading OSTree-based images

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

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:

   console $ 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:

   ```console

   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:

   YAML title="automotive image builder manifest" --8<-- "demos/ostree_upgrade/ostree_upgrade_v2.aib.yml:11:14"

5. Build your updated image:

   console $ 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:

   ```console $ ostree log --repo= //- 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:

   console $ 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:

   ```console

   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:

    ```console

    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:

    ```console

    wget -V

    -bash: wget: command not found ```

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

    console $ systemctl reboot

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

14. Check the status of the OS image deployment:

    ```console

    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:

    ```console

    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.