CCSINTL-471: 1st set of premigration updates to RPM install and upgrade docs (ansible#4231)

sayjadha · sayjadha · commit bc96043a7980 · 2025-09-12T19:15:25.000-04:00
* CCSINTL-471: 1st set of premigration updates to RPM install and upgrade docs

* CCSINTL-471: 2nd set of premigration updates

* CCSINTL-471: Incorporated 3rd set of premigration check updates

* CCSINTL-471: Incorporated peer feedback
diff --git a/downstream/assemblies/platform/assembly-aap-upgrading-platform.adoc b/downstream/assemblies/platform/assembly-aap-upgrading-platform.adoc
@@ -31,7 +31,9 @@ include::platform/proc-choosing-obtaining-installer-no-internet.adoc[leveloffset
 include::platform/proc-editing-inventory-file-for-updates.adoc[leveloffset=+1]
 include::platform/con-backup-aap.adoc[leveloffset=+1]
 include::platform/proc-running-setup-script-for-updates.adoc[leveloffset=+1]
-include::platform/proc-upgrade-controller-hub-eda-unified-ui.adoc[leveloffset=+1]
+include::platform/con-upgrade-controller-hub-eda-unified-ui.adoc[leveloffset=+1]
+include::platform/proc-upgrade-controller-hub-eda-unified-ui.adoc[leveloffset=+2]
+include::platform/proc-upgrade-controller-hub-eda-unified-services.adoc[leveloffset=+2]
 // [ddacosta] - Moved to a new post upgrade section of the doc
 //include::platform/proc-account-linking.adoc[leveloffset=+1]
 
diff --git a/downstream/modules/platform/con-aap-installation-on-disconnected-rhel.adoc b/downstream/modules/platform/con-aap-installation-on-disconnected-rhel.adoc
@@ -8,9 +8,10 @@
 [role="_abstract"]
 You can install {PlatformNameShort} without an internet connection by using the installer-managed database located on the {ControllerName}. The setup bundle is recommended for disconnected installation because it includes additional components that make installing {PlatformNameShort} easier in a disconnected environment. These include the {PlatformNameShort} Red Hat package managers (RPMs) and the default {ExecEnvShort} (EE) images.
 
-*Additional Resources*
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/rpm_installation/appendix-inventory-files-vars[Inventory file variables]
 
-For a comprehensive list of predefined variables used in installation inventory files, see link:{URLInstallationGuide}/appendix-inventory-files-vars[Inventory file variables].
 
 == System requirements for disconnected installation
 
@@ -29,5 +30,8 @@ RPM dependencies for {PlatformNameShort} that come from the BaseOS and AppStream
 The RHEL Binary DVD method requires the DVD for supported versions of RHEL. See link:https://access.redhat.com/support/policy/updates/errata[Red Hat Enterprise Linux Life Cycle] for information on which versions of RHEL are currently supported.
 ====
 
+[role="_additional-resources"]
 .Additional resources
-* link:{BaseURL}/red_hat_satellite/{SatelliteVers}/html/installing_satellite_server_in_a_disconnected_network_environment/index[Satellite]
+* link:https://docs.redhat.com/en/documentation/red_hat_satellite/6.16/html/installing_satellite_server_in_a_disconnected_network_environment[Installing Satellite Server in a disconnected network environment]
+
+
diff --git a/downstream/modules/platform/con-aap-installation-prereqs.adoc b/downstream/modules/platform/con-aap-installation-prereqs.adoc
@@ -17,4 +17,6 @@ WARNING: To prevent errors, upgrade your RHEL nodes fully before installing {Pla
 
 [role="_additional-resources"]
 .Additional resources
-For more information about obtaining a platform installer or system requirements, see the link:{URLPlanningGuide}/platform-system-requirements[System requirements] in the _{TitlePlanningGuide}_.
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/planning_your_installation/platform-system-requirements[System requirements]
+
+
diff --git a/downstream/modules/platform/con-aap-upgrade-planning.adoc b/downstream/modules/platform/con-aap-upgrade-planning.adoc
@@ -38,8 +38,7 @@ To resolve this issue, for each controller host, add the {Gateway} URL as a trus
 
 [role="_additional-resources"]
 .Additional resources
-* link:{URLCentralAuth}/assembly-gateway-licensing#proc-attaching-subscriptions[Attaching a subscription]
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/access_management_and_authentication/assembly-gateway-licensing#proc-attaching-subscriptions[Attaching a subscription]
 * xref:con-backup-aap_aap-upgrading-platform[Backup and restore]
-* link:{URLControllerAdminGuide}/controller-clustering[Clustering]
-* {LinkPlanningGuide}
-
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/configuring_automation_execution/controller-clustering[Clustering]
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/planning_your_installation/index[Planning your installation]
diff --git a/downstream/modules/platform/con-upgrade-controller-hub-eda-unified-ui.adoc b/downstream/modules/platform/con-upgrade-controller-hub-eda-unified-ui.adoc
@@ -0,0 +1,27 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-upgrade-controller-hub-eda-unified-ui_{context}"]
+= Automation controller and automation hub 2.4 and Event-Driven Ansible 2.5 with unified UI upgrades
+
+{PlatformNameShort} 2.5 supports upgrades from {PlatformNameShort} 2.4 environments for all components, with the exception of {EDAName}. You can also configure a mixed environment with {EDAName} from 2.5 connected to a legacy 2.4 cluster. Combining install methods (OCP, RPM, Containerized) within such a topology is not supported by {PlatformNameShort}.
+
+[NOTE]
+====
+If you are running the 2.4 version of {EDAName} in production, before you upgrade, contact Red Hat support or your account representative for more information on how to move to {PlatformNameShort} 2.5.
+====
+
+Supported topologies described in this document assume that:
+
+* 2.4 services will only include {ControllerName} and {HubName}.
+* 2.5 parts will always include {EDAName} and the unified UI ({Gateway}).
+* Combining installation methods for these topologies is not supported.
+
+== Upgrade considerations
+
+* You must maintain two separate inventory files: one for the 2.4 services and one for the 2.5 services.
+* You must maintain two separate installations within this scenario: one for the 2.4 services and one for the 2.5 services. 
+* You must upgrade the two separate installations separately.
+* To upgrade to a consistent component version topology, consider the following: 
+** You must manually combine the inventory file configuration from the 2.4 inventory into the 2.5 inventory and run upgrade on ONLY the 2.5 inventory file. 
+** You must be using an external database for both the 2.4 inventory as well as the 2.5 inventory. 
+** Customers using managed database instances for either 2.4 or 2.5 inventory must migrate to an external database first, before upgrading.
diff --git a/downstream/modules/platform/proc-aap-activate-with-manifest.adoc b/downstream/modules/platform/proc-aap-activate-with-manifest.adoc
@@ -5,16 +5,9 @@
 
 = Activate with a manifest file
 
-If you have a subscriptions manifest, you can upload the manifest file either by using the {PlatformName} interface.
+If you have a subscriptions manifest, you can upload the manifest file either by using the {PlatformName} interface. 
 
-[NOTE]
-====
-You are opted in for {Analytics} by default when you activate the platform on first time log in. This helps Red Hat improve the product by delivering you a much better user experience. You can opt out, after activating {PlatformNameShort}, by doing the following: 
-
-. From the navigation panel, select {MenuSetSystem}.
-. Uncheck the *Gather data for {Analytics}* option.
-. Click btn:[Save].
-====
+You are opted in for {Analytics} by default when you activate the platform on first time log in. This helps Red Hat improve the product by delivering you a much better user experience. However, you can opt out of {Analytics} after the {PlatformNameShort} is activated. To opt out, select {MenuSetSystem} from the navigation panel, uncheck the *Gather data for {Analytics}* option, and then click btn:[Save].
 
 ifndef::controller-AG[]
 .Prerequisites
diff --git a/downstream/modules/platform/proc-aap-add-merge-subscriptions.adoc b/downstream/modules/platform/proc-aap-add-merge-subscriptions.adoc
@@ -16,4 +16,4 @@ Once an allocation is created, you can add the subscriptions you need for {Platf
 
 [role="_additional-resources"]
 .Next steps
-* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/installing_on_openshift_container_platform/index#proc-aap-generate-manifest-file[Download the manifest file]. 
+* link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html-single/installing_on_openshift_container_platform/index#proc-aap-generate-manifest-file[Download the manifest file]. 
diff --git a/downstream/modules/platform/proc-accessing-rpm-repositories-for-locally-mounted-dvd.adoc b/downstream/modules/platform/proc-accessing-rpm-repositories-for-locally-mounted-dvd.adoc
@@ -57,6 +57,6 @@ www.redhat.com]
 ----
 ====
 
-
-.Additional Resources
-For further detail on setting up a repository see link:https://access.redhat.com/solutions/3776721[Need to set up yum repository for locally-mounted DVD on Red Hat Enterprise Linux 8].
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/solutions/3776721[Need to set up yum repository for locally-mounted DVD on Red Hat Enterprise Linux 8]
diff --git a/downstream/modules/platform/proc-choosing-obtaining-installer.adoc b/downstream/modules/platform/proc-choosing-obtaining-installer.adoc
@@ -15,14 +15,12 @@ Choose the {PlatformName} installer you need based on your {RHEL} environment in
 A valid Red Hat customer account is required to access {PlatformName} installer downloads on the Red Hat Customer Portal.
 ====
 
-== Installing with internet access
-
 Choose the {PlatformName} installer if your {RHEL} environment is connected to the internet. Installing with internet access retrieves the latest required repositories, packages, and dependencies. Choose one of the following ways to set up your {PlatformNameShort} installer.
 
-*Tarball install*
-
 .Procedure
 
+* *Tarball install*
++ 
 . Navigate to the link:{PlatformDownloadUrl}[{PlatformName} download] page.
 . In the *Product software* tab, click btn:[Download Now] for the *Ansible Automation Platform <latest-version> Setup*.
 . Extract the files:
@@ -31,9 +29,7 @@ Choose the {PlatformName} installer if your {RHEL} environment is connected to t
 $ tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz
 -----
 
-*RPM install*
-
-.Procedure
+* *RPM install*
 
 . Install the {PlatformNameShort} Installer Package.
 +
@@ -48,9 +44,10 @@ v.{PlatformVers} for RHEL 9 for x86-64:
 ----
 $ sudo dnf install --enablerepo=ansible-automation-platform-2.5-for-rhel-9-x86_64-rpms ansible-automation-platform-installer
 ----
++
 [NOTE]
 ====
 `dnf install` enables the repo as the repo is disabled by default.
 ====
-
++
 When you use the RPM installer, the files are placed under the `/opt/ansible-automation-platform/installer` directory.
diff --git a/downstream/modules/platform/proc-editing-inventory-file-for-updates.adoc b/downstream/modules/platform/proc-editing-inventory-file-for-updates.adoc
@@ -38,9 +38,7 @@ Do not use `localhost`.
 If `localhost` is used, the upgrade will be stopped as part of preflight checks.
 ====
 
-.Provisioning new nodes in a cluster
-
-* Add new nodes alongside existing nodes in the `inventory` file as follows:
+. Provision new nodes in a cluster, by adding new nodes alongside existing nodes in the `inventory` file as follows:
 +
 [source,ini,options="nowrap",subs=attributes+]
 ----
diff --git a/downstream/modules/platform/proc-installing-the-aap-setup-bundle.adoc b/downstream/modules/platform/proc-installing-the-aap-setup-bundle.adoc
@@ -25,7 +25,6 @@ $ cd ansible-automation-platform-setup-bundle-2.5-1
 +
 . Edit the inventory file to include variables based on your host names and desired password values.
 
-[NOTE]
-====
-See section xref:con-install-scenario-examples[3.2 Inventory file examples base on installation scenarios] for a list of examples that best fits your scenario.
-====
+[role="_additional-resources"]
+.Additional resources
+* xref:con-install-scenario-examples[3.2 Inventory file examples base on installation scenarios]
diff --git a/downstream/modules/platform/proc-postgresql-enable-mtls-authentication.adoc b/downstream/modules/platform/proc-postgresql-enable-mtls-authentication.adoc
@@ -7,8 +7,9 @@
 mTLS authentication is disabled by default; however, you can optionally enable the authentication. 
 
 .Procedure
-To configure each component's database with mTLS authentication, add the following variables to your inventory file under the `[all:vars]` group and ensure each component has a different TLS certificate and key:
 
+* To configure each component's database with mTLS authentication, add the following variables to your inventory file under the `[all:vars]` group and ensure each component has a different TLS certificate and key:
++
 [source,yaml,subs="+attributes"]
 ----
 # {ControllerNameStart}
diff --git a/downstream/modules/platform/proc-running-setup-script-for-updates.adoc b/downstream/modules/platform/proc-running-setup-script-for-updates.adoc
@@ -14,7 +14,7 @@ You can run the setup script once you have finished updating the `inventory` fil
 -----
 $ ./setup.sh
 -----
-
++
 The installation will begin. 
 
 [role="_additional-resources"]
diff --git a/downstream/modules/platform/proc-upgrade-controller-hub-eda-unified-services.adoc b/downstream/modules/platform/proc-upgrade-controller-hub-eda-unified-services.adoc
@@ -0,0 +1,91 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2024-10-09
+:_mod-docs-content-type: PROCEDURE
+
+[id="upgrade-controller-hub-eda-unified-ui-services_{context}"]
+= Using Migration path for 2.4 services with 2.5 services
+
+If you installed {PlatformNameShort} 2.5 to use {EDAName} in a supported scenario, you can upgrade your {PlatformNameShort} 2.4 {ControllerName} and {HubName} to {PlatformNameShort} 2.5 by following the procedure in this section. 
+
+.Prerequisites
+
+* An inventory from 2.4 for {ControllerName} and {HubName} and a 2.5 inventory for unified UI ({Gateway}) and {EDAName}. You must run upgrades on 2.4 services (using the inventory file to specify only {ControllerName} and {HubName} VMs) to get them to the initial version of {PlatformNameShort} 2.5 first. When all the services are at the same version, run an upgrade (using a complete inventory file) on all the services to go to the latest version of {PlatformNameShort} 2.5.
+
+[IMPORTANT]
+====
+DO NOT upgrade {EDAName} and the unified UI ({Gateway}) to the latest version of {PlatformNameShort} 2.5 without first upgrading the individual services ({ControllerName} and {HubName}) to the initial version of {PlatformNameShort} 2.5.
+====
+
+* Ensure you have upgraded to the latest version of {PlatformNameShort} 2.4 before upgrading your {PlatformName}.
+
+.Procedure
+
+. Merge 2.4 inventory data into the 2.5 inventory. 
++
+The example below shows the inventory file for {ControllerName} and {HubName} for 2.4 and the inventory file for {EDAName} and the unified UI ({Gateway}) for 2.5, respectively, as the starting point, and what the merged inventory looks like. 
++
+*Inventory files from 2.4*
++
+[source,bash]
+----
+[automationcontroller]
+controller-1
+controller-2
+
+[automationhub]
+hub-1
+hub-2
+
+[all:vars]
+# Here we have the admin passwd, db credentials, etc.
+----
++
+*Inventory files from 2.5*
++
+[source,]
+----
+[edacontroller]
+eda-1
+eda-2
+ 
+[gateway]
+gw-1
+gw-2
+ 
+[all:vars]
+# Here we have admin passwd, db credentials etc.
+----
++
+*Merged Inventory*
++
+[source,]
+----
+[automationcontroller]
+controller-1
+controller-2
+ 
+[automationhub]
+hub-1
+hub-2
+ 
+[edacontroller]
+eda-1
+eda-2
+ 
+[gateway]
+gw-1
+gw-2
+ 
+[all:vars]
+# Here we have admin passwd, db credentials etc from both inventories above
+----
+
+. Run `setup.sh`
++
+The installer upgrades {ControllerName} and {HubName} from 2.4 to {PlatformNameShort} 2.5.latest, {EDAName}, and the unified UI ({Gateway}) from the fresh install of 2.5 to the latest version of 2.5, and connects {ControllerName} and {HubName} properly with the unified UI ({Gateway}) node to initialize the unified experience. 
+
+.Verification
+
+* Verify that everything has upgraded to 2.5 and is working properly in one of two ways: 
+** Perform an SSH to {ControllerName} and {EDAName}.
+** In the unified UI, navigate to *Help > About* to verify the RPM versions are at 2.5.
diff --git a/downstream/modules/platform/proc-upgrade-controller-hub-eda-unified-ui.adoc b/downstream/modules/platform/proc-upgrade-controller-hub-eda-unified-ui.adoc
diff --git a/downstream/modules/platform/proc-verify-aap-installation.adoc b/downstream/modules/platform/proc-verify-aap-installation.adoc
diff --git a/downstream/modules/platform/ref-postgresql-requirements.adoc b/downstream/modules/platform/ref-postgresql-requirements.adoc
diff --git a/downstream/modules/platform/ref-system-requirements.adoc b/downstream/modules/platform/ref-system-requirements.adoc
