Upgrade the Ansible automation portal RHEL appliance - Red Hat Ansible Automation Platform 2.6

Important:

If you are upgrading from plug-in version 2.1 to 2.2, you must grant navigation permissions to existing roles. The Templates and History sidebar items now require explicit ansible.templates.view and ansible.history.view permission grants. Without these permissions, non-admin users cannot see the Templates and History navigation items. Administrators and superusers are unaffected.

After upgrading, log in as an administrator, navigate to Administration > RBAC, and add ansible.templates.view and ansible.history.view to each role that requires access. For more information, see Configure role-based access control for Ansible automation portal.

Bootc divides the filesystem into three categories that determine what happens during an upgrade:


Path	Upgrade behavior	What the appliance stores here
/usr	Replaced atomically with the new image	Portal scripts, pre-baked Ansible plugins, image version stamp
/etc	Three-way merged (your changes are preserved)	Portal configuration (app-config.production.yaml), Quadlet files, Quadlet drop-ins, SSL certificates
/var	Never touched by bootc	PostgreSQL database, backups, Podman secrets, generated configs

Your configuration files in /etc are preserved through upgrades using a three-way merge: bootc compares the original file from the old image, your modified version, and the new file from the new image. Your changes take precedence. Files in /var (database, backups) are never modified by bootc.

For more information about RHEL image mode, see Managing RHEL bootc images.

Prerequisites:

Back up and restore data before upgrading.
For connected upgrades, authenticate to registry.redhat.io (see the Authenticate to the container registry section).
For disconnected upgrades, configure a mirror registry or prepare an OCI archive (see Upgrade the Ansible automation portal RHEL appliance in a disconnected environment).

Authenticate to the container registry

To pull new appliance images from registry.redhat.io, authenticate to the registry and save the credentials where bootc can find them.

Procedure:

SSH into the Ansible automation portal RHEL appliance and log in to the container registry:
```
$ sudo podman login --authfile /etc/ostree/auth.json registry.redhat.io
```

Upgrade the appliance

Procedure:

Back up and restore data.
Run the upgrade:
```
$ sudo bootc upgrade
```
The upgrade is staged and does not take effect until you reboot. The current version continues running. You can schedule the reboot for a convenient maintenance window.

bootc upgrade pulls the latest image for the current tag. To upgrade to a specific version, use bootc switch with a version tag:
```
$ sudo bootc switch registry.redhat.io/ansible-automation-platform/bootc-automation-portal-rhel9:version
```
Reboot to activate the new image:
```
$ sudo systemctl reboot
```

Verification:

Verify that the new image is booted:
```
$ sudo bootc status
```
The booted digest matches the digest from the upgrade output. The previous version is retained as a rollback target.
Check the portal service logs:
```
$ sudo journalctl -u portal -f
```
Verify that all services are running:
```
$ sudo systemctl status portal postgres devtools
```
All three services (portal, postgres, devtools) show active (running).

Roll back an upgrade

Bootc maintains two image slots: the booted image and one rollback image. After an upgrade, the previous version becomes the rollback target. After a rollback, the upgraded version becomes the rollback target. You can switch between the two versions as needed.

If the new version has issues, roll back to the previous image.

Procedure:

Roll back to the previous image:
```
$ sudo bootc rollback
```
Reboot to activate the rollback image:
```
$ sudo systemctl reboot
```

The rollback reverts the system image atomically. Your configuration and data in the /etc and /var directories are preserved. After reboot, the post-upgrade reconciliation runs again and regenerates plugin configurations from the previous image version.

Verification:

Confirm the rollback was applied:
```
$ sudo bootc status
```
The booted image shows the previous digest. The upgraded image is now listed as the rollback target.
Verify that all services are running:
```
$ sudo systemctl status portal postgres devtools
```