Installing self-service automation portal

Procedure

1. In a browser, log in to GitHub.
2. Click your profile picture and select Settings.
3. Select Developer settings.
4. Select Personal access tokens.
5. Click Generate new token → Generate new token(classic).

6. In the Select scopes: section, enable the following:

   • repo
   • read:org
   • workflow (as needed)
7. Click Generate token.
8. Save the personal access token.

Procedure

1. In a browser, log in to Gitlab and click your avatar.
2. Select Edit profile.
3. Select Access tokens.
4. Click Add new token.
5. Provide a name and expiration date for the token.

6. In the Scopes: section, select the following:

   • read_repository
   • api
7. Click Create personal access token.
8. Save the personal access token.

Procedure

1. In a browser, log in to the OpenShift Container Platform web console.

2. Creating a project varies slightly depending on which perspective you have on:

   1. From the Developer perspective: select Project then Create Project.
   2. From the Administrator perspective: select Home then Project then Create Project.

3. In the Create Project dialog box, enter a unique name Name field.

   • Lowercase alphanumeric characters (a-z, 0-9) and the hyphen character (-) are permitted for project names.
   • The underscore (_) character is not permitted.

   • The maximum length for project names is 63 characters.

     1. Optional: display name and description for your project.
4. Click Click to create the project.

Procedure

1. In a terminal, log in to OpenShift Container Platform using your credentials:

   oc login <OpenShift_API_URL> -u <username>

   The following example shows the output for a successful login:

   $ oc login https://api.<my_cluster>.com:6443 -u kubeadmin
   WARNING: Using insecure TLS client config. Setting this option is not supported!
   
   Console URL: https://api.<my_cluster>.com:6443/console
   Authentication required for https://api.<my_cluster>.com:6443 (openshift)
   Username: kubeadmin
   Password:
   Login successful.
   
   You have access to 22 projects, the list has been suppressed. You can list all projects with 'oc projects'
   
   Using project "default".

2. Create a new project. Use a unique project name.

   $ oc new-project <self-service-project-name>

   • Lowercase alphanumeric characters (a-z, 0-9) and the hyphen character (-) are permitted for project names.
   • The underscore (_) character is not permitted.

   • The maximum length for project names is 63 characters.

     Example:

     $ oc new-project <my-project>
     
     Now using project "my-project" on server "https://openshift.example.com:6443".

3. Open your new project:

   $ oc project <self-service-project-name>

Procedure

1. Create an auth.json file on your local machine.

2. Add the following structure to the auth.json file:

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

3. Generate the base64-encoded authentication value:

   printf '%s' '<username>:<password>' | base64 -w0

4. Replace <base64-encoded-username-password> in the auth.json file with the output from the previous step.

5. Create the authentication secret in the target OpenShift project. The secret name must match your Helm release name.

   If you install from the OpenShift catalog and you use the default release name redhat-rhaap-portal:

   oc create secret generic redhat-rhaap-portal-dynamic-plugins-registry-auth \
     --from-file=auth.json=./auth.json

   If you use a custom release name:

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

1. In the OpenShift web console, select the OpenShift project where you will install the Helm release.
2. In the Administrator view, click Workloads → Secrets.
3. Click Create → Key/value secret.
4. Set the secret name to <release-name>-dynamic-plugins-registry-auth.
5. Add a key named auth.json and paste the contents of your auth.json file as the value.
6. Click Create.

1. In the Developer view, click Helm.
2. Select the Helm release.
3. Click Actions → Upgrade.
4. In the YAML view, set redhat-developer-hub.global.pluginMode to oci (OCI container delivery) or tarball (HTTP plug-in registry).
5. Click Upgrade.

Procedure

1. Log in to your OpenShift Container Platform instance.
2. Open your OpenShift project for self-service automation portal in the Administrator view.
3. Click Secrets in the side pane.
4. Click Create to open the form for creating a new secret.
5. Select the Key/Value option.

6. Create a secret named secrets-rhaap-portal.

   Note

   The secret must use this exact name.

7. Add the following key-value pairs to the secret.

   Note

   The secrets must use the exact key names specified below.

   • Key: aap-host-url

     Value needed: Ansible Automation Platform instance URL

   • Key: oauth-client-id

     Value needed: Ansible Automation Platform OAuth client ID

   • Key: oauth-client-secret

     Value needed: Ansible Automation Platform OAuth client secret value

   • Key: aap-token

     Value needed: Token for Ansible Automation Platform user authentication (must have read access).

8. Click Create to create the secret.

Procedure

1. Log in to your OpenShift Container Platform instance.
2. Open your OpenShift project for self-service automation portal.
3. Click Secrets in the side pane.
4. Click Create to open the form for creating a new secret.
5. Select the Key/Value option.

6. Create a secret named secrets-scm.

   Note

   The secret must use this exact name.

7. Add the following key-value pairs to the secret. If you are only using one SCM, just add the key-value pair for that SCM.

   Note

   The secrets must use the exact key names specified below.

   • Key: github-token

     Value needed: Github Personal Access Token (PAT)

   • Key: gitlab-token

     Value needed: Gitlab Personal Access Token (PAT)

8. Click Create to create the secret.

Procedure

1. Log in to registry.redhat.io:

   $ podman login registry.redhat.io

2. Enter your Red Hat username and password when prompted.

3. Log in to your disconnected registry:

   $ podman login <disconnected_registry_url>

4. Pull the Red Hat Developer Hub image from registry.redhat.io:

   $ podman pull registry.redhat.io/rhdh/rhdh-hub-rhel9:x.y.z

5. Tag the image for your disconnected registry:

   $ podman tag registry.redhat.io/rhdh/rhdh-hub-rhel9:x.y.z <disconnected_registry_url>/<your_namespace>/rhdh/rhdh-hub-rhel9:x.y.z

6. Push the tagged image to your disconnected registry:

   $ podman push <disconnected_registry_url>/<your_namespace>/rhdh/rhdh-hub-rhel9:x.y.z

7. If you use the built-in PostgreSQL database, mirror the PostgreSQL 15 image. An external database is the supported production architecture and does not require this step:

   $ podman pull registry.redhat.io/rhel9/postgresql-15:<tag>
   $ podman tag registry.redhat.io/rhel9/postgresql-15:<tag> <disconnected_registry_url>/<your_namespace>/rhel9/postgresql-15:<tag>
   $ podman push <disconnected_registry_url>/<your_namespace>/rhel9/postgresql-15:<tag>

8. If you use OCI container delivery, mirror the Ansible plug-ins OCI artifacts image:

   $ podman pull registry.redhat.io/ansible-automation-platform/automation-portal:<plugin-version>
   $ podman tag registry.redhat.io/ansible-automation-platform/automation-portal:<plugin-version> <disconnected_registry_url>/<your_namespace>/ansible-automation-platform/automation-portal:<plugin-version>
   $ podman push <disconnected_registry_url>/<your_namespace>/ansible-automation-platform/automation-portal:<plugin-version>

9. Mirror the Ansible Dev Tools sidecar image. Use the path that matches your Ansible Automation Platform version:

   Ansible Automation Platform 2.5:

   $ podman pull registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel9:latest
   $ podman tag registry.redhat.io/ansible-automation-platform-25/ansible-dev-tools-rhel9:latest <disconnected_registry_url>/<your_namespace>/ansible-automation-platform-25/ansible-dev-tools-rhel9:latest
   $ podman push <disconnected_registry_url>/<your_namespace>/ansible-automation-platform-25/ansible-dev-tools-rhel9:latest

   Ansible Automation Platform 2.6:

   $ podman pull registry.redhat.io/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest
   $ podman tag registry.redhat.io/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest <disconnected_registry_url>/<your_namespace>/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest
   $ podman push <disconnected_registry_url>/<your_namespace>/ansible-automation-platform-26/ansible-dev-tools-rhel9:latest

Procedure

1. Add the OpenShift Helm charts repository and update your local cache:

   helm repo add openshift-helm-charts https://charts.openshift.io/
   helm repo update

2. Pull the required version of the chart:

   helm pull openshift-helm-charts/redhat-rhaap-portal --version x.y.z

   The chart is saved as a .tgz file (for example, redhat-rhaap-portal-1.0.1.tgz).

3. Extract the chart files:

   tar -xvf redhat-rhaap-portal-x.y.z.tgz

   This creates a directory with a name similar to redhat-rhaap-portal-1.0.1/.

4. In the redhat-rhaap-portal/values.yaml file, replace all image: references with the full path to the images in your disconnected registry.

5. Repack the chart with your modifications:

   helm package redhat-rhaap-portal-x.y.z

6. A new .tgz file is created containing your changes.

Procedure

1. Copy the modified Helm chart .tgz file or files (for example, redhat-rhaap-portal-1.0.1.tgz) from your connected bastion host to a machine or jump box within your disconnected OpenShift network.
2. If you use the HTTP plug-in registry method, transfer the plug-in tarball files to the disconnected environment.

Procedure

1. In a terminal, log in to your disconnected OpenShift cluster using the oc CLI.

   oc login --token=<your_token> --server=<your_openshift_api_url>

   Use the following command if you have a kubeconfig:

   export KUBECONFIG=/path/to/your/kubeconfig
   oc login

2. Ensure that your OpenShift cluster is configured to trust your disconnected registry.

Procedure

1. On the machine within your disconnected environment, navigate to the directory where you placed the transferred Helm chart .tgz file:

   $ cd /path/to/your/transferred/charts/

2. Define your namespace and cluster router base as environment variables:

   $ export MY_NAMESPACE="<your_namespace_name>"
   $ export MY_CLUSTER_ROUTER_BASE="<your_cluster_router_base>"

3. If the namespace does not exist, create it:

   $ oc new-project "${MY_NAMESPACE}"

4. Create a custom values file and reuse it for install and upgrade. Choose the example that matches your plug-in delivery method.

   OCI delivery (values-oci.yaml):

   redhat-developer-hub:
     global:
       clusterRouterBase: <your_cluster_router_base>
       pluginMode: oci
       imageTagInfo: "<plugin-version>"
       # Registry host only. Replaces registry.redhat.io for all images.
       imageRegistry: "<disconnected_registry_url>"
       # Optional. Full OCI plugin image path for mirrors with non-standard
       # repository paths. Overrides imageRegistry for OCI plugin artifacts only.
       # Use when your mirror does not preserve the default repository path
       # (ansible-automation-platform/automation-portal).
       # ociPluginImage: "<disconnected_registry_url>/custom-path/automation-portal"
     upstream:
       backstage:
         # The Helm chart pins images by SHA256 digest by default.
         # When mirroring with podman tag/push, the digest is not preserved.
         # Override with tag-based references.
         image:
           repository: rhdh/rhdh-hub-rhel9
           tag: "1.8"
         appConfig:
           ansible:
             rhaap:
               checkSSL: true  # Set to false if using self-signed certificates.
           catalog:
             providers:
               rhaap:
                 '{{- include "catalog.providers.env" . }}':
                   orgs: "<your-aap-organization-name>"
       # If you use the built-in PostgreSQL database, uncomment the following lines.
       # An external database is the supported production architecture.
       # postgresql:
       #   image:
       #     repository: rhel9/postgresql-15
       #     tag: "latest"

   HTTP plug-in registry delivery (values-tarball.yaml):

   redhat-developer-hub:
     global:
       clusterRouterBase: <your_cluster_router_base>
       pluginMode: tarball
       # Registry host only. Replaces registry.redhat.io for the images.
       imageRegistry: "<disconnected_registry_url>"
     upstream:
       backstage:
         image:
           repository: rhdh/rhdh-hub-rhel9
           tag: "1.8"
         appConfig:
           ansible:
             rhaap:
               checkSSL: true  # Set to false if using self-signed certificates.
           catalog:
             providers:
               rhaap:
                 '{{- include "catalog.providers.env" . }}':
                   orgs: "<your-aap-organization-name>"
       # If you use the built-in PostgreSQL database, uncomment the following lines.
       # An external database is the supported production architecture.
       # postgresql:
       #   image:
       #     repository: rhel9/postgresql-15
       #     tag: "latest"

   Important

   Set imageRegistry to the registry host only (for example, mirror.example.com). Do not include repository paths. The chart appends the default repository path ansible-automation-platform/automation-portal automatically. If your mirror uses a different repository structure, set ociPluginImage to the full image path instead.

5. Install the chart using the helm install command:

   $ helm install redhat-rhaap-portal \
     redhat-rhaap-portal-x.y.z.tgz \
     --namespace "${MY_NAMESPACE}" \
     -f /path/to/values-oci.yaml

   To apply changes after deployment, upgrade the Helm release. If you install from the OpenShift web console, use Developer → Helm → select the release → Actions → Upgrade → YAML view.

   To upgrade from the command line:

   $ helm upgrade redhat-rhaap-portal \
     redhat-rhaap-portal-x.y.z.tgz \
     --namespace "${MY_NAMESPACE}" \
     -f /path/to/values-oci.yaml

   Alternatively, you can pass values using --set flags.

   OCI delivery:

   $ helm install redhat-rhaap-portal \
     redhat-rhaap-portal-x.y.z.tgz \
     --namespace "${MY_NAMESPACE}" \
     --set redhat-developer-hub.global.clusterRouterBase="${MY_CLUSTER_ROUTER_BASE}" \
     --set redhat-developer-hub.global.imageRegistry="<disconnected_registry_url>" \
     --set redhat-developer-hub.global.pluginMode=oci

   To also set ociPluginImage via --set:

     --set redhat-developer-hub.global.ociPluginImage="<disconnected_registry_url>/custom-path/automation-portal"

   HTTP plug-in registry delivery:

   $ helm install redhat-rhaap-portal \
     redhat-rhaap-portal-x.y.z.tgz \
     --namespace "${MY_NAMESPACE}" \
     --set redhat-developer-hub.global.clusterRouterBase="${MY_CLUSTER_ROUTER_BASE}" \
     --set redhat-developer-hub.global.imageRegistry="<disconnected_registry_url>" \
     --set redhat-developer-hub.global.pluginMode=tarball

Procedure

1. Obtain the CA certificate chain that signed your mirror registry’s TLS certificate. If the registry uses a certificate chain, include the full chain:

   $ cat registry.crt intermediate.crt root.crt > ca-bundle.crt

2. Create a ConfigMap from the CA certificate:

   $ oc create configmap registry-ca-crt \
     --from-file=ca.crt=ca-bundle.crt -n <namespace>

3. Add the volume and mount to your values file:

   redhat-developer-hub:
     upstream:
       backstage:
         extraVolumes:
           - name: registry-ca-crt
             configMap:
               name: registry-ca-crt
         initContainers:
           - name: install-dynamic-plugins
             volumeMounts:
               - name: registry-ca-crt
                 mountPath: /etc/containers/certs.d/<registry-host>
                 readOnly: true

Procedure

1. Log in to self-service automation portal with an account that has Ansible Automation Platform administrator privileges.
2. In the navigation pane of self-service automation portal, select Administration → RBAC.
3. Click Create to create a new role and enter a name, for example portal-users.

4. Click Next.

   

5. In the Users and Groups section, select the Ansible Automation Platform teams and users to assign to this role, then click Next.

   
   Note

   The Members column displays the total count of users in each team, including both regular team members and administrators.

   You can only select Ansible Automation Platform teams and users from the Ansible Automation Platform Organization that you have configured for synchronization with self-service automation portal.

6. Click Next to configure permissions in the Add permission policies section:

   1. Select the Catalog plugin from the Select plugins dropdown menu.

   2. Select the checkbox for catalog.entity.read.

      

7. Select the Scaffolder plugin and enable all scaffolder permissions:

   • scaffolder.template.parameter.read
   • scaffolder.template.step.read
   • scaffolder.action.execute
   • scaffolder.task.cancel
   • scaffolder.task.create

   • scaffolder.task.read

     Note

     The scaffolder.task.read permission must be enabled so that users can view previous task runs in the History page in the self-service automation portal console.

8. Click Next to review your settings, then Create to create the new role.

   On successful completion, your new role is included in the All roles list when you select Administration → RBAC in the navigation pane in self-service automation portal.

Procedure

1. Log in to self-service automation portal with an account that has Ansible Automation Platform administrator privileges.
2. In the navigation pane of self-service automation portal, select Administration → RBAC.
3. Click Create to create a new role and enter a name, for example network-templates.
4. Click Next.

5. In the Users and Groups section, select the Ansible Automation Platform teams and users to assign to this role (for example, the Ansible Automation Platform network-team), then click Next.

   
   Note

   The Members column displays the total count of users in each team, including both regular team members and administrators.

   You can only select Ansible Automation Platform teams and users from the Ansible Automation Platform Organization that you are using in self-service automation portal.

6. Click Next to configure permissions in the Add permission policies section:

   • Select the Catalog plugin from the Select plugins dropdown menu.
   • Select the checkbox for catalog.entity.read.
   • Click Conditional to configure a condition-based policy.

7. In the condition builder, configure a rule to filter by tag:

   • Rule: Select HAS_METADATA from the dropdown menu
   • Key: Enter tags
   • Value: Enter the tag value to filter by (for example, network-automation)

8. Select the Scaffolder plugin and enable all scaffolder permissions:

   • scaffolder.template.parameter.read
   • scaffolder.template.step.read
   • scaffolder.action.execute
   • scaffolder.task.cancel
   • scaffolder.task.create
   • scaffolder.task.read
9. Click Next to review your settings, then click Create to create the new role.

1. Log in to self-service automation portal as a non-Ansible Automation Platform administrator user who is a member of a team you granted permissions to.

2. Verify that the user can see auto-generated templates in self-service automation portal.

   • If you configured conditional access by tag, the user should see only templates with the specified tags.
   • If you did not configure conditional access, the user should see all Ansible Automation Platform job templates for which they have job template Execute permissions in Ansible Automation Platform.

3. To verify execution permissions work correctly, attempt to execute a template:

   1. If the user has job template Execute permissions in Ansible Automation Platform for the template, the user can view the template, and the job launches successfully.

1. Check your current plug-in bundle version:

   oc exec $(oc get pods -l deployment=plugin-registry -o jsonpath='{.items[0].metadata.name}') -- \
     ls -l /opt/app-root/src | grep ansible-plugin

   The version number appears in the plug-in file names.

2. Identify your Helm chart version:

   helm list -n <namespace>

   Look for your self-service automation portal release and note the chart version.

3. If the versions do not match:

   1. Download the correct plug-in bundle version from the Red Hat Ansible Automation Platform Product Software downloads page.
   2. Update your plug-in registry following the procedure in Section 8.2, “Download plug-ins and push to the registry”.
   3. Wait for the self-service automation portal pods to restart automatically.

1. Check the pod logs for specific error messages:

   oc logs -n <namespace> <pod_name> --previous

2. If you see database migration errors:

   1. Verify that your database is accessible:

      oc exec -it -n <namespace> <pod_name> -- pg_isready -h <database_host>

   2. Check database connection secrets:

      oc get secret -n <namespace> | grep -i database

   3. If you use an external database, verify that the database user has the required permissions.

3. If you see configuration errors:

   1. Review your Helm values for syntax errors:

      helm get values <release_name> -n <namespace>

   2. Compare with your previous working configuration to identify changes.
   3. Revert problematic configuration changes and upgrade again.

1. Upgrade your Ansible Automation Platform instance to version 2.6 before you upgrade self-service automation portal.

   The self-service automation portal version that is compatible with Ansible Automation Platform 2.6 requires Ansible Automation Platform 2.6 features for full functionality.

2. Review the Ansible Automation Platform 2.6 release notes for breaking changes that affect self-service automation portal.

3. Back up your existing self-service automation portal configuration before you upgrade:

   helm get values <release_name> -n <namespace> > backup-values.yaml

4. After you upgrade, verify that OAuth authentication still functions:

   1. Check that your OAuth application in Ansible Automation Platform is configured correctly.
   2. Test the sign-in functionality.
   3. If authentication fails, verify that the OAuth redirect URL matches your upgraded deployment URL.
5. Update any custom templates or configurations to use syntax that is compatible with the new self-service automation portal version.

1. List all Helm releases in your cluster:

   helm list --all-namespaces

2. Identify the correct release name and namespace for your self-service automation portal deployment.

3. Run the upgrade command with the correct parameters:

   helm upgrade <correct_release_name> openshift-helm-charts/redhat-rhaap-portal \
     --version <target_version> \
     -n <correct_namespace>

1. Before you upgrade, export your current values:

   helm get values <release_name> -n <namespace> > current-values.yaml

2. When you upgrade, specify your values file:

   helm upgrade <release_name> openshift-helm-charts/redhat-rhaap-portal \
     --version <target_version> \
     -f current-values.yaml \
     -n <namespace>

3. After you upgrade, verify that your custom values are still applied:

   helm get values <release_name> -n <namespace>