Chapter 2. Installing the Ansible plug-ins with a Helm chart on OpenShift Container Platform

Procedure

1. Create an auth.json file on your local machine with your registry.redhat.io credentials:

   {
     "auths": {
       "registry.redhat.io": {
         "auth": "<base64-encoded-username:password>"
       }
     }
   }

   To generate the base64-encoded value use the printf '%s' '<username>:<password>' | base64 command.

2. Create the authentication secret in the OpenShift project where you installed Red Hat Developer Hub.

   The secret name must follow the pattern <deployment-name>-dynamic-plugins-registry-auth, where <deployment-name> matches your Red Hat Developer Hub deployment name.

   • For a default Red Hat Developer Hub Helm installation with release name developer-hub:

     oc create secret generic developer-hub-dynamic-plugins-registry-auth \
       --from-file=auth.json=./auth.json

   • If you use a different Helm release name:

     oc create secret generic <deployment-name>-dynamic-plugins-registry-auth \
       --from-file=auth.json=./auth.json

   • If you already have Podman credentials configured locally:

     oc create secret generic <deployment-name>-dynamic-plugins-registry-auth \
       --from-file=auth.json=${XDG_RUNTIME_DIR}/containers/auth.json

     Important

     Create this secret in the same OpenShift project as your Red Hat Developer Hub deployment, and create it before you configure the plug-ins. Use a Red Hat Registry service account token, not your personal Red Hat account credentials.

Procedure

1. In a browser, navigate to the Red Hat Ansible Automation Platform Product Software downloads page and select the Product Software tab.

2. Click Download now next to Ansible plug-ins for Red Hat Developer Hub Setup Bundle to download the latest version of the plug-ins.

   The format of the filename is ansible-rhdh-plugins-x.y.z.tar.gz. Substitute the Ansible plug-ins release version, for example 2.0.0, for x.y.z.

3. Create a directory on your local machine to store the .tar files.

   $ mkdir /path/to/<ansible-backstage-plugins-local-dir-changeme>

4. Set an environment variable ($DYNAMIC_PLUGIN_ROOT_DIR) to represent the directory path.

   $ export DYNAMIC_PLUGIN_ROOT_DIR=/path/to/<ansible-backstage-plugins-local-dir-changeme>

5. Extract the ansible-rhdh-plugins-<version-number>.tar.gz contents to $DYNAMIC_PLUGIN_ROOT_DIR.

   $ tar --exclude='*code*' -xzf ansible-rhdh-plugins-x.y.z.tar.gz -C $DYNAMIC_PLUGIN_ROOT_DIR

   Substitute the Ansible plug-ins release version, for example 2.0.0, for x.y.z.

Procedure

1. Log in to your OpenShift Container Platform instance with credentials to create a new application.

2. Open your Red Hat Developer Hub OpenShift project.

   $ oc project <YOUR_DEVELOPER_HUB_PROJECT>

3. Run the following commands to create a plug-in registry build in the OpenShift cluster.

   $ oc new-build httpd --name=plugin-registry --binary
   $ oc start-build plugin-registry --from-dir=$DYNAMIC_PLUGIN_ROOT_DIR --wait
   $ oc new-app --image-stream=plugin-registry

1. Click the plug-in registry to view the log.

   

   (1) Developer hub instance

   (2) Plug-in registry

2. Click the terminal tab and login to the container.

3. In the terminal, run ls to confirm that the .tar files are in the plugin registry.

   ansible-plugin-backstage-rhaap-dynamic-x.y.z.tgz
   ansible-plugin-scaffolder-backend-module-backstage-rhaap-dynamic-x.y.z.tgz

   The version numbers and file names can differ.

1. In the OpenShift Developer UI, navigate to Helm developer-hub Actions Upgrade Yaml view.

2. 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. Choose the configuration that matches your delivery method.

   • OCI container delivery (recommended):

     global:
       dynamic:
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - disabled: false
             package: 'oci://registry.redhat.io/ansible-automation-platform/automation-portal:21!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:2.1!ansible-plugin-scaffolder-backend-module-backstage-rhaap'
             pluginConfig:
               dynamicPlugins:
                 backend:
                   ansible.plugin-scaffolder-backend-module-backstage-rhaap: null

     Replace x.y.z with the Ansible plug-ins version.

     Note

     OCI delivery does not require the integrity hash values. The OCI registry handles integrity verification.

   • HTTP plug-in registry:

     global:
       dynamic:
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - disabled: false
             integrity: <SHA512 value>
             package: 'http://plugin-registry:8080/ansible-plugin-backstage-rhaap-dynamic-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 value>
             package: >-
               http://plugin-registry:8080/ansible-plugin-scaffolder-backend-module-backstage-rhaap-dynamic-x.y.z.tgz
             pluginConfig:
               dynamicPlugins:
                 backend:
                   ansible.plugin-scaffolder-backend-module-backstage-rhaap: null

     Replace x.y.z with the correct plug-in version numbers and update the integrity values using the corresponding .integrity file content.

3. Click Upgrade.

   The Red Hat Developer Hub pods restart and the plug-ins are installed.

1. Open the Developer perspective for the Red Hat Developer Hub application in the OpenShift Web console.
2. Select the Topology view.
3. Select the Red Hat Developer Hub deployment pod to open an information pane.
4. Select the Resources tab of the information pane.
5. In the Pods section, click View logs to open the Pod details page.
6. In the Pod details page, select the Logs tab.

7. Select install-dynamic-plugins from the drop-down list of containers to view the container log.

   • For OCI delivery, a successful installation displays:

     => Successfully installed dynamic plugin oci:registry.redhat.io/ansible-automation-platform/ansible-plugin-backstage-rhaap-dynamic:x.y.z

   • For HTTP plug-in registry, a successful installation displays:

     => Successfully installed dynamic plugin http://plugin-registry:8080/ansible-plugin-backstage-rhaap-dynamic-x.y.z.tgz

Procedure

1. Create a new Red Hat Registry Service account, if required.
2. Click the token name under the Account name column.
3. Select the OpenShift Secret tab and follow the instructions to add the pull secret to your Red Hat Developer Hub OpenShift project.

4. 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>
       ...

Procedure

1. Edit your custom Red Hat Developer Hub config map, app-config-rhdh, that you created in Adding a custom ConfigMap.

2. 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'
   ...

Procedure

1. Create a Personal Access Token (PAT) with “read and write” scope in automation controller, following the Applications section of Access management and authentication.
2. Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh.

3. Add your Ansible Automation Platform details to app-config-rhdh.yaml.

   1. Set the baseURL key with your automation controller URL.
   2. Set the token key with the generated token value that you created in Step 1.

   3. 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.

Procedure

1. Edit your custom Red Hat Developer Hub config map, for example app-config-rhdh.

2. 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]