Chapter 2. Installing the Ansible plug-ins with a Helm chart on OpenShift Container Platform The following procedures describe how to install Ansible plug-ins in Red Hat Developer Hub instances on Red Hat OpenShift Container Platform using a Helm chart. The workflow is as follows: Download the Ansible plug-ins files. Create a plug-in registry in your OpenShift cluster to host the Ansible plug-ins. Add the plug-ins to the Helm chart. Create a custom ConfigMap. Add your custom ConfigMap to your Helm chart. Edit your custom ConfigMap and Helm chart according to the required and optional configuration procedures. Note You can save changes to your Helm and ConfigMap after each update to your configuration. You do not have to make all the changes to these files in a single session. 2.1. Prerequisites Red Hat Developer Hub installed on Red Hat OpenShift Container Platform. For Helm installation, follow the steps in the Installing Red Hat Developer Hub on OpenShift Container Platform with the Helm chart section of Installing Red Hat Developer Hub on OpenShift Container Platform . For Operator installation, follow the steps in the Installing Red Hat Developer Hub on OpenShift Container Platform with the Operator section of Installing Red Hat Developer Hub on OpenShift Container Platform . A valid subscription to Red Hat Ansible Automation Platform. An OpenShift Container Platform instance with the appropriate permissions within your project to create an application. The Red Hat Developer Hub instance can query the automation controller API. Optional: To use the integrated learning paths, you must have outbound access to developers.redhat.com. 2.2. Recommended RHDH preconfiguration Red Hat recommends performing the following initial configuration tasks in RHDH. However, you can install the Ansible plug-ins for Red Hat Developer Hub before completing these tasks. Setting up authentication in RHDH Installing and configuring RBAC in RHDH Note Red Hat provides a repository of software templates for RHDH that uses the publish:github action. To use these software templates, you must install the required GitHub dynamic plugins. 2.3. Downloading the Ansible plug-ins files Download the latest .tar file for the plug-ins from the Red Hat Ansible Automation Platform Product Software downloads page . The format of the filename is ansible-backstage-rhaap-bundle-x.y.z.tar.gz . Substitute the Ansible plug-ins release version, for example 1.0.0 , for x.y.z . Create a directory on your local machine to store the .tar files. USD mkdir /path/to/<ansible-backstage-plugins-local-dir-changeme> Set an environment variable ( USDDYNAMIC_PLUGIN_ROOT_DIR ) to represent the directory path. USD export DYNAMIC_PLUGIN_ROOT_DIR=/path/to/<ansible-backstage-plugins-local-dir-changeme> Extract the ansible-backstage-rhaap-bundle-<version-number>.tar.gz contents to USDDYNAMIC_PLUGIN_ROOT_DIR . USD tar --exclude='*code*' -xzf ansible-backstage-rhaap-bundle-x.y.z.tar.gz -C USDDYNAMIC_PLUGIN_ROOT_DIR Substitute the Ansible plug-ins release version, for example 1.0.0 , for x.y.z . Verification Run ls to verify that the extracted files are in the USDDYNAMIC_PLUGIN_ROOT_DIR directory: USD ls USDDYNAMIC_PLUGIN_ROOT_DIR ansible-plugin-backstage-rhaap-x.y.z.tgz ansible-plugin-backstage-rhaap-x.y.z.tgz.integrity ansible-plugin-backstage-rhaap-backend-x.y.z.tgz ansible-plugin-backstage-rhaap-backend-x.y.z.tgz.integrity ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz.integrity The files with the .integrity file type contain the plugin SHA value. The SHA value is used during the plug-in configuration. 2.4. Creating a registry for the Ansible plug-ins Set up a registry in your OpenShift cluster to host the Ansible plug-ins and make them available for installation in Red Hat Developer Hub (RHDH). Procedure Log in to your OpenShift Container Platform instance with credentials to create a new application. Open your Red Hat Developer Hub OpenShift project. USD oc project <YOUR_DEVELOPER_HUB_PROJECT> Run the following commands to create a plug-in registry build in the OpenShift cluster. USD oc new-build httpd --name=plugin-registry --binary USD oc start-build plugin-registry --from-dir=USDDYNAMIC_PLUGIN_ROOT_DIR --wait USD oc new-app --image-stream=plugin-registry Verification To verify that the plugin-registry was deployed successfully, open the Topology view in the Developer perspective on the Red Hat Developer Hub application in the OpenShift Web console. Click the plug-in registry to view the log. (1) Developer hub instance (2) Plug-in registry Click the terminal tab and login to the container. In the terminal, run ls to confirm that the .tar files are in the plugin registry. ansible-plugin-backstage-rhaap-x.y.z.tgz ansible-plugin-backstage-rhaap-backend-x.y.z.tgz ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz The version numbers and file names can differ. 2.5. Required configuration 2.5.1. Adding the Ansible plug-ins configuration In the OpenShift Developer UI, navigate to Helm developer-hub Actions Upgrade Yaml view . Update the Helm chart configuration to add the dynamic plug-ins in the Red Hat Developer Hub instance. Under the plugins section in the YAML file, add the dynamic plug-ins that you want to enable. global: ... plugins: - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap plugin> package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-x.y.z.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: <SHA512 Integrity key for ansible-plugin-scaffolder-backend-module-backstage-rhaap plugin> package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap-backend plugin> package: >- http://plugin-registry:8080/ansible-plugin-backstage-rhaap-backend-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null In the package sections, replace x.y.z in the plug-in filenames with the correct version numbers for the Ansible plug-ins. For each Ansible plug-in, update the integrity values using the corresponding .integrity file content. Click Upgrade . The developer hub pods restart and the plug-ins are installed. Verification To verify that the plug-ins have been installed, open the install-dynamic-plugin container logs and check that the Ansible plug-ins are visible in Red Hat Developer Hub: Open the Developer perspective for the Red Hat Developer Hub application in the OpenShift Web console. Select the Topology view. Select the Red Hat Developer Hub deployment pod to open an information pane. Select the Resources tab of the information pane. In the Pods section, click View logs to open the Pod details page. In the Pod details page, select the Logs tab. Select install-dynamic-plugins from the drop-down list of containers to view the container log. In the install-dynamic-plugin container logs, search for the Ansible plug-ins. The following example from the log indicates a successful installation for one of the plug-ins: => Successfully installed dynamic plugin http://plugin-registry-1:8080/ansible-plugin-backstage-rhaap-1.1.0.tgz The following image shows the container log in the Pod details page. The version numbers and file names can differ. 2.5.2. Adding the Ansible Development Tools sidecar container After the plug-ins are loaded, add the Ansible Development Container ( ansible-devtools-server ) in the Red Hat Developer Hub pod as a sidecar container. 2.5.2.1. Adding a pull secret to the Red Hat Developer Hub Helm configuration Prerequisite The Ansible Development Container download requires a Red Hat Customer Portal account and Red Hat Service Registry account. Procedure Create a new Red Hat Registry Service account , if required. Click the token name under the Account name column. Select the OpenShift Secret tab and follow the instructions to add the pull secret to your Red Hat Developer Hub OpenShift project. Add the new secret to the Red Hat Developer Hub Helm configuration, replacing <your-redhat-registry-pull-secret> with the name of the secret you generated on the Red Hat Registry Service Account website: upstream: backstage: ... image: ... pullSecrets: - <your-redhat-registry-pull-secret> ... For more information, refer to the Red Hat Container Registry documentation . 2.5.2.2. Adding the Ansible Developer Tools container You must update the Helm chart configuration to add an extra container. Procedure Log in to the OpenShift UI. Navigate to Helm developer-hub Actions upgrade Yaml view to open the Helm chart. Update the extraContainers section in the YAML file. Add the following code: upstream: backstage: ... extraContainers: - command: - adt - server image: >- registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel8: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 Upgrade . Verification To verify that the container is running, check the container log: 2.5.3. Adding a custom ConfigMap Create a Red Hat Developer Hub ConfigMap following the procedure in Adding a custom application configuration file to Red Hat OpenShift Container Platform in the Administration guide for Red Hat Developer Hub . The examples below use a custom ConfigMap named app-config-rhdh To edit your custom ConfigMap, log in to the OpenShift UI and navigate to Select Project ( developerHubProj ) ConfigMaps {developer-hub}-app-config EditConfigMaps app-config-rhdh . 2.5.4. Configuring the Ansible Dev Tools Server The creatorService URL is required for the Ansible plug-ins to provision new projects using the provided software templates. Procedure Edit your custom Red Hat Developer Hub config map, app-config-rhdh , that you created in Adding a custom ConfigMap . Add the following code to your Red Hat Developer Hub app-config-rhdh.yaml file. kind: ConfigMap apiVersion: v1 metadata: name: app-config-rhdh ... data: app-config-rhdh.yaml: |- ansible: creatorService: baseUrl: 127.0.0.1 port: '8000' ... 2.5.5. Configuring Ansible Automation Platform details The Ansible plug-ins query your Ansible Automation Platform subscription status with the controller API using a token. Note The Ansible plug-ins continue to function regardless of the Ansible Automation Platform subscription status. Procedure Create a Personal Access Token (PAT) with "Read" scope in automation controller, following the Applications section of Access management and authentication . Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh . Add your Ansible Automation Platform details to app-config-rhdh.yaml . Set the baseURL key with your automation controller URL. Set the token key with the generated token value that you created in Step 1. Set the checkSSL key to true or false . If checkSSL is set to true , the Ansible plug-ins verify whether the SSL certificate is valid. data: app-config-rhdh.yaml: | ... ansible: ... rhaap: baseUrl: '<https://MyControllerUrl>' token: '<AAP Personal Access Token>' checkSSL: true Note You are responsible for protecting your Red Hat Developer Hub installation from external and unauthorized access. Manage the backend authentication key like any other secret. Meet strong password requirements, do not expose it in any configuration files, and only inject it into configuration files as an environment variable. 2.5.6. Adding Ansible plug-ins software templates Red Hat Ansible provides software templates for Red Hat Developer Hub to provision new playbooks and collection projects based on Ansible best practices. Procedure Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh . Add the following code to your Red Hat Developer Hub app-config-rhdh.yaml file. data: app-config-rhdh.yaml: | catalog: ... locations: ... - type: url target: https://github.com/ansible/ansible-rhdh-templates/blob/main/all.yaml rules: - allow: [Template] For more information, refer to the Managing templates section of the Administration guide for Red Hat Developer Hub . 2.5.7. Configuring Role Based Access Control Red Hat Developer Hub offers Role-based Access Control (RBAC) functionality. RBAC can then be applied to the Ansible plug-ins content. Assign the following roles: Members of the admin:superUsers group can select templates in the Create tab of the Ansible plug-ins to create playbook and collection projects. Members of the admin:users group can view templates in the Create tab of the Ansible plug-ins. The following example adds RBAC to Red Hat Developer Hub. data: app-config-rhdh.yaml: | plugins: ... permission: enabled: true rbac: admin: users: - name: user:default/<user-scm-ida> superUsers: - name: user:default/<user-admin-idb> For more information about permission policies and managing RBAC, refer to the Authorization guide for Red Hat Developer Hub. 2.6. Optional configuration for Ansible plug-ins 2.6.1. Enabling Red Hat Developer Hub authentication Red Hat Developer Hub (RHDH) provides integrations for multiple Source Control Management (SCM) systems. This is required by the plug-ins to create repositories. Refer to the Enabling authentication in Red Hat Developer Hub chapter of the Administration guide for Red Hat Developer Hub . 2.6.2. Configuring Ansible plug-ins optional integrations The Ansible plug-ins provide integrations with Ansible Automation Platform and other optional Red Hat products. To edit your custom ConfigMap, log in to the OpenShift UI and navigate to Select Project ( developerHubProj ) ConfigMaps {developer-hub}-app-config-rhdh app-config-rhdh . 2.6.2.1. Configuring OpenShift Dev Spaces When OpenShift Dev Spaces is configured for the Ansible plug-ins, users can click a link from the catalog item view in Red Hat Developer Hub and edit their provisioned Ansible Git projects using Dev Spaces. Note OpenShift Dev Spaces is a separate product and it is optional. The plug-ins will function without it. It is a separate Red Hat product and is not included in the Ansible Automation Platform or Red Hat Developer Hub subscription. If the OpenShift Dev Spaces link is not configured in the Ansible plug-ins, the Go to OpenShift Dev Spaces dashboard link in the DEVELOP section of the Ansible plug-ins landing page redirects users to the Ansible development tools home page . Prerequisites A Dev Spaces installation. Refer to the Installing Dev Spaces section of the Red Hat OpenShift Dev Spaces Administration guide . Procedure Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh . Add the following code to your Red Hat Developer Hub app-config-rhdh.yaml file. data: app-config-rhdh.yaml: |- ansible: devSpaces: baseUrl: >- https://<Your OpenShift Dev Spaces URL> Replace <Your OpenShft Dev Spaces URL> with your OpenShift Dev Spaces URL. In the OpenShift Developer UI, select the Red Hat Developer Hub pod. Open Actions . Click Restart rollout . 2.6.2.2. Configuring the private automation hub URL Private automation hub provides a centralized, on-premise repository for certified Ansible collections, execution environments and any additional, vetted content provided by your organization. If the private automation hub URL is not configured in the Ansible plug-ins, users are redirected to the Red Hat Hybrid Cloud Console automation hub . Note The private automation hub configuration is optional but recommended. The Ansible plug-ins will function without it. Prerequisites: A private automation hub instance. For more information on installing private automation hub, refer to the installation guides in the Ansible Automation Platform documentation . Procedure: Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh . Add the following code to your Red Hat Developer Hub app-config-rhdh.yaml file. data: app-config-rhdh.yaml: |- ansible: ... automationHub: baseUrl: '<https://MyOwnPAHUrl>' ... Replace <https://MyOwnPAHUrl/> with your private automation hub URL. In the OpenShift Developer UI, select the Red Hat Developer Hub pod. Open Actions . Click Restart rollout . 2.7. Full examples 2.7.1. Full app-config-rhdh ConfigMap example for Ansible plug-ins entries kind: ConfigMap ... metadata: name: app-config-rhdh ... data: app-config-rhdh.yaml: |- ansible: creatorService: baseUrl: 127.0.0.1 port: '8000' rhaap: baseUrl: '<https://MyControllerUrl>' token: '<AAP Personal Access Token>' checkSSL: <true or false> # Optional integrations devSpaces: baseUrl: '<https://MyDevSpacesURL>' automationHub: baseUrl: '<https://MyPrivateAutomationHubURL>' ... catalog: locations: - type: url target: https://github.com/ansible/ansible-rhdh-templates/blob/main/all.yaml rules: - allow: [Template] ... 2.7.2. Full Helm chart config example for Ansible plug-ins global: ... dynamic: ... plugins: - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap plugin> package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-x.y.z.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: <SHA512 Integrity key for ansible-plugin-scaffolder-backend-module-backstage-rhaap plugin> package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap-backend plugin> package: >- http://plugin-registry:8080/ansible-plugin-backstage-rhaap-backend-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null ... upstream: backstage: ... extraAppConfig: - configMapRef: app-config-rhdh filename: app-config-rhdh.yaml extraContainers: - command: - adt - server image: >- registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel8:latest imagePullPolicy: IfNotPresent name: ansible-devtools-server ports: - containerPort: 8000 ...

Commands:
mkdir /path/to/<ansible-backstage-plugins-local-dir-changeme>
export DYNAMIC_PLUGIN_ROOT_DIR=/path/to/<ansible-backstage-plugins-local-dir-changeme>
tar --exclude='*code*' -xzf ansible-backstage-rhaap-bundle-x.y.z.tar.gz -C USDDYNAMIC_PLUGIN_ROOT_DIR
ls USDDYNAMIC_PLUGIN_ROOT_DIR ansible-plugin-backstage-rhaap-x.y.z.tgz ansible-plugin-backstage-rhaap-x.y.z.tgz.integrity ansible-plugin-backstage-rhaap-backend-x.y.z.tgz ansible-plugin-backstage-rhaap-backend-x.y.z.tgz.integrity ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz.integrity
oc project <YOUR_DEVELOPER_HUB_PROJECT>
oc new-build httpd --name=plugin-registry --binary oc start-build plugin-registry --from-dir=USDDYNAMIC_PLUGIN_ROOT_DIR --wait oc new-app --image-stream=plugin-registry
ansible-plugin-backstage-rhaap-x.y.z.tgz ansible-plugin-backstage-rhaap-backend-x.y.z.tgz ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz
global: plugins: - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap plugin> package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-x.y.z.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: <SHA512 Integrity key for ansible-plugin-scaffolder-backend-module-backstage-rhaap plugin> package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap-backend plugin> package: >- http://plugin-registry:8080/ansible-plugin-backstage-rhaap-backend-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null
=> Successfully installed dynamic plugin http://plugin-registry-1:8080/ansible-plugin-backstage-rhaap-1.1.0.tgz
upstream: backstage: image: pullSecrets: - <your-redhat-registry-pull-secret>
upstream: backstage: extraContainers: - command: - adt - server image: >- registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel8:latest imagePullPolicy: IfNotPresent name: ansible-devtools-server ports: - containerPort: 8000
kind: ConfigMap apiVersion: v1 metadata: name: app-config-rhdh data: app-config-rhdh.yaml: |- ansible: creatorService: baseUrl: 127.0.0.1 port: '8000'
data: app-config-rhdh.yaml: | ansible: rhaap: baseUrl: '<https://MyControllerUrl>' token: '<AAP Personal Access Token>' checkSSL: true
data: app-config-rhdh.yaml: | catalog: locations: - type: url target: https://github.com/ansible/ansible-rhdh-templates/blob/main/all.yaml rules: - allow: [Template]
data: app-config-rhdh.yaml: | plugins: permission: enabled: true rbac: admin: users: - name: user:default/<user-scm-ida> superUsers: - name: user:default/<user-admin-idb>
data: app-config-rhdh.yaml: |- ansible: devSpaces: baseUrl: >- https://<Your OpenShift Dev Spaces URL>
data: app-config-rhdh.yaml: |- ansible: automationHub: baseUrl: '<https://MyOwnPAHUrl>'
kind: ConfigMap metadata: name: app-config-rhdh data: app-config-rhdh.yaml: |- ansible: creatorService: baseUrl: 127.0.0.1 port: '8000' rhaap: baseUrl: '<https://MyControllerUrl>' token: '<AAP Personal Access Token>' checkSSL: <true or false> # Optional integrations devSpaces: baseUrl: '<https://MyDevSpacesURL>' automationHub: baseUrl: '<https://MyPrivateAutomationHubURL>' catalog: locations: - type: url target: https://github.com/ansible/ansible-rhdh-templates/blob/main/all.yaml rules: - allow: [Template]
global: dynamic: plugins: - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap plugin> package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-x.y.z.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: <SHA512 Integrity key for ansible-plugin-scaffolder-backend-module-backstage-rhaap plugin> package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - disabled: false integrity: <SHA512 Integrity key for ansible-plugin-backstage-rhaap-backend plugin> package: >- http://plugin-registry:8080/ansible-plugin-backstage-rhaap-backend-x.y.z.tgz pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null upstream: backstage: extraAppConfig: - configMapRef: app-config-rhdh filename: app-config-rhdh.yaml extraContainers: - command: - adt - server image: >- registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel8:latest imagePullPolicy: IfNotPresent name: ansible-devtools-server ports: - containerPort: 8000