ansible · ariordan-redhat · Oct 8, 2024 · Oct 9, 2024 · Oct 9, 2024 · Oct 10, 2024
diff --git a/downstream/assemblies/platform/assembly-aap-migration.adoc b/downstream/assemblies/platform/assembly-aap-migration.adoc
@@ -10,10 +10,16 @@ ifdef::context[:parent-context: {context}]
 
 Migrating your {PlatformName} deployment to the {OperatorPlatformNameShort} allows you to take advantage of the benefits provided by a Kubernetes native operator, including simplified upgrades and full lifecycle support for your {PlatformName} deployments.
 
+[NOTE]
+====
+Upgrades of {EDAName} version 2.4 to 2.5 are not supported. Database migrations between {EDAName} 2.4 and {EDAName} 2.5 are not compatible.
+====
+
 Use these procedures to migrate any of the following deployments to the {OperatorPlatformNameShort}:
 
-* A VM-based installation of Ansible Tower 3.8.6, {ControllerName}, or {HubName}
-* An Openshift instance of Ansible Tower 3.8.6 ({PlatformNameShort} 1.2)
+* OpenShift cluster A to OpenShift cluster B
+* OpenShift namespace A to OpenShift namespace B
+* Virtual machine (VM) based or containerized VM {PlatformNameShort} 2.5 → {PlatformNameShort} 2.5
 
 include::platform/con-aap-migration-considerations.adoc[leveloffset=+1]
 include::platform/con-aap-migration-prepare.adoc[leveloffset=+1]
@@ -24,6 +30,7 @@ include::platform/proc-verify-network-connectivity.adoc[leveloffset=+2]
 include::platform/proc-aap-migration.adoc[leveloffset=+1]
 include::platform/proc-aap-create_controller.adoc[leveloffset=+2]
 include::platform/proc-aap-create_hub.adoc[leveloffset=+2]
+include::platform/proc-aap-create_eda.adoc[leveloffset=+2]
 include::platform/proc-post-migration-cleanup.adoc[leveloffset=+1]
 
 

diff --git a/downstream/assemblies/platform/assembly-aap-upgrades.adoc b/downstream/assemblies/platform/assembly-aap-upgrades.adoc
@@ -8,12 +8,9 @@ ifdef::context[:parent-context: {context}]
 
 [role="_abstract"]
 
-Upgrade to {PlatformName} {PlatformVers} by setting up your inventory and running the installation script.
-Ansible then upgrades your deployment to {PlatformVers}.
-If you plan to upgrade from {PlatformNameShort} 2.0 or earlier, you must migrate Ansible content for compatibility with {PlatformVers}.
 
 include::platform/con-aap-upgrades.adoc[leveloffset=+1]
-include::platform/con-aap-upgrades-legacy.adoc[leveloffset=+1]
+// include::platform/con-aap-upgrades-legacy.adoc[leveloffset=+1]
 
 
 ifdef::parent-context[:context: {parent-context}]

diff --git a/downstream/assemblies/platform/assembly-aap-upgrading-platform.adoc b/downstream/assemblies/platform/assembly-aap-upgrading-platform.adoc
@@ -7,14 +7,17 @@ ifdef::context[:parent-context: {context}]
 
 [role="_abstract"]
 
-To upgrade your {PlatformName}, start by reviewing planning information to ensure a successful upgrade.
+To upgrade your {PlatformName}, start by reviewing link:{LinkPlanningGuide} to ensure a successful upgrade.
 You can then download the desired version of the {PlatformNameShort} installer, configure the inventory file in the installation bundle to reflect your environment, and then run the installer.
 
 include::platform/con-aap-upgrade-planning.adoc[leveloffset=+1]
 
 include::platform/proc-choosing-obtaining-installer.adoc[leveloffset=+1]
 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/proc-account-linking.adoc[leveloffset=+1]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/platform/assembly-appendix-operator-crs.adoc b/downstream/assemblies/platform/assembly-appendix-operator-crs.adoc
@@ -0,0 +1,15 @@
+
+ifdef::context[:parent-context: {context}]
+
+[id="appendix-operator-crs_{context}"]
+
+= Appendix: {PlatformName} custom resources 
+
+[role="_abstract"]
+
+This appendix provides a reference for the {PlatformNameShort} custom resources for various deployment scenarios.
+
+include::platform/ref-operator-crs.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/platform/assembly-configure-aap-operator.adoc b/downstream/assemblies/platform/assembly-configure-aap-operator.adoc
@@ -6,22 +6,22 @@ ifdef::context[:parent-context: {context}]
 
 = Configuring the {OperatorPlatformName} on {OCP}
 
-The platform gateway for {PlatformNameShort} enables you to manage the following {PlatformNameShort} components to form a single user interface:
+The  {Gateway} for {PlatformNameShort} enables you to manage the following {PlatformNameShort} components to form a single user interface:
 
 * {ControllerNameStart}
 * {HubNameStart}
 * {EDAName}
 * {LightspeedShortName} (This feature is disabled by default, you must opt in to use it.)
 
-Before you can deploy the platform gateway you must have {OperatorPlatformNameShort} installed in a namespace. 
+Before you can deploy the {Gateway} you must have {OperatorPlatformNameShort} installed in a namespace. 
 If you have not installed {OperatorPlatformNameShort} see xref:install-aap-operator_operator-platform-doc[Installing the {OperatorPlatformName} on {OCP}].
 
 [NOTE] 
 ====
-Platform gateway is only available under {OperatorPlatformNameShort} version 2.5. Every component deployed under {OperatorPlatformNameShort} 2.5 will also default to version 2.5.
+{GatewayStart} is only available under {OperatorPlatformNameShort} version 2.5. Every component deployed under {OperatorPlatformNameShort} 2.5 defaults to version 2.5.
 ====
 
-If you have the {OperatorPlatformNameShort} and some or all of the {PlatformNameShort} components installed see xref:operator-deploy-central-config_{context}[Deploying the platform gateway with existing {PlatformNameShort} components]for how to proceed. 
+If you have the {OperatorPlatformNameShort} and some or all of the {PlatformNameShort} components installed see xref:operator-deploy-central-config_{context}[Deploying the  {Gateway} with existing {PlatformNameShort} components] for how to proceed.
 
 include::platform/proc-operator-link-components.adoc[leveloffset=+1]
 include::platform/proc-operator-access-aap.adoc[leveloffset=+1]

diff --git a/downstream/assemblies/platform/assembly-install-aap-operator.adoc b/downstream/assemblies/platform/assembly-install-aap-operator.adoc
@@ -1,11 +1,9 @@
 
-
 ifdef::context[:parent-context: {context}]
 
-
-
 [id="install-aap-operator_{context}"]
-= Installing the {PlatformName} on {OCP}
+
+= Installing the {OperatorPlatformName} on {OCP}
 
 [role="_abstract"]
 

diff --git a/downstream/assemblies/platform/assembly-installing-aap-operator-cli.adoc b/downstream/assemblies/platform/assembly-installing-aap-operator-cli.adoc
@@ -1,14 +1,6 @@
-// Used in
-// titles/aap-operator-installation/
-////
-Retains the context of the parent assembly if this assembly is nested within another assembly.
-For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
-See also the complementary step on the last line of this file.
-////
-
 ifdef::context[:parent-context: {context}]
 
-[id="installing-aap-operator-cli_{Context}"]
+[id="installing-aap-operator-cli_{context}"]
 = Installing {OperatorPlatformName} from the {OCPShort} CLI
 
 :context: installing-aap-operator-cli

diff --git a/downstream/assemblies/platform/assembly-operator-upgrade.adoc b/downstream/assemblies/platform/assembly-operator-upgrade.adoc
@@ -9,13 +9,14 @@ ifdef::context[:parent-context: {context}]
 
 [role="_abstract"]
 
-The {OperatorPlatformNameShort} simplifies the installation, upgrade and deployment of new {PlatformName} instances in your {OCPShort} environment.
+The {OperatorPlatformNameShort} simplifies the installation, upgrade, and deployment of new {PlatformName} instances in your {OCPShort} environment.
 
+include::platform/con-operator-upgrade-overview.adoc[leveloffset=+1]
 include::platform/con-operator-upgrade-considerations.adoc[leveloffset=+1]
 include::platform/con-operator-upgrade-prereq.adoc[leveloffset=+1]
+include::platform/con-operator-channel-upgrade.adoc[leveloffset=+1]
 include::platform/proc-operator-upgrade.adoc[leveloffset=+1]
-
-
+include::platform/proc-operator-create_crs.adoc[leveloffset=+1]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/platform/assembly-platform-install-scenario.adoc b/downstream/assemblies/platform/assembly-platform-install-scenario.adoc
@@ -74,6 +74,7 @@ include::platform/proc-configure-pulpcore-service.adoc[leveloffset=+4]
 include::platform/proc-apply-selinux-context.adoc[leveloffset=+4]
 include::hub/hub/proc-configure-content-signing-on-pah.adoc[leveloffset=+3]
 include::platform/proc-add-eda-safe-plugin-var.adoc[leveloffset=+3]
+include::platform/ref-redis-config-enterprise-topology.adoc[leveloffset=+3]
 include::platform/proc-running-setup-script.adoc[leveloffset=+1]
 include::platform/proc-verify-aap-installation.adoc[leveloffset=+1]
 include::platform/con-adding-subscription-manifest.adoc[leveloffset=+1]

diff --git a/downstream/images/Subscription_tab.png b/downstream/images/Subscription_tab.png
diff --git a/downstream/images/account-linking-flow.png b/downstream/images/account-linking-flow.png
diff --git a/downstream/images/change_subscription.png b/downstream/images/change_subscription.png
diff --git a/downstream/modules/platform/con-aap-migration-considerations.adoc b/downstream/modules/platform/con-aap-migration-considerations.adoc
@@ -4,4 +4,6 @@
 
 
 [role="_abstract"]
-If you are upgrading from {PlatformNameShort} 1.2 on {OCPShort} 3 to {PlatformNameShort} 2.x on {OCPShort} 4, you must provision a fresh {OCPShort} version 4 cluster and then migrate the {PlatformNameShort} to the new cluster. 
+If you are upgrading from any version of {PlatformNameShort} older than 2.4, you must upgrade through {PlatformNameShort} first.
+If you are on {OCPShort} 3 and you want to upgrade to {OCPShort} 4, you must provision a fresh {OCPShort} version 4 cluster and then migrate the {PlatformNameShort} to the new cluster.
+
diff --git a/downstream/modules/platform/con-aap-migration-prepare.adoc b/downstream/modules/platform/con-aap-migration-prepare.adoc
@@ -4,7 +4,7 @@
 
 [role="_abstract"]
 
-Before migrating your current {PlatformNameShort} deployment to {OperatorPlatformNameShort}, you need to back up your existing data, create k8s secrets for your secret key and postgresql configuration.
+Before migrating your current {PlatformNameShort} deployment to {OperatorPlatformNameShort}, you must back up your existing data, and create Kubernetes secrets for your secret key and postgresql configuration.
 
 [NOTE]
 ====

diff --git a/downstream/modules/platform/con-aap-upgrade-planning.adoc b/downstream/modules/platform/con-aap-upgrade-planning.adoc
@@ -7,34 +7,23 @@
 [role="_abstract"]
 Before you begin the upgrade process, review the following considerations to plan and prepare your {PlatformNameShort} deployment:
 
-[discrete]
-== {ControllerNameStart}
-
-* Even if you have a valid license from a previous version, you must provide your credentials or a subscriptions manifest upon upgrading to the latest version of {ControllerName}.
-* If you need to upgrade {RHEL} and {ControllerName}, you must first backup and restore your {ControllerName} data.
-* Clustered upgrades require special attention to instance and instance groups before upgrading.
+* See link:{URLPlanningGuide}/platform-system-requirements[System requirements] in the {TitlePlanningGuide} guide to ensure you have the topologies that fit your use case. 
++
+[NOTE]
+====
+2.4 to 2.5 upgrades now include link:{URLPlanningGuide}/ref-aap-components#con-about-platform-gateway_planning[Platform gateway]. Ensure you review the 2.5 link:{URLPlanningGuide}/ref-network-ports-protocols_planning[Network ports and protocols] for architectural changes.
+====
++
+* Ensure you have a valid subscription from a previous version. You must provide your credentials or a link:https://access.redhat.com/articles/5807761[subscriptions manifest] upon upgrading to the latest version of {PlatformNameShort}.
+* Clustered upgrades require special attention to instance and instance groups before upgrading. Ensure you capture your inventory or instance group details before upgrading.
+* Upgrades of {EDAName} version 2.4 to 2.5 are not supported. Database migrations between {EDAName} 2.4 and {EDAName} 2.5 are not compatible.
++
+If you are currently running {EDAcontroller} 2.5, it is recommended that you disable all {EDAName} activations before upgrading to ensure that only new activations run after the upgrade process is complete. 
 
 [role="_additional-resources"]
 .Additional resources
-* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html/automation_controller_user_guide/controller-managing-subscriptions#controller-importing-subscriptions[Importing a subscription]
-* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html/automation_controller_administration_guide/controller-backup-and-restore[Backup and restore]
-* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html/automation_controller_administration_guide/controller-clustering[Clustering]
-
-[discrete]
-== {HubNameStart}
-
-* When upgrading to {PlatformNameShort} {PlatformVers}, you can either add an existing {HubName} API token or generate a new one and invalidate any existing tokens.
-* Existing container images are removed when upgrading {PlatformNameShort}. 
-This is because, when upgrading {PlatformNameShort} with `setup.sh` script, podman `system reset -f` is executed. 
-This removes all container images on your {PlatformNameShort} nodes then pushes the new {ExecEnvShort} image that is bundled with installer.
-See xref:proc-running-setup-script-for-updates[Running the {PlatformName} installer setup script].
-
-[role="_additional-resources"]
-.Additional resources
-* <<editing-inventory-file-for-updates_{context}, Setting up the inventory file >>
-
-[discrete]
-== {EDAcontroller}
-//ATTENTION: Remove this section for EDA 1.0.4; customers will no longer need to perform deactivation because services will be automatically restored after upgrade and migration. 
+* link:{URLCentralAuth}/assembly-gateway-licensing#proc-attaching-subscriptions[Attaching a subscription]
+* xref:platform/con-backup-aap.adoc[Backup and restore]
+* link:{URLControllerAdminGuide}/controller-clustering[Clustering]
+* link:{LinkPlanningGuide}
 
-* If you are currently running {EDAcontroller} and plan to deploy it when you upgrade to {PlatformNameShort} {PlatformVers}, it is recommended that you disable all {EDAName} activations before upgrading to ensure that only new activations run after the upgrade process has completed. This prevents possibilities of orphaned containers running activations from the previous version.
diff --git a/downstream/modules/platform/con-aap-upgrades.adoc b/downstream/modules/platform/con-aap-upgrades.adoc
@@ -4,11 +4,12 @@
 
 = {PlatformNameShort} upgrades
 
-Upgrading to version {PlatformVers} from {PlatformNameShort} 2.1 or later involves downloading the installation package and then performing the following steps:
+Upgrading {PlatformNameShort} {PlatformVers}  involves downloading the installation package and then performing the following steps:
 
-* Set up your inventory to match your installation environment.
+* Set up your inventory to match your installation environment. See link:{LinkTopologies} for a list of example inventory files. 
 * Run the {PlatformVers} installation program over your current {PlatformNameShort} installation.
 
+// [hherbly]: not sure we need the addt'l resources block? the xref goes to the next section of the document.
 [role="_additional-resources"]
 .Additional resources
-* <<aap-upgrading-platform,Upgrading to {PlatformName} {PlatformVers}>>
+* xref:platform/assembly-aap-upgrading-platform[Upgrading to {PlatformName} {PlatformVers}]
diff --git a/downstream/modules/platform/con-backup-aap.adoc b/downstream/modules/platform/con-backup-aap.adoc
@@ -2,16 +2,17 @@
 
 = Back up your {PlatformNameShort} instance
 
-Back up an existing {PlatformNameShort} instance by running the `.setup.sh` script with the `backup_dir` flag, which saves the content and configuration of your current environment:
+Back up an existing {PlatformNameShort} instance by running the `.setup.sh` script with the `backup_dir` flag, which saves the content and configuration of your current environment.
 
-. Navigate to your `ansible-tower-setup-latest` directory.
+.Procedure
+
+. Navigate to your {PlatformNameShort} installation directory.
 . Run the `./setup.sh` script following the example below:
 +
 ----
-$ ./setup.sh -e ‘backup_dir=/ansible/mybackup’ -e ‘use_compression=True’ @credentials.yml -b <1><2>
+$ ./setup.sh -e ‘backup_dir=/ansible/mybackup’ -e ‘use_compression=True’ @credentials.yml -b <1>
 ----
 <1> `backup_dir` specifies a directory to save your backup to.
-<2> `@credentials.yml` passes the password variables and their values encrypted via `ansible-vault`.
 
-With a successful backup, a backup file is created at `/ansible/mybackup/tower-backup-latest.tar.gz` .
+With a successful backup, a backup file is created at `/ansible/mybackup/automation-platform-backup-<date/time>.tar.gz` .
 
diff --git a/downstream/modules/platform/con-ocp-supported-install.adoc b/downstream/modules/platform/con-ocp-supported-install.adoc
@@ -1,11 +1,11 @@
-[id="con-ocp-supported-install_{context}"]
+[id="ocp-supported-install_{context}"]
 
 = Supported installation scenarios for {OCP}
 
 
 You can use the OperatorHub on the {OCP} web console to install {OperatorPlatformNameShort}.
 
-Alternatively, you can install {OperatorPlatformNameShort} from the {OCPShort} command-line interface (CLI), `oc`. See xref:installing-aap-operator-cli_operator-platform-doc[Installing {OperatorPlatformName}  from the {OCPShort} CLI] for help with this. 
+Alternatively, you can install {OperatorPlatformNameShort} from the {OCPShort} command-line interface (CLI), `oc`. See xref:installing-aap-operator-cli_operator-platform-doc[Installing {OperatorPlatformName} from the {OCPShort} CLI] for help with this. 
 
 After you have installed {OperatorPlatformNameShort} you must create an *{PlatformNameShort}* custom resource (CR). This enables you to manage {PlatformNameShort} components from a single unified interface known as the platform gateway. As of version 2.5, you must create an {PlatformNameShort} CR, even if you have an existing {ControllerName},  {HubName}, or {EDAName}, components.
 

diff --git a/downstream/modules/platform/con-operator-channel-upgrade.adoc b/downstream/modules/platform/con-operator-channel-upgrade.adoc
@@ -0,0 +1,50 @@
+[id="operator-channel-upgrade_{context}"]
+
+= Channel upgrades
+
+Upgrading to version 2.5 from {PlatformNameShort} 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.
+
+image:change_subscription.png[Update channel]
+
+==  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 {PlatformNameShort} 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 {OperatorPlatformNameShort} 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.
+
+== 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 {OperatorPlatformNameShort} 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.
+====
diff --git a/downstream/modules/platform/con-operator-upgrade-considerations.adoc b/downstream/modules/platform/con-operator-upgrade-considerations.adoc
@@ -2,11 +2,9 @@
 
 = Upgrade considerations
 
+If you are upgrading from version 2.4, continue to the xref:upgrading-operator_{context}[Upgrading the {OperatorPlatformNameShort}].
 
-[role="_abstract"]
-{PlatformName} version 2.0 was the first release of the {OperatorPlatformNameShort}. If you are upgrading from version 2.0, continue to the xref:upgrading-operator_operator-upgrade[Upgrading the {OperatorPlatformNameShort}] procedure.
-
-If you are using a version of {OCPShort} that is not supported by the version of {PlatformName} to which you are upgrading, you must upgrade your {OCPShort} cluster to a supported version before upgrading.
+If your {OCPShort} version is not supported by the {PlatformName} version you are upgrading to, you must upgrade your {OCPShort} cluster to a supported version first.
 
 Refer to the link:https://access.redhat.com/support/policy/updates/ansible-automation-platform[Red Hat Ansible Automation Platform Life Cycle] to determine the {OCPShort} version needed.