ansible · michellemacrh · Jul 15, 2025 · Jul 15, 2025
diff --git a/downstream/assemblies/platform/assembly-gateway-licensing.adoc b/downstream/assemblies/platform/assembly-gateway-licensing.adoc
@@ -11,13 +11,19 @@ Ansible is an open source software project and is licensed under the GNU General
 
 You must have valid subscriptions attached before installing {PlatformNameShort}. 
 
-For more information, see xref:proc-attaching-subscriptions[Attaching Subscriptions].
+For more information, see link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/installing_on_openshift_container_platform/index#proc-attaching-subscriptions[Attaching Subscriptions].
 
 include::platform/ref-controller-trial-evaluation.adoc[leveloffset=+1]
+
 include::platform/ref-controller-licenses.adoc[leveloffset=+1]
+
 include::platform/ref-controller-node-counting.adoc[leveloffset=+1]
+
 include::platform/ref-controller-subscription-types.adoc[leveloffset=+1]
+
 include::platform/proc-attaching-subscriptions.adoc[leveloffset=+1]
+
 include::assembly-aap-manifest-files.adoc[leveloffset=+1]
+
 include::assembly-aap-activate.adoc[leveloffset=+1]
 
diff --git a/downstream/assemblies/platform/assembly-install-aap-operator.adoc b/downstream/assemblies/platform/assembly-install-aap-operator.adoc
@@ -35,7 +35,7 @@ You cannot deploy {PlatformNameShort} in the default namespace on your OpenShift
 ====
 
 
-.Prerequisites
+== Prerequisites
 * You have installed the {PlatformName} catalog in OperatorHub.
 * You have created a `StorageClass` object for your platform and a persistent volume claim (PVC) with `ReadWriteMany` access mode. See link:https://docs.openshift.com/container-platform/{OCPLatest}/storage/dynamic-provisioning.html[Dynamic provisioning] for details.
 * To run {OCP} clusters on Amazon Web Services (AWS) with `ReadWriteMany` access mode, you must add NFS or other storage.

diff --git a/downstream/assemblies/platform/assembly-installing-aap-operator-cli.adoc b/downstream/assemblies/platform/assembly-installing-aap-operator-cli.adoc
@@ -25,14 +25,16 @@ You can use the {OCPShort} CLI to fetch the web address and the password of the
 To login to the {Gateway}, you need the web address and the password.
 
 include::platform/proc-cli-get-controller-address.adoc[leveloffset=+1]
+
 include::platform/proc-cli-get-controller-pwd.adoc[leveloffset=+1]
+
 include::platform/proc-cli-get-controller-pwd-decode.adoc[leveloffset=+1]
 
 
 [role="_additional-resources"]
 == Additional resources
 
-* For more information on running operators on OpenShift Container Platform, navigate to the link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation] and click the _Operators - Working with Operators in OpenShift Container Platform_ guide.
+* link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/platform/assembly-installing-controller-operator.adoc b/downstream/assemblies/platform/assembly-installing-controller-operator.adoc
@@ -22,7 +22,7 @@ You can use these instructions to configure the {ControllerName} operator on {OC
 
 [NOTE]
 ====
-When an instance of {ControllerName} is removed, the associated PVCs are not automatically deleted. This can cause issues during migration if the new deployment has the same name as the previous one. Therefore, it is recommended that you manually remove old PVCs before deploying a new {ControllerName} instance in the same namespace. See xref:proc-find-delete-PVCs_{context}[Finding and deleting PVCs] for more information.
+When an instance of {ControllerName} is removed, the associated PVCs are not automatically deleted. This can cause issues during migration if the new deployment has the same name as the previous one. Therefore, it is recommended that you manually remove old PVCs before deploying a new {ControllerName} instance in the same namespace. See link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/installing_on_openshift_container_platform/index#proc-find-delete-PVCs_installing-controller-operator[Finding and deleting PVCs] for more information.
 ====
 
 
@@ -34,19 +34,6 @@ When an instance of {ControllerName} is removed, the associated PVCs are not aut
 * For {ControllerName}, a default StorageClass must be configured on the cluster for the operator to dynamically create needed PVCs. This is not necessary if an external PostgreSQL database is configured.
 * For Hub a StorageClass that supports ReadWriteMany must be available on the cluster to dynamically created the PVC needed for the content, redis and api pods. If it is not the default StorageClass on the cluster, you can specify it when creating your AutomationHub object.
 
-//Not relevant for 2.5 EA, commenting out section [gmurray]
-//== Installing the {ControllerName} operator
-//Use this procedure to install the {ControllerName} operator.
-
-//.Procedure
-
-//. Navigate to menu:Operators[Installed Operators], then click on the *Ansible Automation Platform* operator.
-//. Locate the *Automation controller* tab, then click btn:[Create instance].
-
-//You can proceed with configuring the instance using either the Form View or YAML view.
-
-
-//include::platform/proc-creating-controller-form-view.adoc[leveloffset=+2]
 include::platform/proc-configuring-controller-image-pull-policy.adoc[leveloffset=+2]
 
 include::platform/proc-configuring-controller-ldap-security.adoc[leveloffset=+2]
@@ -62,7 +49,7 @@ include::platform/proc-find-delete-PVCs.adoc[leveloffset=+1]
 [role="_additional-resources"]
 == Additional resources
 
-* For more information on running operators on OpenShift Container Platform, navigate to the link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation] and click the _Operators - Working with Operators in OpenShift Container Platform_ guide.
+* link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/platform/assembly-installing-hub-operator.adoc b/downstream/assemblies/platform/assembly-installing-hub-operator.adoc
@@ -67,7 +67,7 @@ include::platform/proc-aap-add-allowed-registries.adoc[leveloffset=+1]
 [role="_additional-resources"]
 == Additional resources
 
-* For more information on running operators on OpenShift Container Platform, navigate to the link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation] and click the _Operators - Working with Operators in OpenShift Container Platform_ guide.
+* link:{BaseURL}/openshift_container_platform/[OpenShift Container Platform product documentation]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
diff --git a/downstream/modules/platform/con-aap-migrate-SAML-users.adoc b/downstream/modules/platform/con-aap-migrate-SAML-users.adoc
@@ -40,4 +40,4 @@ Once you set up the auto migrate functionality, you should be able to login with
 [role="_additional-resources"]
 .Additional resources
 
-Refer to link:https://interact.redhat.com/share/baxthgXBQZ3kSRKPLn5L[{PlatformNameShort} 2.4 to 2.5. Linking accounts post upgrade, and Setting up SAML authentication] for a demonstration of the post upgrade steps.
+link:https://interact.redhat.com/share/baxthgXBQZ3kSRKPLn5L[{PlatformNameShort} 2.4 to 2.5. Linking accounts post upgrade, and Setting up SAML authentication]
diff --git a/downstream/modules/platform/con-aap-migrate-normal-users.adoc b/downstream/modules/platform/con-aap-migrate-normal-users.adoc
@@ -14,4 +14,4 @@ When you upgrade from {PlatformNameShort} 2.4 to 2.5, your existing user account
 
 == Additional resources
 
-* See link:{URLCentralAuth}/gw-managing-access#proc-controller-creating-a-user[Creating a user] for more information on user types.
+* link:{URLCentralAuth}/gw-managing-access#proc-controller-creating-a-user[Creating a user]
diff --git a/downstream/modules/platform/con-operator-upgrade-overview.adoc b/downstream/modules/platform/con-operator-upgrade-overview.adoc
@@ -3,6 +3,7 @@
 [id="operator-upgrade-overview"]
 
 = Overview
+
 You can use this document for help with upgrading {PlatformNameShort} 2.4 to 2.5 on {OCP}.
 This document applies to upgrades of {PlatformNameShort} 2.5 to later versions of 2.5.
 

diff --git a/...ream/modules/platform/con-storage-options-for-operator-installation-on-ocp.adoc b/...ream/modules/platform/con-storage-options-for-operator-installation-on-ocp.adoc
@@ -16,5 +16,5 @@ In addition, {ODFShort} provides a `ReadWriteMany` or S3-compliant implementatio
 [role="_additional-resources"]
 .Additional resources
 
-* link:https://docs.openshift.com/container-platform/{OCPLatest}/storage/persistent_storage/persistent-storage-nfs.html[Persistent storage using NFS] in the {OCPShort} _Storage_ guide
-* IBM's link:https://www.ibm.com/support/pages/how-do-i-create-storage-class-nfs-dynamic-storage-provisioning-openshift-environment[How do I create a storage class for NFS dynamic storage provisioning in an OpenShift environment?]
+* link:https://docs.openshift.com/container-platform/{OCPLatest}/storage/persistent_storage/persistent-storage-nfs.html[Persistent storage using NFS]
+* link:https://www.ibm.com/support/pages/how-do-i-create-storage-class-nfs-dynamic-storage-provisioning-openshift-environment[How do I create a storage class for NFS dynamic storage provisioning in an OpenShift environment?]
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
-* xref:proc-aap-generate-manifest-file[Download the manifest file] from Red Hat Subscription Management. 
+* 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]. 
diff --git a/downstream/modules/platform/proc-aap-create-subscription-allocation.adoc b/downstream/modules/platform/proc-aap-create-subscription-allocation.adoc
@@ -15,4 +15,4 @@ Creating a new subscription allocation allows you to set aside subscriptions and
 
 [role="_additional-resources"]
 .Next steps
-* xref:proc-add-merge-subscriptions[Add the subscriptions] needed for {PlatformNameShort} to run properly.
+* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/installing_on_openshift_container_platform/index#proc-add-merge-subscriptions[Add the subscriptions].
diff --git a/downstream/modules/platform/proc-aap-generate-manifest-file.adoc b/downstream/modules/platform/proc-aap-generate-manifest-file.adoc
@@ -17,4 +17,4 @@ This downloads a file _manifest_<allocation name>_<date>.zip_ to your default do
 
 [role="_additional-resources"]
 .Next steps
-* link:{URLCentralAuth}/assembly-gateway-licensing#proc-aap-activate-with-manifest[Upload the manifest file] to activate {PlatformName}.
+* link:{URLCentralAuth}/assembly-gateway-licensing#proc-aap-activate-with-manifest[Upload the manifest file].
diff --git a/downstream/modules/platform/proc-access-hub-operator-ui.adoc b/downstream/modules/platform/proc-access-hub-operator-ui.adoc
@@ -11,6 +11,7 @@ You can access the {HubName} through the {Gateway} or through the following proc
 . Navigate to menu:Networking[Routes].
 . Under *Location*, click on the URL for your {HubName} instance.
 
+.Verification
 The {HubName} user interface launches where you can sign in with the administrator credentials specified during the operator configuration process.
 
 [NOTE]

diff --git a/downstream/modules/platform/proc-account-linking.adoc b/downstream/modules/platform/proc-account-linking.adoc
@@ -13,12 +13,13 @@ The first time you log in to {PlatformNameShort} 2.5, the platform searches thro
 
 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. 
 
+If you have completed the upgrade process and have a legacy {PlatformNameShort} subscription, follow the account linking procedure below to migrate your account to {PlatformNameShort} 2.5.
+
 .Prerequisites
 
 * You have completed the upgrade process and have a legacy {PlatformNameShort} account and credentials.
 
 .Procedure
-If you have completed the upgrade process and have a legacy {PlatformNameShort} subscription, follow the account linking procedure below to migrate your account to {PlatformNameShort} 2.5.
 
 . Navigate to the login page for {PlatformNameShort}. 
 . In the login modal, select either *I have an {ControllerName} account* or *I have an {HubName} account* based on the credentials you have. 
@@ -32,21 +33,21 @@ If you are logging in using OIDC credentials, see link:https://access.redhat.com
 . If you have successfully linked your account, the next 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 btn:[Link] to link them to your centralized {Gateway} account.
 . Click btn:[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:
-
+* 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 btn:[More Actions] icon *{MoreActionsIcon}* > *Link user accounts*. 
 . Enter the credentials for the account that you want to link. 
 
+.Troubleshooting
+
 If you encounter an error message telling you that your account could not be authenticated, contact your platform administrator. 
 
 [NOTE]
 ====
 If you log into {PlatformNameShort} for the first time and are prompted to change your username, this is an indication that another user has already logged into {PlatformNameShort} with the same username. To proceed with account migration, follow the prompts to change your username. {PlatformNameShort} uses your password to authenticate which account or accounts belong to you.
 ====
 
-.A diagram of the account linking flow
+*A diagram of the account linking flow*
 image:account-linking-flow.png[Account linking flow]
 
 After you have migrated your user account, you can manage your account from the *Access Management* menu. See link:{URLCentralAuth}/gw-managing-access[Managing access with role based access control]. 
diff --git a/downstream/modules/platform/proc-add-controller-access-token.adoc b/downstream/modules/platform/proc-add-controller-access-token.adoc
@@ -6,23 +6,26 @@
 
 To connect {OperatorResourceShort} with {Gateway} you must create a Kubernetes secret with the connection information for your {ControllerName} instance.
 
+Use the following procedure to create an OAuth2 token for your user in the {Gateway} UI.
+
 [NOTE]
 ====
 You can only create OAuth 2 Tokens for your own user through the API or UI, which means you can only configure or view tokens from your own user profile.
 ====
 
 .Procedure
-To create an OAuth2 token for your user in the {Gateway} UI:
+
 
 . Log in to {OCP}. 
 . In the navigation panel, select menu:Access Management[Users].
 . Select the username you want to create a token for.
 . Select menu:Tokens[Automation Execution]
 . Click btn:[Create Token].
 . You can leave *Applications* empty. Add a description and select *Read* or *Write* for the *Scope*.
-
++
 [NOTE]
 ====
 Make sure you provide a valid user when creating tokens. 
 Otherwise, you get an error message that you tried to issue the command without either specifying a user, or supplying a username that does not exist.
-====
+====
++
diff --git a/downstream/modules/platform/proc-add-operator-execution-nodes.adoc b/downstream/modules/platform/proc-add-operator-execution-nodes.adoc
@@ -53,4 +53,4 @@ watch podman ps
 ----
 
 .Additional resources
-* For more information about managing instance groups see the link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/using_automation_execution/index#controller-instance-groups[Managing Instance Groups] section of the Automation Controller User Guide.
+* link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html-single/using_automation_execution/index#controller-instance-groups[Managing Instance Groups]
diff --git a/downstream/modules/platform/proc-attaching-subscriptions.adoc b/downstream/modules/platform/proc-attaching-subscriptions.adoc
@@ -34,21 +34,6 @@ $ sudo subscription-manager list --available --all | grep "Ansible Automation Pl
 Do not use MCT4022 as a `pool_id` for your subscription because it can cause {PlatformNameShort} subscription attachment to fail.
 ====
 +
-.Example
-An example output of the `*subsciption-manager list*` command. Obtain the `pool_id` as seen in the `Pool ID:` section:
-+
------
-Subscription Name: Red Hat Ansible Automation, Premium (5000 Managed Nodes)
-  Provides: Red Hat Ansible Engine
-  Red Hat Ansible Automation Platform
-  SKU: MCT3695
-  Contract: ````
-  Pool ID: <pool_id>
-  Provides Management: No
-  Available: 4999
-  Suggested: 1
------
-+
 . Attach the subscription:
 +
 -----

diff --git a/downstream/modules/platform/proc-cli-get-controller-address.adoc b/downstream/modules/platform/proc-cli-get-controller-address.adoc
@@ -12,11 +12,12 @@ The route inherits the name that you assigned to the {Gateway} object in the YAM
 .Procedure
 
 * Use the following command to fetch the routes:
-
++
 [subs="+quotes"]
 -----
 oc get routes -n __<platform_namespace>__
 -----
++
 
 .Verification 
 

diff --git a/downstream/modules/platform/proc-configuring-controller-image-pull-policy.adoc b/downstream/modules/platform/proc-configuring-controller-image-pull-policy.adoc
@@ -3,6 +3,7 @@
 [id="proc-configuring-controller-image-pull-policy_{context}"]
 
 = Configuring your controller image pull policy
+
 Use this procedure to configure the image pull policy on your {ControllerName}.
 
 .Procedure

diff --git a/downstream/modules/platform/proc-controller-ingress-options.adoc b/downstream/modules/platform/proc-controller-ingress-options.adoc
@@ -19,12 +19,12 @@ The {OperatorPlatformNameShort} installation form allows you to further configur
 . Under *Ingress annotations*, enter any annotations to add to the ingress.
 . Under *Ingress TLS secret*, click the drop-down menu and select a secret from the list.
 
+.Verification
+
 After you have configured your {ControllerName} operator, click btn:[Create] at the bottom of the form view. {OCP} creates the pods. This may take a few minutes.
 
 You can view the progress by navigating to menu:Workloads[Pods] and locating the newly created instance.
 
-.Verification
-
 Verify that the following operator pods provided by the {PlatformNameShort} Operator installation from {ControllerName} are running:
 [cols="a,a,a,a"]
 |===

diff --git a/downstream/modules/platform/proc-create-a-connection-secret.adoc b/downstream/modules/platform/proc-create-a-connection-secret.adoc
@@ -3,6 +3,7 @@
 [id="proc-create-connection-secret_{context}"]
 
 = Creating a {ControllerName} connection secret for {OperatorResourceShort}
+
 To make your connection information available to the {OperatorResourceShort}, create a k8s secret with the token and host value. 
 
 .Procedure

diff --git a/downstream/modules/platform/proc-create-an-ansiblejob.adoc b/downstream/modules/platform/proc-create-an-ansiblejob.adoc
@@ -3,6 +3,7 @@
 [id="proc-create-an-ansiblejob_{context}"]
 
 = Creating an AnsibleJob custom resource
+
 An AnsibleJob custom resource launches a job in the {ControllerName} instance specified in the Kubernetes secret ({ControllerName} host URL, token).
 You can launch an automation job on {ControllerName} by creating an AnsibleJob resource.
 

diff --git a/downstream/modules/platform/proc-hub-ingress-options.adoc b/downstream/modules/platform/proc-hub-ingress-options.adoc
@@ -19,12 +19,12 @@ The {OperatorPlatformNameShort} installation form allows you to further configur
 . Under *Ingress annotations*, enter any annotations to add to the ingress.
 . Under *Ingress TLS secret*, click the drop-down menu and select a secret from the list.
 
+.Verification
+
 After you have configured your {HubName} operator, click btn:[Create] at the bottom of the form view. {OCP} creates the pods. This may take a few minutes.
 
 You can view the progress by navigating to menu:Workloads[Pods] and locating the newly created instance.
 
-.Verification
-
 Verify that the following operator pods provided by the {PlatformNameShort} Operator installation from {HubName} are running:
 [cols="a,a,a"]
 |===

diff --git a/downstream/modules/platform/proc-install-aap-operator.adoc b/downstream/modules/platform/proc-install-aap-operator.adoc
@@ -7,18 +7,17 @@
 . Navigate to menu:Operators[OperatorHub].
 . Search for {PlatformNameShort} and click btn:[Install].
 . Select an *Update Channel*:
-+
 * *stable-2.x*: installs a namespace-scoped operator, which limits deployments of {HubName} and {ControllerName} instances to the namespace the operator is installed in, this is suitable for most cases.
 The stable-2.x channel does not require administrator privileges and utilizes fewer resources because it only monitors a single namespace.
 * *stable-2.x-cluster-scoped*: installs the {OperatorPlatformNameShort} in a single namespace that manages {PlatformNameShort} custom resources and deployments in all namespaces.
 The {OperatorPlatformNameShort} requires administrator privileges for all namespaces in the cluster.
 . Select *Installation Mode*, *Installed Namespace*, and *Approval Strategy*.
 . Click btn:[Install].
 
-The installation process begins. When installation finishes, a modal appears notifying you that the {OperatorPlatformNameShort} is installed in the specified namespace.
-
 .Verification
 
+The installation process begins. When installation finishes, a modal appears notifying you that the {OperatorPlatformNameShort} is installed in the specified namespace.
+
 * Click btn:[View Operator] to view your newly installed {OperatorPlatformNameShort} and verify the following operator custom resources are present:
 
 [cols="a,a,a,a"]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -14,4 +14,4 @@ When you upgrade from {PlatformNameShort} 2.4 to 2.5, your existing user account

		== Additional resources

		* See link:{URLCentralAuth}/gw-managing-access#proc-controller-creating-a-user[Creating a user] for more information on user types.
		* link:{URLCentralAuth}/gw-managing-access#proc-controller-creating-a-user[Creating a user]