Chapter 3. Installing the Ansible plug-ins with the Operator 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 the Operator. 3.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. 3.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. 3.3. Backing up your RHDH Operator ConfigMap Before you install Ansible plug-ins for Red Hat Developer Hub, create a local copy of the ConfigMap for the RHDH Operator. You can use a section of the ConfigMap when you are populating a custom ConfigMap. Procedure Find the namespace for your RHDH Operator. When you installed the RHDH Operator, a namespace was created for it. Select Topology and look for the RHDH Operator in the Project dropdown list. The default namespace is rhdh-operator . Run the following command to make a copy of the ConfigMap for your RHDH Operator, backstage-default-config . Replace <rhdh-operator-namespace> with your RHDH Operator namespace, and <CopyOfRhdhOperatorConfig> with the filename you want to use for your copy of the RHDH Operator. USD oc get configmap backstage-default-config -n <rhdh-operator-namespace> -o yaml > <CopyOfRhdhOperatorConfig> 3.4. Creating a custom Operator ConfigMap Create a custom ConfigMap, for instance rhdh-custom-config , for your project. For more details about creating a custom ConfigMap, see the Adding a custom application configuration file to OpenShift Container Platform using the Operator in the Administration guide for Red Hat Developer Hub . Populate the ConfigMap with YAML from the backup that you made of the RHDH Operator ConfigMap. Prerequisites You have saved a backup copy of the Configmap for the RHDH Operator. Procedure In the OpenShift web console, navigate to the project you created. Click ConfigMaps in the navigation pane. Click Create ConfigMap . Replace the default YAML code in the new ConfigMap with the following code: apiVersion: v1 kind: ConfigMap metadata: name: rhdh-custom-config data: deployment.yaml: |- # Replace with RHDH Operator ConfigMap deployment.yaml block here Copy the deployment.yaml: section from your local copy of the RHDH Operator ConfigMap. Paste the deployment.yaml: section into the rhdh-custom-config ConfigMap, replacing the deployment.yaml: line. Add a sidecar container ( ansible-devtools-server ) to the list of containers under resources in the deployment.spec.template.spec.[containers] block of the ConfigMap: spec: replicas: 1 selector: matchLabels: rhdh.redhat.com/app: template: metadata: labels: rhdh.redhat.com/app: spec:\ ... containers: - name: backstage-backend ... - resources: {} # Add sidecar container for Ansible plug-ins terminationMessagePath: /dev/termination-log name: ansible-devtools-server command: - adt - server ports: - containerPort: 8000 protocol: TCP imagePullPolicy: IfNotPresent terminationMessagePolicy: File image: 'ghcr.io/ansible/community-ansible-dev-tools:latest' Click Create to create the ConfigMap. Verification To view your new ConfigMap, click ConfigMaps in the navigation pane. 3.5. Adding the rhdh-custom-config file to the RHDH Operator Custom Resource Update the RHDH Operator Custom Resource to add the rhdh-custom-config file. In the OpenShift console, select the Topology view. Click More actions ... on the RHDH Operator Custom Resource and select Edit backstage to edit the Custom Resource. Add a rawRuntimeConfig: block for your custom ConfigMap spec: block. It must have the same indentation level as the spec.application: block. spec: application: ... database: ... rawRuntimeConfig: backstageConfig: rhdh-custom-config Click Save . The RHDH Operator redeploys the pods to reflect the updated Custom Resource. 3.6. 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. 3.7. 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. 3.8. Installing the dynamic plug-ins To install the dynamic plugins, add them to your ConfigMap for your RHDH plugin settings (for example, rhaap-dynamic-plugins-config ). If you have not already created a ConfigMap file for your RHDH plugin settings, create one by following the procedure in Adding a custom application configuration file to Red Hat OpenShift Container Platform section of the Administration guide for Red Hat Developer Hub . The example ConfigMap used in the following procedure is called rhaap-dynamic-plugins-config . Procedure Select ConfigMaps in the navigation pane of the OpenShift console. Select the rhaap-dynamic-plugins-config ConfigMap from the list. Select the YAML tab to edit the rhaap-dynamic-plugins-config ConfigMap. In the data.dynamic-plugins.yaml.plugins block, add the three dynamic plug-ins from the plug-in registry. For the integrity hash values, use the .integrity files in your USDDYNAMIC_PLUGIN_ROOT_DIR directory that correspond to each plug-in, for example use ansible-plugin-backstage-rhaap-x.y.z.tgz.integrity for the ansible-plugin-backstage-rhaap-x.y.z.tgz plug-in. Replace x.y.z with the correct version of the plug-ins. 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-x.y.z.tgz' integrity: <SHA512 value> # Use hash in ansible-plugin-backstage-rhaap-x.y.z.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-backstage-rhaap-backend-x.y.z.tgz integrity: <SHA512 value> # Use hash in ansible-plugin-backstage-rhaap-backend-x.y.z.tgz.integrity pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null - disabled: false package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz integrity: <SHA512 value> # Use hash in ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz.integrity pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - ...<REDACTED> Click Save . To view the progress of the rolling restart: In the Topology view, select the deployment pod and click View logs . Select install-dynamic-plugins from the list of containers. Verification In the OpenShift console, select the Topology view. Click the Open URL icon on the deployment pod to open your Red Hat Developer Hub instance in a browser window. The Ansible plug-in is present in the navigation pane, and if you select Administration , the installed plug-ins are listed in the Plugins tab. 3.9. 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 . 3.10. 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' ... 3.11. 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. 3.12. 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 . 3.13. 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. 3.14. Optional configuration for Ansible plug-ins 3.14.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 . 3.14.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 . 3.14.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 . 3.14.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 . 3.15. 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] ...

Commands:
oc get configmap backstage-default-config -n <rhdh-operator-namespace> -o yaml > <CopyOfRhdhOperatorConfig>
apiVersion: v1 kind: ConfigMap metadata: name: rhdh-custom-config data: deployment.yaml: |- # Replace with RHDH Operator ConfigMap deployment.yaml block here
spec: replicas: 1 selector: matchLabels: rhdh.redhat.com/app: template: metadata: labels: rhdh.redhat.com/app: spec: containers: - name: backstage-backend - resources: {} # Add sidecar container for Ansible plug-ins terminationMessagePath: /dev/termination-log name: ansible-devtools-server command: - adt - server ports: - containerPort: 8000 protocol: TCP imagePullPolicy: IfNotPresent terminationMessagePolicy: File image: 'ghcr.io/ansible/community-ansible-dev-tools:latest'
spec: application: database: rawRuntimeConfig: backstageConfig: rhdh-custom-config
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
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-x.y.z.tgz' integrity: <SHA512 value> # Use hash in ansible-plugin-backstage-rhaap-x.y.z.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-backstage-rhaap-backend-x.y.z.tgz integrity: <SHA512 value> # Use hash in ansible-plugin-backstage-rhaap-backend-x.y.z.tgz.integrity pluginConfig: dynamicPlugins: backend: ansible.plugin-backstage-rhaap-backend: null - disabled: false package: >- http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz integrity: <SHA512 value> # Use hash in ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz.integrity pluginConfig: dynamicPlugins: backend: ansible.plugin-scaffolder-backend-module-backstage-rhaap: null - ...<REDACTED>
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]