From bac54c21ef5ac6a910a6e756fdb39b931e131dc4 Mon Sep 17 00:00:00 2001 From: Jaroslav Klech Date: Fri, 15 May 2026 16:48:30 +0200 Subject: [PATCH] =?UTF-8?q?AAP-75442:=20Rewrite=20RHDH=20plug-ins=20instal?= =?UTF-8?q?l=20guide=20=E2=80=94=20OCI=20primary,=20HTTP=20deprecated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full guide replacement for Installing Ansible plug-ins for Red Hat Developer Hub. Unifies separate Helm/Operator chapters into single chapters with inline deployment-method variants. OCI container delivery is the primary installation method; HTTP plug-in registry is relocated to a deprecated appendix. Changes: - New unified install/configure/uninstall/upgrade assemblies - 4 plug-ins documented (expanded from 2) - OCI registry auth secret procedure with Helm/Operator variants - ADT sidecar image path parameterized with {PlatformVers} - HTTP registry procedures consolidated in deprecated appendix - Upgrade chapter carries forward with OCI-first approach - Telemetry chapter carried forward as-is - RHDHVers attribute updated from 1.6 to 1.9 - Fixed stale xrefs, hardcoded versions, and incomplete examples in reused modules This PR will NOT be merged. Content for DITA/AEM conversion. --- .../devtools/assembly-rhdh-configure.adoc | 27 ++++ .../devtools/assembly-rhdh-full-examples.adoc | 19 +++ .../assembly-rhdh-http-deprecated.adoc | 19 +++ .../devtools/assembly-rhdh-install.adoc | 23 ++++ .../devtools/assembly-rhdh-intro.adoc | 10 +- .../assembly-rhdh-ocp-configure-optional.adoc | 8 +- .../devtools/assembly-rhdh-prerequisites.adoc | 15 +++ .../devtools/assembly-rhdh-uninstall.adoc | 15 +++ .../devtools/assembly-rhdh-upgrade.adoc | 16 +++ downstream/attributes/attributes.adoc | 2 +- .../con-rhdh-ansible-plugins-overview.adoc | 38 ++++++ .../con-rhdh-http-registry-deprecated.adoc | 17 +++ .../proc-rhdh-add-devtools-sidecar.adoc | 85 +++++++++++++ ...oc-rhdh-add-plugin-software-templates.adoc | 2 +- .../proc-rhdh-configure-devtools-server.adoc | 2 - .../proc-rhdh-configure-dynamic-plugins.adoc | 117 ++++++++++++++++++ .../devtools/proc-rhdh-configure-rbac.adoc | 2 +- ...proc-rhdh-create-registry-auth-secret.adoc | 87 +++++++++++++ ...oc-rhdh-install-plugins-http-registry.adoc | 108 ++++++++++++++++ .../proc-rhdh-uninstall-ocp-helm.adoc | 23 +--- .../proc-rhdh-uninstall-operator.adoc | 21 ++++ .../devtools/proc-rhdh-upgrade-oci.adoc | 27 ++++ .../proc-rhdh-verify-plugin-installation.adoc | 24 ++++ .../ref-rhdh-full-aap-configmap-example.adoc | 4 +- ...-rhdh-full-helm-chart-ansible-plugins.adoc | 34 +++-- .../ref-rhdh-full-operator-cr-example.adoc | 53 ++++++++ .../aap-plugin-rhdh-install/master.adoc | 31 ++--- 27 files changed, 767 insertions(+), 62 deletions(-) create mode 100644 downstream/assemblies/devtools/assembly-rhdh-configure.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-full-examples.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-http-deprecated.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-install.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-prerequisites.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-uninstall.adoc create mode 100644 downstream/assemblies/devtools/assembly-rhdh-upgrade.adoc create mode 100644 downstream/modules/devtools/con-rhdh-ansible-plugins-overview.adoc create mode 100644 downstream/modules/devtools/con-rhdh-http-registry-deprecated.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-add-devtools-sidecar.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-configure-dynamic-plugins.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-create-registry-auth-secret.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-install-plugins-http-registry.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-uninstall-operator.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-upgrade-oci.adoc create mode 100644 downstream/modules/devtools/proc-rhdh-verify-plugin-installation.adoc create mode 100644 downstream/modules/devtools/ref-rhdh-full-operator-cr-example.adoc diff --git a/downstream/assemblies/devtools/assembly-rhdh-configure.adoc b/downstream/assemblies/devtools/assembly-rhdh-configure.adoc new file mode 100644 index 0000000000..5b7ad0f78f --- /dev/null +++ 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 new file mode 100644 index 0000000000..b105ef3905 --- /dev/null +++ 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 new file mode 100644 index 0000000000..80e47f2ed9 --- /dev/null +++ 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 new file mode 100644 index 0000000000..a699df88a9 --- /dev/null +++ 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 index 83d73db6fe..f81e8b93a9 100644 --- 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 index 408cac7584..97bb163785 100644 --- 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 new file mode 100644 index 0000000000..882044b15c --- /dev/null +++ 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 new file mode 100644 index 0000000000..8db4c52aa7 --- /dev/null +++ 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 new file mode 100644 index 0000000000..3ad7ecbfef --- /dev/null +++ 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 index a4ee4ffda8..adb72c472a 100644 --- 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 new file mode 100644 index 0000000000..064c548ef1 --- /dev/null +++ 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 new file mode 100644 index 0000000000..65a72238d2 --- /dev/null +++ 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 new file mode 100644 index 0000000000..fb63d2893b --- /dev/null +++ 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 +---- + +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 index 4f74e9546a..701a6400df 100644 --- 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 index 1b6b9a4358..7fcad650f0 100644 --- 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. + ---- diff --git a/downstream/modules/devtools/proc-rhdh-configure-dynamic-plugins.adoc b/downstream/modules/devtools/proc-rhdh-configure-dynamic-plugins.adoc new file mode 100644 index 0000000000..78ec98b043 --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-configure-dynamic-plugins.adoc @@ -0,0 +1,117 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-configure-dynamic-plugins_{context}"] += Configuring the dynamic plug-ins + +[role="_abstract"] +After creating the registry authentication secret, add the Ansible plug-ins to your dynamic plug-ins configuration. + +.Operator installation + +In the `data.dynamic-plugins.yaml.plugins` block, add the Ansible plug-ins using OCI references: + +[source,yaml,subs="+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-rhaap + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-rhaap: + appIcons: + - importName: AnsibleLogo + name: AnsibleLogo + dynamicRoutes: + - importName: AnsiblePage + menuItem: + icon: AnsibleLogo + text: Ansible + path: /ansible + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-self-service + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-self-service: + scaffolderFieldExtensions: + - importName: AAPTokenFieldExtension + - importName: AAPResourcePickerExtension + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-backstage-plugin-catalog-backend-module-rhaap + pluginConfig: {} + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-scaffolder-backend-module-backstage-rhaap + pluginConfig: + dynamicPlugins: + backend: + ansible.plugin-scaffolder-backend-module-backstage-rhaap: +---- + +Replace `__` with the Ansible plug-ins image tag for your release (for example, `2.2`). + +.Helm chart installation + +Update the Helm chart configuration under the `plugins` section: + +[source,yaml,subs="+attributes"] +---- +global: + # ... + dynamic: + # ... + plugins: + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-rhaap + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-rhaap: + appIcons: + - importName: AnsibleLogo + name: AnsibleLogo + dynamicRoutes: + - importName: AnsiblePage + menuItem: + icon: AnsibleLogo + text: Ansible + path: /ansible + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-self-service + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-self-service: + scaffolderFieldExtensions: + - importName: AAPTokenFieldExtension + - importName: AAPResourcePickerExtension + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-backstage-plugin-catalog-backend-module-rhaap + pluginConfig: {} + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-scaffolder-backend-module-backstage-rhaap + pluginConfig: + dynamicPlugins: + backend: + ansible.plugin-scaffolder-backend-module-backstage-rhaap: +---- + +Replace `__` with the Ansible plug-ins image tag for your release (for example, `2.2`). + +Click btn:[Upgrade]. diff --git a/downstream/modules/devtools/proc-rhdh-configure-rbac.adoc b/downstream/modules/devtools/proc-rhdh-configure-rbac.adoc index 21b3f78b18..70cd537d2f 100644 --- a/downstream/modules/devtools/proc-rhdh-configure-rbac.adoc +++ b/downstream/modules/devtools/proc-rhdh-configure-rbac.adoc @@ -32,5 +32,5 @@ data: + For more information about permission policies and managing RBAC, refer to the link:{BaseURL}/red_hat_developer_hub/{RHDHVers}/html-single/authorization_in_red_hat_developer_hub/index[_Authorization in {RHDH}_] -guide for Red Hat Developer Hub. +guide. diff --git a/downstream/modules/devtools/proc-rhdh-create-registry-auth-secret.adoc b/downstream/modules/devtools/proc-rhdh-create-registry-auth-secret.adoc new file mode 100644 index 0000000000..1869175890 --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-create-registry-auth-secret.adoc @@ -0,0 +1,87 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-create-registry-auth-secret_{context}"] += Creating the registry authentication secret + +[role="_abstract"] +{RHDH} pulls the Ansible plug-ins directly from `registry.redhat.io` as OCI artifacts during startup. +This requires a registry authentication secret in the same {OCPShort} project as your {RHDH} deployment. + +.Procedure + +. Log in to the container image registry: ++ +[source,terminal] +---- +$ podman login --authfile auth.json registry.redhat.io +---- ++ +To authenticate to multiple registries, run `podman login` for each registry. +The `auth.json` file accumulates credentials for all registries you log in to. + +. Create a secret from the `auth.json` file in the same {OCPShort} project as your {RHDH} deployment. ++ +For an Operator-based deployment: ++ +[source,terminal] +---- +$ oc create secret generic dynamic-plugins-registry-auth \ + --from-file=auth.json=auth.json \ + -n +---- ++ +For a Helm-based deployment: ++ +[source,terminal] +---- +$ oc create secret generic -dynamic-plugins-registry-auth \ + --from-file=auth.json=auth.json \ + -n +---- ++ +Replace `__` with your Helm release name. + ++ +[IMPORTANT] +==== +The secret name is fixed. +The {RHDH} Operator and Helm chart expect these exact names. +You cannot use a custom name. +==== ++ +.Secret names by deployment method +[cols="1,1",options="header"] +|=== +| Deployment method | Secret name + +| Operator +| `dynamic-plugins-registry-auth` + +| Helm chart +| `__-dynamic-plugins-registry-auth` +|=== + ++ +[NOTE] +==== +For disconnected or restricted network environments, mirror the `automation-portal` OCI image to an internal registry and use OCI references pointing to that registry instead. +For mirroring procedures, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{RHDHVers}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index#assembly-install-dynamic-plugins-rhdh_title-plugins-rhdh-about[Mirroring dynamic plugin OCI artifacts for deployments in restricted environments] in the {RHDH} documentation. +==== + +.Verification + +Verify that the secret exists in the project. + +For an Operator-based deployment: + +[source,terminal] +---- +$ oc get secret dynamic-plugins-registry-auth -n +---- + +For a Helm-based deployment: + +[source,terminal] +---- +$ oc get secret -dynamic-plugins-registry-auth -n +---- diff --git a/downstream/modules/devtools/proc-rhdh-install-plugins-http-registry.adoc b/downstream/modules/devtools/proc-rhdh-install-plugins-http-registry.adoc new file mode 100644 index 0000000000..e7515d3472 --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-install-plugins-http-registry.adoc @@ -0,0 +1,108 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-install-plugins-http-registry_{context}"] += Installing the plug-ins from the HTTP registry + +[role="_abstract"] +Add the {AAPRHDHShort} from the HTTP registry to your {RHDH} dynamic plug-in configuration. + +For each plug-in, you need the HTTP URL to the `.tgz` file in the registry and the SHA-512 integrity hash from the corresponding `.integrity` file. + +.Operator installation + +Add the plug-ins to your dynamic plug-ins ConfigMap (for example, `rhaap-dynamic-plugins-config`). +Replace `__` with the correct plug-in version. +Use the SHA-512 hash from the corresponding `.integrity` file for each `integrity` value. + +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: rhaap-dynamic-plugins-config +data: + dynamic-plugins.yaml: | + # ... + plugins: + - disabled: false + package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-dynamic-.tgz' + integrity: + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-rhaap: + appIcons: + - importName: AnsibleLogo + name: AnsibleLogo + dynamicRoutes: + - importName: AnsiblePage + menuItem: + icon: AnsibleLogo + text: Ansible + path: /ansible + - disabled: false + package: >- + http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-dynamic-.tgz + integrity: + pluginConfig: + dynamicPlugins: + backend: + ansible.plugin-scaffolder-backend-module-backstage-rhaap: null +---- + +Reference this ConfigMap in your `Backstage` CR under `spec.application.dynamicPluginsConfigMapName`. + +.Helm chart installation + +In the {OCPShort} Developer UI, navigate to *Helm* > *developer-hub* > *Actions* > *Upgrade* > *Yaml view*. +Add the plug-ins under the `global.dynamic.plugins` section. +Replace `__` with the correct plug-in version. +Use the SHA-512 hash from the corresponding `.integrity` file for each `integrity` value. + +[source,yaml] +---- +global: + # ... + plugins: + - disabled: false + integrity: + package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-dynamic-.tgz' + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-rhaap: + appIcons: + - importName: AnsibleLogo + name: AnsibleLogo + dynamicRoutes: + - importName: AnsiblePage + menuItem: + icon: AnsibleLogo + text: Ansible + path: /ansible + - disabled: false + integrity: + package: >- + http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-dynamic-.tgz + pluginConfig: + dynamicPlugins: + backend: + ansible.plugin-scaffolder-backend-module-backstage-rhaap: null +---- + +Click btn:[Upgrade]. +The Developer Hub pods restart and the plug-ins are installed. + +.Verification + +. In the {OCPShort} web console, open the pod details for the {RHDH} deployment. +. Select the *Logs* tab and choose the `install-dynamic-plugins` container from the drop-down list. +. Search the log for the Ansible plug-ins. +A successful installation produces log entries similar to: ++ +[source,terminal] +---- +=> Successfully installed dynamic plugin http://plugin-registry:8080/ansible-plugin-backstage-rhaap-dynamic-.tgz +---- + +After installing the plug-ins from the HTTP registry, continue with the configuration steps in xref:rhdh-configure-devtools-server_rhdh-configure[Configuring the Ansible Dev Tools Server]. diff --git a/downstream/modules/devtools/proc-rhdh-uninstall-ocp-helm.adoc b/downstream/modules/devtools/proc-rhdh-uninstall-ocp-helm.adoc index 2e17cca957..3bb6b39187 100644 --- a/downstream/modules/devtools/proc-rhdh-uninstall-ocp-helm.adoc +++ b/downstream/modules/devtools/proc-rhdh-uninstall-ocp-helm.adoc @@ -14,23 +14,12 @@ To uninstall the Ansible plug-ins from a Helm chart installation, you remove tem . In the OpenShift Developer UI, navigate to menu:Helm[developer-hub > Actions > Upgrade > Yaml view]. -. Remove the Ansible plug-ins configuration under the `plugins` section. +. Remove the Ansible plug-ins configuration under the `plugins` section (all `oci://registry.redhat.io/ansible-automation-platform/automation-portal` entries). + ----- -global: - dynamic: - plugins: - - disabled: false - package: 'oci://registry.redhat.io/ansible-automation-platform/automation-portal:2.1!ansible-plugin-backstage-rhaap' - pluginConfig: - ... - - disabled: false - package: 'oci://registry.redhat.io/ansible-automation-platform/automation-portal:2.1!ansible-plugin-scaffolder-backend-module-backstage-rhaap' - pluginConfig: - ... ----- -+ -For HTTP plug-in registry, remove the `http://plugin-registry:8080/\...` entries instead. +[NOTE] +==== +If you used the deprecated HTTP plug-in registry method, remove the `http://plugin-registry:8080/\...` entries instead. +==== . Remove the `extraContainers` section. @@ -44,7 +33,7 @@ upstream: - adt - server image: >- - registry.redhat.io/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest + registry.redhat.io/ansible-automation-platform-{PlatformVers}/ansible-dev-tools-rhel9:latest imagePullPolicy: IfNotPresent name: ansible-devtools-server ports: diff --git a/downstream/modules/devtools/proc-rhdh-uninstall-operator.adoc b/downstream/modules/devtools/proc-rhdh-uninstall-operator.adoc new file mode 100644 index 0000000000..4269536f5d --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-uninstall-operator.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-uninstall-operator_{context}"] += Uninstalling from an Operator installation + +[role="_abstract"] +To uninstall the {AAPRHDHShort} from an Operator installation, edit the ConfigMaps that reference Ansible. +The deployment auto-reloads when the ConfigMaps are updated. + +.Procedure + +. Remove the Ansible plug-in entries from the `plugins:` block in your dynamic plug-ins ConfigMap. +Alternatively, set `disabled: true` for each Ansible plug-in entry. + +. Edit your custom {RHDH} ConfigMap (for example, `app-config-rhdh`): +.. Remove the Ansible software templates entry from the `catalog.locations` block. +.. Remove the entire `ansible` block (including `creatorService`, `rhaap`, `devSpaces`, and `automationHub` entries). +.. Click btn:[Save]. + +. Modify the Backstage custom resource and remove the `containers` block for the Ansible Developer Tools sidecar from the `spec.deployment.patch.spec.template.spec` block. +Click btn:[Save]. diff --git a/downstream/modules/devtools/proc-rhdh-upgrade-oci.adoc b/downstream/modules/devtools/proc-rhdh-upgrade-oci.adoc new file mode 100644 index 0000000000..9081414f1c --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-upgrade-oci.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-upgrade-oci_{context}"] += Upgrading the {AAPRHDHShort} using OCI delivery + +[role="_abstract"] +To upgrade the {AAPRHDHShort}, update the OCI image tag in your dynamic plug-ins configuration to the new version. + +.Prerequisites + +* You have installed the {AAPRHDHShort} using OCI container delivery. +* You have the new Ansible plug-ins image tag for your release. + +.Procedure + +. Edit your dynamic plug-ins configuration: +* For Operator deployments, edit the dynamic plug-ins ConfigMap (for example, `dynamic-plugins-rhdh`). +* For Helm deployments, in the {OCPShort} Developer UI, navigate to *Helm* > *developer-hub* > *Actions* > *Upgrade* > *Yaml view*. +. Update the `__` value in each `oci://registry.redhat.io/ansible-automation-platform/automation-portal:__` reference to the new version. +. Apply the changes: +* For Operator deployments, click btn:[Save]. The {RHDH} pod restarts automatically with the updated plug-ins. +* For Helm deployments, click btn:[Upgrade]. + +.Verification + +. Check the `install-dynamic-plugin` container logs for the new version. +. Verify that the Ansible plug-in is present in the navigation pane. diff --git a/downstream/modules/devtools/proc-rhdh-verify-plugin-installation.adoc b/downstream/modules/devtools/proc-rhdh-verify-plugin-installation.adoc new file mode 100644 index 0000000000..9037e9fe33 --- /dev/null +++ b/downstream/modules/devtools/proc-rhdh-verify-plugin-installation.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-verify-plugin-installation_{context}"] += Verifying the plug-in installation + +[role="_abstract"] +After configuring the dynamic plug-ins and sidecar container, verify that the Ansible plug-ins installed successfully. + +.Procedure + +. In the `install-dynamic-plugin` container logs, search for the Ansible plug-ins. +A successful installation shows: ++ +[source,terminal] +---- +==> Successfully installed dynamic plugin oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-rhaap +==> Successfully installed dynamic plugin oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-self-service +==> Successfully installed dynamic plugin oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-backstage-plugin-catalog-backend-module-rhaap +==> Successfully installed dynamic plugin oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-scaffolder-backend-module-backstage-rhaap +---- + +. Verify that the Ansible plug-in is present in the navigation pane. + +. If you select *Administration*, the installed plug-ins are listed in the *Plugins* tab. diff --git a/downstream/modules/devtools/ref-rhdh-full-aap-configmap-example.adoc b/downstream/modules/devtools/ref-rhdh-full-aap-configmap-example.adoc index fb05ff05a4..39a5a6feb7 100644 --- a/downstream/modules/devtools/ref-rhdh-full-aap-configmap-example.adoc +++ b/downstream/modules/devtools/ref-rhdh-full-aap-configmap-example.adoc @@ -20,7 +20,9 @@ data: port: '8000' # Optional integrations rhaap: - baseUrl: '' + baseUrl: '' + token: '' + checkSSL: true devSpaces: baseUrl: '' automationHub: diff --git a/downstream/modules/devtools/ref-rhdh-full-helm-chart-ansible-plugins.adoc b/downstream/modules/devtools/ref-rhdh-full-helm-chart-ansible-plugins.adoc index da681ae9db..4e13b3db0a 100644 --- a/downstream/modules/devtools/ref-rhdh-full-helm-chart-ansible-plugins.adoc +++ b/downstream/modules/devtools/ref-rhdh-full-helm-chart-ansible-plugins.adoc @@ -6,14 +6,16 @@ [role="_abstract"] This example provides a full YAML configuration for the Helm chart using OCI container delivery. +[source,yaml,subs="+attributes"] ---- global: + # ... dynamic: - includes: - - dynamic-plugins.default.yaml + # ... plugins: - disabled: false - package: 'oci://registry.redhat.io/ansible-automation-platform/automation-portal:2.1!ansible-plugin-backstage-rhaap' + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-rhaap pluginConfig: dynamicPlugins: frontend: @@ -28,17 +30,29 @@ global: text: Ansible path: /ansible - disabled: false - package: 'oci://registry.redhat.io/ansible-automation-platform/automation-portal:2.1!ansible-plugin-scaffolder-backend-module-backstage-rhaap' + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-backstage-self-service + pluginConfig: + dynamicPlugins: + frontend: + ansible.plugin-backstage-self-service: + scaffolderFieldExtensions: + - importName: AAPTokenFieldExtension + - importName: AAPResourcePickerExtension + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-backstage-plugin-catalog-backend-module-rhaap + pluginConfig: {} + - disabled: false + package: >- + oci://registry.redhat.io/ansible-automation-platform/automation-portal:!ansible-plugin-scaffolder-backend-module-backstage-rhaap pluginConfig: dynamicPlugins: backend: - ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - + ansible.plugin-scaffolder-backend-module-backstage-rhaap: upstream: backstage: - image: - pullSecrets: - - + # ... extraAppConfig: - configMapRef: app-config-rhdh filename: app-config-rhdh.yaml @@ -47,7 +61,7 @@ upstream: - adt - server image: >- - registry.redhat.io/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest + registry.redhat.io/ansible-automation-platform-{PlatformVers}/ansible-dev-tools-rhel9:latest imagePullPolicy: IfNotPresent name: ansible-devtools-server ports: diff --git a/downstream/modules/devtools/ref-rhdh-full-operator-cr-example.adoc b/downstream/modules/devtools/ref-rhdh-full-operator-cr-example.adoc new file mode 100644 index 0000000000..276a2a504e --- /dev/null +++ b/downstream/modules/devtools/ref-rhdh-full-operator-cr-example.adoc @@ -0,0 +1,53 @@ +:_mod-docs-content-type: REFERENCE + +[id="rhdh-full-operator-cr-example_{context}"] += Full Operator Backstage CR example for {AAPRHDHShort} + +[role="_abstract"] +This example shows the full Backstage custom resource configuration for an Operator-based deployment, including the ADT sidecar container and `imagePullSecrets`: + +[source,yaml,subs="+attributes"] +---- +apiVersion: rhdh.redhat.com/v1alpha5 +kind: Backstage +metadata: + name: developer-hub + namespace: +spec: + application: + appConfig: + configMaps: + - name: app-config-rhdh + mountPath: /opt/app-root/src + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + secrets: + - name: + - name: + extraFiles: + mountPath: /opt/app-root/src + secrets: + - key: private-key.pem + name: + route: + enabled: true + database: + enableLocalDb: true + deployment: + patch: + spec: + template: + spec: + imagePullSecrets: + - name: rhdh-registry-pull-secret + containers: + - name: ansible-devtools-server + command: + - adt + - server + image: registry.redhat.io/ansible-automation-platform-{PlatformVers}/ansible-dev-tools-rhel9:latest + imagePullPolicy: Always + ports: + - containerPort: 8000 + protocol: TCP +---- diff --git a/downstream/titles/aap-plugin-rhdh-install/master.adoc b/downstream/titles/aap-plugin-rhdh-install/master.adoc index ed0aa82fbd..14a8d43c97 100644 --- a/downstream/titles/aap-plugin-rhdh-install/master.adoc +++ b/downstream/titles/aap-plugin-rhdh-install/master.adoc @@ -18,27 +18,30 @@ include::{Boilerplate}[] include::devtools/assembly-rhdh-intro.adoc[leveloffset=+1] +// Prerequisites +include::devtools/assembly-rhdh-prerequisites.adoc[leveloffset=+1] -// Installation -include::devtools/assembly-rhdh-install-ocp-helm.adoc[leveloffset=+1] +// Installation (unified Helm/Operator, OCI delivery) +include::devtools/assembly-rhdh-install.adoc[leveloffset=+1] -include::devtools/assembly-rhdh-install-ocp-operator.adoc[leveloffset=+1] +// Configuration +include::devtools/assembly-rhdh-configure.adoc[leveloffset=+1] -// -// Subscription warnings - deleted chapter -// -// Upgrade -include::devtools/assembly-rhdh-upgrade-ocp-helm.adoc[leveloffset=+1] +// Optional configuration +include::devtools/assembly-rhdh-ocp-configure-optional.adoc[leveloffset=+1] + +// Uninstall (unified Helm/Operator) +include::devtools/assembly-rhdh-uninstall.adoc[leveloffset=+1] -include::devtools/assembly-rhdh-upgrade-ocp-operator.adoc[leveloffset=+1] +// Full configuration examples +include::devtools/assembly-rhdh-full-examples.adoc[leveloffset=+1] -// -// Uninstall -include::devtools/assembly-rhdh-uninstall-ocp-helm.adoc[leveloffset=+1] +// Appendix: HTTP plug-in registry (deprecated) +include::devtools/assembly-rhdh-http-deprecated.adoc[leveloffset=+1] -include::devtools/assembly-rhdh-uninstall-ocp-operator.adoc[leveloffset=+1] +// Upgrade +include::devtools/assembly-rhdh-upgrade.adoc[leveloffset=+1] -// // Telemetry include::devtools/assembly-rhdh-telemetry-capturing.adoc[leveloffset=+1]