ansible · jklech-work · May 15, 2026
diff --git a/downstream/assemblies/devtools/assembly-rhdh-configure.adoc b/downstream/assemblies/devtools/assembly-rhdh-configure.adoc
@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-configure_{context}"]
+= Configuring the {AAPRHDHShort}
+
+:context: rhdh-configure
+
+[role="_abstract"]
+After installing the {AAPRHDHShort}, configure them to connect to your {PlatformName} instance and enable software templates.
+
+Add the following configuration to your {RHDH} custom ConfigMap (for example, `app-config-rhdh`).
+
+For Operator deployments, edit the ConfigMap directly.
+For Helm deployments, edit the ConfigMap referenced in `upstream.backstage.extraAppConfig`.
+
+include::devtools/proc-rhdh-configure-devtools-server.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-configure-aap-details.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-add-plugin-software-templates.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-configure-rbac.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-full-examples.adoc b/downstream/assemblies/devtools/assembly-rhdh-full-examples.adoc
@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-full-examples_{context}"]
+= Full configuration examples
+
+:context: rhdh-full-examples
+
+[role="_abstract"]
+
+include::devtools/ref-rhdh-full-aap-configmap-example.adoc[leveloffset=+1]
+
+include::devtools/ref-rhdh-full-operator-cr-example.adoc[leveloffset=+1]
+
+include::devtools/ref-rhdh-full-helm-chart-ansible-plugins.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-http-deprecated.adoc b/downstream/assemblies/devtools/assembly-rhdh-http-deprecated.adoc
@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-http-deprecated_{context}"]
+= Installing {AAPRHDHShort} using an HTTP plug-in registry (deprecated)
+
+:context: rhdh-http-deprecated
+
+include::devtools/con-rhdh-http-registry-deprecated.adoc[leveloffset=+1]
+
+include::devtools/proc_downloading-the-ansible-plug-ins-files.adoc[leveloffset=+1]
+
+include::devtools/proc_creating-a-registry-for-the-ansible-plug-ins.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-install-plugins-http-registry.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-install.adoc b/downstream/assemblies/devtools/assembly-rhdh-install.adoc
@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-install_{context}"]
+= Installing the {AAPRHDHShort}
+
+:context: rhdh-install
+
+[role="_abstract"]
+Install the {AAPRHDH} on {OCPShort} using OCI container delivery.
+{RHDH} pulls the plug-ins directly from `registry.redhat.io` as OCI artifacts during startup.
+
+include::devtools/proc-rhdh-create-registry-auth-secret.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-configure-dynamic-plugins.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-add-devtools-sidecar.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-verify-plugin-installation.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-intro.adoc b/downstream/assemblies/devtools/assembly-rhdh-intro.adoc
@@ -8,15 +8,7 @@ ifdef::context[:parent-context: {context}]
 [role="_abstract"]
 {AAPRHDH} (RHDH) offer a tailored RHDH interface, curated learning paths, and software templates for creating projects, all while linking to supported development environments like OpenShift Dev Spaces and Ansible Automation Platform.
 
-include::devtools/ref-rhdh-about-rhdh.adoc[leveloffset=+1]
-
-include::devtools/ref-rhdh-about-plugins.adoc[leveloffset=+1]
-
-// Commenting out architecture diagram because updates are needed.
-// Un-comment this when architecture diagram is available.
-// include::devtools/ref-rhdh-architecture.adoc[leveloffset=+1]
-
-// include::devtools/ref-devtools-components.adoc[leveloffset=+1]
+include::devtools/con-rhdh-ansible-plugins-overview.adoc[leveloffset=+1]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

diff --git a/downstream/assemblies/devtools/assembly-rhdh-ocp-configure-optional.adoc b/downstream/assemblies/devtools/assembly-rhdh-ocp-configure-optional.adoc
@@ -2,15 +2,11 @@ ifdef::context[:parent-context-of-rhdh-ocp-configure-optional: {context}]
 :_mod-docs-content-type: ASSEMBLY
 [id="rhdh-ocp-configure-optional_{context}"]
 
-= Optional configuration for Ansible plug-ins
+= Optional configuration
 
 :context: rhdh-ocp-configure-optional_{parent-context-of-rhdh-ocp-configure-optional}
 [role="_abstract"]
-Enable {RHDH} authentication and configure optional integrations, such as connecting to OpenShift Dev Spaces or specifying a {PrivateHubName} URL. While optional, these configurations enhance the user experience and functionality of the plug-ins.
-
-include::devtools/proc-rhdh-enable-rhdh-authentication.adoc[leveloffset=+1]
-
-include::devtools/proc-rhdh-configure-optional-integrations.adoc[leveloffset=+1]
+Enable optional integrations to enhance the user experience and functionality of the {AAPRHDHShort}.
 
 include::devtools/proc-rhdh-configure-devspaces.adoc[leveloffset=+1]
 

diff --git a/downstream/assemblies/devtools/assembly-rhdh-prerequisites.adoc b/downstream/assemblies/devtools/assembly-rhdh-prerequisites.adoc
@@ -0,0 +1,15 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-prerequisites_{context}"]
+= Prerequisites
+
+:context: rhdh-prerequisites
+
+include::devtools/con-rhdh-install-ocp-prereqs.adoc[leveloffset=+1]
+
+include::devtools/con-rhdh-recommended-preconfig.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-uninstall.adoc b/downstream/assemblies/devtools/assembly-rhdh-uninstall.adoc
@@ -0,0 +1,15 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-uninstall_{context}"]
+= Uninstalling the {AAPRHDHShort}
+
+:context: rhdh-uninstall
+
+include::devtools/proc-rhdh-uninstall-ocp-helm.adoc[leveloffset=+1]
+
+include::devtools/proc-rhdh-uninstall-operator.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/assemblies/devtools/assembly-rhdh-upgrade.adoc b/downstream/assemblies/devtools/assembly-rhdh-upgrade.adoc
@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-rhdh-upgrade_{context}"]
+= Upgrading the {AAPRHDHShort}
+
+:context: rhdh-upgrade
+
+[role="_abstract"]
+Upgrade the {AAPRHDH} to a newer version.
+
+include::devtools/proc-rhdh-upgrade-oci.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/downstream/attributes/attributes.adoc b/downstream/attributes/attributes.adoc
@@ -156,7 +156,7 @@
 :AAPRHDH: Ansible plug-ins for Red Hat Developer Hub
 :AAPRHDHShort: Ansible plug-ins
 :RHDH: Red Hat Developer Hub
-:RHDHVers: 1.6
+:RHDHVers: 1.9
 :RHDHShort: RHDH
 :SelfService: self-service automation portal
 :SelfServiceShort: self-service automation portal

diff --git a/downstream/modules/devtools/con-rhdh-ansible-plugins-overview.adoc b/downstream/modules/devtools/con-rhdh-ansible-plugins-overview.adoc
@@ -0,0 +1,38 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="rhdh-ansible-plugins-overview_{context}"]
+= {AAPRHDH}
+
+[role="_abstract"]
+{AAPRHDH} deliver an Ansible-first user experience that simplifies the automation experience for Ansible users of all skill levels.
+
+The Ansible plug-ins provide:
+
+* A customized home page and navigation tailored to Ansible users.
+* Software templates for creating Ansible playbook and collection projects that follow best practices.
+* Curated Ansible learning paths to help users new to Ansible.
+* Links to supported development environments and tools with opinionated configurations.
+
+The `automation-portal` OCI bundle includes the following plug-ins:
+
+.Ansible plug-ins for {RHDH}
+[cols="1,1,2",options="header"]
+|===
+| Plug-in | Type | Purpose
+
+| `ansible-plugin-backstage-rhaap`
+| Frontend
+| Ansible landing page, navigation, and UI components
+
+| `ansible-plugin-backstage-self-service`
+| Frontend
+| Scaffolder field extensions for AAP token and resource picker
+
+| `ansible-plugin-scaffolder-backend-module-backstage-rhaap`
+| Backend
+| Scaffolder actions for creating Ansible content
+
+| `ansible-backstage-plugin-catalog-backend-module-rhaap`
+| Backend
+| Catalog entity provider for syncing AAP organizations, users, and teams
+|===
diff --git a/downstream/modules/devtools/con-rhdh-http-registry-deprecated.adoc b/downstream/modules/devtools/con-rhdh-http-registry-deprecated.adoc
@@ -0,0 +1,17 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="rhdh-http-registry-deprecated_{context}"]
+= Installing {AAPRHDHShort} using an HTTP plug-in registry (deprecated)
+
+[role="_abstract"]
+
+[IMPORTANT]
+====
+The HTTP plug-in registry method is deprecated and will be removed in a future release.
+Red{nbsp}Hat recommends using OCI-based plug-in delivery as described in the main installation procedure.
+For disconnected environments, use OCI image mirroring instead of an HTTP registry.
+See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{RHDHVers}/html-single/configuring_dynamic_plugins_in_red_hat_developer_hub/index#configuring-dynamic-plugins-with-an-oci-registry-in-a-restricted-network[Configuring dynamic plugins with an OCI registry in a restricted network] in the {RHDH} documentation.
+====
+
+The following procedures describe how to install the {AAPRHDHShort} using an HTTP plug-in registry hosted in your {OCPShort} cluster.
+This method requires downloading plug-in tarballs, creating an HTTP registry in the cluster, and referencing the plug-ins by HTTP URL with SHA integrity hashes.
diff --git a/downstream/modules/devtools/proc-rhdh-add-devtools-sidecar.adoc b/downstream/modules/devtools/proc-rhdh-add-devtools-sidecar.adoc
@@ -0,0 +1,85 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="rhdh-add-devtools-sidecar_{context}"]
+= Adding the Ansible Developer Tools sidecar container
+
+[role="_abstract"]
+After the plug-ins load, add the Ansible Developer Tools container (`ansible-devtools-server`) as a sidecar container to the {RHDH} pod.
+
+[NOTE]
+====
+The `ansible-dev-tools-rhel9` container image is hosted on `registry.redhat.io` and requires {PlatformName} subscription entitlements.
+If your {OCPShort} cluster's global pull secret does not include AAP-entitled credentials, you must create an `imagePullSecrets` entry in the deployment patch.
+You can reuse the same `auth.json` credentials created for the dynamic plug-ins registry secret:
+
+[source,terminal]
+----
+$ oc create secret docker-registry rhdh-registry-pull-secret \
+    --from-file=.dockerconfigjson=auth.json \
+    -n <your_rhdh_namespace>
+----
+
+Then add the `imagePullSecrets` field to the deployment patch as shown in the examples below.
+====
+
+.Operator installation
+
+Modify the Backstage custom resource to add a `containers` block in the `spec.deployment.patch.spec.template.spec` block:
+
+[source,yaml,subs="+attributes"]
+----
+apiVersion: rhdh.redhat.com/v1alpha5
+kind: Backstage
+metadata:
+  name: developer-hub
+spec:
+  deployment:
+    patch:
+      spec:
+        template:
+          spec:
+            imagePullSecrets:
+              - name: rhdh-registry-pull-secret
+            containers:
+              - command:
+                  - adt
+                  - server
+                image: registry.redhat.io/ansible-automation-platform-{PlatformVers}/ansible-dev-tools-rhel9:latest
+                imagePullPolicy: Always
+                ports:
+                  - containerPort: 8000
+                    protocol: TCP
+----
+
+Click btn:[Save].
+
+.Helm chart installation
+
+Update the `extraContainers` section in the Helm chart YAML:
+
+[source,yaml,subs="+attributes"]
+----
+upstream:
+  backstage:
+    # ...
+    extraContainers:
+      - command:
+          - adt
+          - server
+        image: >-
+          registry.redhat.io/ansible-automation-platform-{PlatformVers}/ansible-dev-tools-rhel9:latest
+        imagePullPolicy: IfNotPresent
+        name: ansible-devtools-server
+        ports:
+          - containerPort: 8000
+    # ...
+----
+
+[NOTE]
+=====
+The image pull policy is `imagePullPolicy: IfNotPresent`.
+The image is pulled only if it does not already exist on the node.
+Update it to `imagePullPolicy: Always` if you always want to use the latest image.
+=====
+
+Click btn:[Upgrade].
diff --git a/downstream/modules/devtools/proc-rhdh-add-plugin-software-templates.adoc b/downstream/modules/devtools/proc-rhdh-add-plugin-software-templates.adoc
@@ -27,4 +27,4 @@ data:
 [role="_additional-resources"]
 .Additional resources
 
-* link:{BaseURL}/red_hat_developer_hub/1.2/html-single/administration_guide_for_red_hat_developer_hub/assembly-admin-templates#assembly-admin-templates[Managing templates]
+* link:{BaseURL}/red_hat_developer_hub/{RHDHVers}/html-single/administration_guide_for_red_hat_developer_hub/assembly-admin-templates#assembly-admin-templates[Managing templates]
diff --git a/downstream/modules/devtools/proc-rhdh-configure-devtools-server.adoc b/downstream/modules/devtools/proc-rhdh-configure-devtools-server.adoc
@@ -8,8 +8,6 @@ The `creatorService` URL is required for the {AAPRHDHShort} to provision new pro
 
 .Procedure
 
-. Edit your custom {RHDH} config map, `app-config-rhdh`, that you created in
-link:{URLPluginRHDHInstall}/rhdh-install-ocp-helm_aap-plugin-rhdh-installing#rhdh-add-custom-configmap_rhdh-ocp-required-installation[Adding a custom ConfigMap].
 . Add the following code to your {RHDH} `app-config-rhdh.yaml` file.
 +
 ----