Chapter 10. Upgrading Red Hat Ansible Automation Platform Operator on OpenShift Container Platform The Ansible Automation Platform Operator simplifies the installation, upgrade, and deployment of new Red Hat Ansible Automation Platform instances in your OpenShift Container Platform environment. 10.1. Overview You can use this document for help with upgrading Ansible Automation Platform 2.4 to 2.5 on Red Hat OpenShift Container Platform. This document applies to upgrades of Ansible Automation Platform 2.5 to later versions of 2.5. The Ansible Automation Platform Operator manages deployments, upgrades, backups, and restores of automation controller and automation hub. It also handles deployments of AnsibleJob and JobTemplate resources from the Ansible Automation Platform Resource Operator. Each operator version has default automation controller and automation hub versions. When the operator is upgraded, it also upgrades the automation controller and automation hub deployments it manages, unless overridden in the spec. OpenShift deployments of Ansible Automation Platform use the built-in Operator Lifecycle Management (OLM) functionality. For more information, see Operator Lifecycle Manager concepts and resources . OpenShift does this by using Subscription, CSV, InstallPlan, and OperatorGroup objects. Most users will not have to interact directly with these resources. They are created when the Ansible Automation Platform Operator is installed from OperatorHub and managed through the Subscriptions tab in the OpenShift console UI. For more information, refer to Accessing the web console . 10.2. Upgrade considerations If you are upgrading from version 2.4, continue to the Upgrading the Ansible Automation Platform Operator . If your OpenShift Container Platform version is not supported by the Red Hat Ansible Automation Platform version you are upgrading to, you must upgrade your OpenShift Container Platform cluster to a supported version first. Refer to the Red Hat Ansible Automation Platform Life Cycle to determine the OpenShift Container Platform version needed. For information about upgrading your cluster, refer to Updating clusters . 10.3. Prerequisites To upgrade to a newer version of Ansible Automation Platform Operator, you must: Ensure your system meets the system requirements detailed in the Operator topologies section of the Tested deployment models guide. Create AutomationControllerBackup and AutomationHubBackup objects. For help with this see Backup and recovery for operator environments Review the Release notes for the new Ansible Automation Platform version to which you are upgrading and any intermediate versions. Determine the type of upgrade you want to perform. See the Channel Upgrades section for more information. 10.4. Channel upgrades Upgrading to version 2.5 from Ansible Automation Platform 2.4 involves retrieving updates from a "channel". A channel refers to a location where you can access your update. It currently resides in the OpenShift console UI. 10.4.1. In-channel upgrades Most upgrades occur within a channel as follows: A new update becomes available in the marketplace, through the redhat-operator CatalogSource. The system automatically creates a new InstallPlan for your Ansible Automation Platform subscription. If set to Manual , the InstallPlan needs manual approval in the OpenShift UI. If set to Automatic , it upgrades as soon as the new version is available. Note Set a manual install strategy on your Ansible Automation Platform Operator subscription during installation or upgrade. You will be prompted to approve upgrades when available in your chosen update channel. Stable channels, like stable-2.5, are available for each X.Y release. A new subscription, CSV, and operator containers are created alongside the old ones. The old resources are cleaned up after a successful install. 10.4.2. Cross-channel upgrades Upgrading between X.Y channels is always manual and intentional. Stable channels for major and minor versions are in the Operator Catalog. Currently, only version 2.x is available, so there are few channels. It is recommended to stay on the latest minor version channel for the latest patches. If the subscription is set for manual upgrades, you must approve the upgrade in the UI. Then, the system upgrades the Operator to the latest version in that channel. Note It is recommended to set a manual install strategy on your Ansible Automation Platform Operator subscription during installation or upgrade. You will be prompted to approve upgrades when they become available in your chosen update channel. Stable channels, such as stable-2.5, are available for each X.Y release. The containers provided in the latest channel are updated regularly for OS upgrades and critical fixes. This allows customers to receive critical patches and CVE fixes faster. Larger changes and new features are saved for minor and major releases. For each major or minor version channel, there is a corresponding "cluster-scoped" channel available. Cluster-scoped channels deploy operators that can manage all namespaces, while non-cluster-scoped channels can only manage resources in their own namespace. Important Cluster-scoped bundles are not compatible with namespace-scoped bundles. Do not try to switch between normal (stable-2.4 for example) channels and cluster-scoped (stable-2.4-cluster-scoped) channels, as this is not supported. 10.5. Upgrading the Ansible Automation Platform Operator To upgrade to the latest version of Ansible Automation Platform Operator on OpenShift Container Platform, you can do the following: Prerequisites Read the Release notes for 2.5 [Optional] You need to deploy all of your Red Hat Ansible Automation Platform services (automation controller, automation hub, Event-Driven Ansible) to the same, single namespace before upgrading to 2.5 (only for existing deployments). For more information see, Migrating from one namespace to another . Review the Backup and recovery for operator environments guide and backup your services: AutomationControllerBackup AutomationHubBackup EDABackup Prodedure Log in to OpenShift Container Platform. Navigate to Operators Installed Operators . Select the Ansible Automation Platform Operator installed on your project namespace. Select the Subscriptions tab. Change the channel from stable-2.4 to stable-2.5. An InstallPlan is created for the user. Click Preview InstallPlan . Click Approve . Create a Custom Resource (CR) using the Ansible Automation Platform UI. The automation controller and automation hub UIs remain until all SSO configuration is supported in the platform gateway UI. For more information on configuring your updated Ansible Automation Platform Operator, see Configuring the Red Hat Ansible Automation Platform Operator on Red Hat OpenShift Container Platform . 10.6. Creating Ansible Automation Platform custom resources After upgrading to the latest version of Ansible Automation Platform Operator on OpenShift Container Platform, you can create an Ansible Automation Platform custom resource (CR) that specifies the names of your existing deployments, in the same namespace. Procedure This example outlines the steps to deploy a new Event-Driven Ansible setup after upgrading to the latest version, with existing automation controller and automation hub deployments already in place. The Appendix contains more examples of Ansible Automation Platform CRs for different deployments. Log in to Red Hat OpenShift Container Platform. Navigate to Operators Installed Operators . Select your Ansible Automation Platform Operator deployment. Select the Details tab. On the Ansible Automation Platform tile click Create instance . From the Create Ansible Automation Platform page enter a name for your instance in the Name field. Click YAML view and paste the following YAML ( aap-existing-controller-and-hub-new-eda.yml ): --- apiVersion: aap.ansible.com/v1alpha1 kind: AnsibleAutomationPlatform metadata: name: myaap spec: # Development purposes only no_log: false controller: name: existing-controller #obtain name from controller CR disabled: false eda: disabled: false hub: name: existing-hub disabled: false Click Create . Note You can override the operator's default image for automation controller, automation hub, or platform-resource app images by specifying the preferred image on the YAML spec. This enables upgrading a specific deployment, like a controller, without updating the operator. The recommended approach however, is to upgrade the operator and use the default image values. Verification Navigate to your Ansible Automation Platform Operator deployment and click All instances to verify whether all instances have deployed correctly. You should see the Ansible Automation Platform instance and the deployed AutomationController , EDA , and AutomationHub instances here. Alternatively, you can verify whether all instances deployed correctly by running oc get route in the command line. 10.7. Ansible Automation Platform post-upgrade steps After a successful upgrade to Ansible Automation Platform 2.5, the crucial step is migrating your users to the latest version of the platform. User data and legacy authentication settings from automation controller and private automation hub are carried over during the upgrade process and allow seamless initial access to the platform after upgrade. Customers can log in without additional action. However, to fully transition authentication to use all of the features and capabilities of the 2.5 platform gateway, a manual process is required post-upgrade to leverage the new authentication framework. In the context of upgrading to Ansible Automation Platform 2.5, this manual process is referred to as migration . There are important notes and considerations for each type of user migration, including the following: Admin users Normal users SAML users Be sure to read through the important notes highlighted for each user type to help make the migration process as smooth as possible. 10.7.1. Migrating admin users Upgrades from Ansible Automation Platform 2.4 to 2.5 allows for the migration of administrators for each component with their existing component-level admin privileges maintained. However, escalation of privileges to platform gateway administrator is not automatic during the upgrade process. This ensures a secure privilege escalation process that can be customized to meet the organization's specific needs. Prerequisites Review current admin roles for the individual services in your current deployment. Confirm the users who will require platform gateway admin rights post-upgrade. 10.7.1.1. Key considerations Component-level admin privileges are retained: Administrators for automation controller and automation hub will retain their existing admin privileges for those respective services post-upgrade. For example, an admin of automation controller will continue to have full administration privileges for automation controller resources. Note Users previously designated as automation controller or automation hub administrators are labeled as Normal in the User type column of the Users list view. This is a mischaracterization. You can verify that these users have, in fact, retained their service level administrator privileges, by editing the account: Procedure From the navigation panel of the platform gateway, select Access Management Users . Select the check box for the user that you want to modify. Click the Pencil icon and select Edit user . The Edit user page is displayed where you can see the service level administrator privileges assigned by the User type checkboxes. See Editing a user for more information on these user types. Note Only a platform administrator can escalate your privileges. Escalation to platform gateway admin must be manually configured post-upgrade: During the upgrade process, admin privileges for individual services are not automatically translated to platform administrator privileges. Escalation to platform gateway admin must be granted by the platform administrator after upgrade and migration. Each service admin retains the original scope of their access until the access is changed. As a platform administrator, you can escalate a user's privileges by selecting the Ansible Automation Platform Administrator checkbox. 10.7.2. Migrating normal users When you upgrade from Ansible Automation Platform 2.4 to 2.5, your existing user account is automatically migrated to a single platform account. However, if you have multiple component accounts (such as, automation controller, private automation hub and Event-Driven Ansible), your accounts must be linked to use the centralized features of the platform. 10.7.2.1. Key considerations service accounts are prefixed: Users with accounts on multiple services in 2.4 are migrated as individual users in 2.5 and prefixed to identify the service from which they were migrated. For example, automation hub accounts are prefixed as hub_<username> . Automation controller user names do not include a prefix. Automation controller user accounts take precedence: When an individual user had accounts on multiple services in 2.4, priority is given to their automation controller account during migration, so those are not renamed. Component level roles are retained until user migration is complete: When users log in using an existing service account and do not perform the account linking process, only the roles for that specific service account are available. The migration process is completed once the user performs the account linking process. At that time, all roles for all services are migrated into the new platform gateway user account. 10.7.2.2. Additional resources See Creating a user for more information on user types. 10.7.2.3. Linking your account Ansible Automation Platform 2.5 provides a centralized location for users, teams and organizations to access the platform's services and features. The first time you log in to Ansible Automation Platform 2.5, the platform searches through the existing services to locate a user account with the credentials you entered. When there is a match to an existing account, that account is registered and becomes centrally managed by the platform. Any subsequent component accounts in the system are orphaned and cannot be used to log into the platform. To address this problem, use the account linking procedure to authenticate from any of your existing component accounts and still be recognized by the platform. Linking accounts associates existing component accounts with the same user profile. Prerequisites You have completed the upgrade process and have a legacy Ansible Automation Platform account and credentials. Procedure If you have completed the upgrade process and have a legacy Ansible Automation Platform subscription, follow the account linking procedure below to migrate your account to Ansible Automation Platform 2.5. Navigate to the login page for Ansible Automation Platform. In the login modal, select either I have an automation controller account or I have an automation hub account based on the credentials you have. On the screen, enter the legacy credentials for the component account you selected and click Log in . Note If you are logging in using OIDC credentials, see How to fix broken OIDC redirect after upgrading to AAP 2.5 . If you have successfully linked your account, the screen shows your username with a green checkmark beside it. If you have other legacy accounts that you want to link, enter those account credentials and click Link to link them to your centralized platform gateway account. Click Submit to complete linking your legacy accounts. After your accounts are linked, depending on your authentication method, you might be prompted to create a new username and password. These credentials will replace your legacy credentials for each component account. You can also link your legacy account manually by taking the following steps: Select your user icon at the top right of your screen, and select User details . Select the More Actions icon ... > Link user accounts . Enter the credentials for the account that you want to link. If you encounter an error message telling you that your account could not be authenticated, contact your platform administrator. Note If you log into Ansible Automation Platform for the first time and are prompted to change your username, this is an indication that another user has already logged into Ansible Automation Platform with the same username. To proceed with account migration, follow the prompts to change your username. Ansible Automation Platform uses your password to authenticate which account or accounts belong to you. A diagram of the account linking flow After you have migrated your user account, you can manage your account from the Access Management menu. See Managing access with role based access control . 10.7.3. Migrating Single Sign-On (SSO) users When upgrading from Ansible Automation Platform 2.4 to 2.5, you must migrate your Single Sign-On (SSO) user accounts if you want to continue using SSO capabilities after the upgrade. Follow the steps in this procedure to ensure a smooth SSO user migration. 10.7.3.1. Key considerations SSO configurations are not migrated automatically during upgrade to 2.5: While the legacy authentication settings are carried over during the upgrade process and allow seamless initial access to the platform after upgrade, SSO configurations must be manually migrated over to a new Ansible Automation Platform 2.5 authentication configuration. The legacy configuration acts as a reference to preserve existing authentication capabilities and facilitate the migration process. The legacy authentication configuration should not be modified directly or used after migration is complete. SSO migration is not currently supported in the UI: While migration of SSO accounts is supported in 2.5, the configuration is not supported through the platform UI and must be done through the API /api/gateway/v1/authenticators/ . Migration of SSO must happen before users log in and start account linking: You must enable the Auto migrate users to setting after configuring SSO in 2.5 and before any users log in. Prerequisites You have configured a SSO authentication method in the platform gateway following the steps in Configuring an authentication type . This will be the configuration that you will migrate your SSO users to. Note Ansible Automation Platform 2.4 SSO configurations are renamed during the upgrade process and are displayed in the Authentication Methods list view with a prefix to indicate a legacy configuration: for example, legacy_sso-saml-<entity id> . The Authentication type is also listed as legacy sso . These configurations can not be modified. Procedure Log in to the platform gateway API. Go to /api/gateway/v1/authenticators/ , locate the legacy authenticator and click the link. This opens the HTML form for that authenticator. Select the new platform gateway authenticator from the Auto migrate users to list. Click PUT . Once you set up the auto migrate functionality, you should be able to login with SSO in the platform gateway and it will automatically link any matching accounts from the legacy SSO authenticator. Additional resources Refer to Ansible Automation Platform 2.4 to 2.5. Linking accounts post upgrade, and Setting up SAML authentication for a demonstration of the post upgrade steps.

Commands:
--- apiVersion: aap.ansible.com/v1alpha1 kind: AnsibleAutomationPlatform metadata: name: myaap spec: # Development purposes only no_log: false controller: name: existing-controller #obtain name from controller CR disabled: false eda: disabled: false hub: name: existing-hub disabled: false