Configuring dynamic plugins

Procedure

1. In the app-config.yaml file in your Backstage instance, add the following customResources component under the kubernetes configuration to enable Argo Rollouts and AnalysisRuns:

   kubernetes:
     ...
     customResources:
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'Rollouts'
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'analysisruns'

   Copy to Clipboard Toggle word wrap

2. Grant ClusterRole permissions for custom resources.

   Note
   • If the Backstage Kubernetes plugin is already configured, the ClusterRole permissions for Rollouts and AnalysisRuns might already be granted.
   • Use the prepared manifest to provide read-only ClusterRole access to both the Kubernetes and ArgoCD plugins.
   1. If the ClusterRole permission is not granted, use the following YAML manifest to create the ClusterRole:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: backstage-read-only
   rules:
     - apiGroups:
         - argoproj.io
       resources:
         - rollouts
         - analysisruns
       verbs:
         - get
         - list

   Copy to Clipboard Toggle word wrap

   1. Apply the manifest to the cluster using kubectl:

      kubectl apply -f <your-clusterrole-file>.yaml

      Copy to Clipboard Toggle word wrap
   2. Ensure the ServiceAccount accessing the cluster has this ClusterRole assigned.

3. Add annotations to catalog-info.yaml to identify Kubernetes resources for Backstage.

   1. For identifying resources by entity ID:

      annotations:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

      Copy to Clipboard Toggle word wrap

   2. (Optional) For identifying resources by namespace:

      annotations:
        ...
        backstage.io/kubernetes-namespace: <RESOURCE_NAMESPACE>

      Copy to Clipboard Toggle word wrap

   3. For using custom label selectors, which override resource identification by entity ID or namespace:

      annotations:
        ...
        backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'

      Copy to Clipboard Toggle word wrap
      Note

      Ensure you specify the labels declared in backstage.io/kubernetes-label-selector on your Kubernetes resources. This annotation overrides entity-based or namespace-based identification annotations, such as backstage.io/kubernetes-id and backstage.io/kubernetes-namespace.

4. Add label to Kubernetes resources to enable Backstage to find the appropriate Kubernetes resources.

   1. Backstage Kubernetes plugin label: Add this label to map resources to specific Backstage entities.

      labels:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

      Copy to Clipboard Toggle word wrap

   2. GitOps application mapping: Add this label to map Argo CD Rollouts to a specific GitOps application

      labels:
        ...
        app.kubernetes.io/instance: <GITOPS_APPLICATION_NAME>

      Copy to Clipboard Toggle word wrap
   Note

   If using the label selector annotation (backstage.io/kubernetes-label-selector), ensure the specified labels are present on the resources. The label selector will override other annotations like kubernetes-id or kubernetes-namespace.

Verification

1. Push the updated configuration to your GitOps repository to trigger a rollout.
2. Open Red Hat Developer Hub interface and navigate to the entity you configured.
3. Select the CD tab and then select the GitOps application. The side panel opens.

4. In the Resources table of the side panel, verify that the following resources are displayed:

   • Rollouts
   • AnalysisRuns (optional)

5. Expand a rollout resource and review the following details:

   • The Revisions row displays traffic distribution details for different rollout versions.
   • The Analysis Runs row displays the status of analysis tasks that evaluate rollout success.

1. Set the proxy to the desired JFrog Artifactory server in the app-config.yaml file as follows:

   proxy:
     endpoints:
       ‘/jfrog-artifactory/api’:
         target: http://<hostname>:8082 # or https://<customer>.jfrog.io
         headers:
         # Authorization: 'Bearer <YOUR TOKEN>'
         # Change to "false" in case of using a self-hosted Artifactory instance with a self-signed certificate
         secure: true

   Copy to Clipboard Toggle word wrap

2. Add the following annotation to the entity’s catalog-info.yaml file to enable the JFrog Artifactory plugin features in RHDH components:

   metadata:
       annotations:
         'jfrog-artifactory/image-name': '<IMAGE-NAME>'

   Copy to Clipboard Toggle word wrap

1. Set the proxy to the desired Nexus Repository Manager server in the app-config.yaml file as follows:

   proxy:
       '/nexus-repository-manager':
       target: 'https://<NEXUS_REPOSITORY_MANAGER_URL>'
       headers:
           X-Requested-With: 'XMLHttpRequest'
           # Uncomment the following line to access a private Nexus Repository Manager using a token
           # Authorization: 'Bearer <YOUR TOKEN>'
       changeOrigin: true
       # Change to "false" in case of using self hosted Nexus Repository Manager instance with a self-signed certificate
       secure: true

   Copy to Clipboard Toggle word wrap

2. Optional: Change the base URL of Nexus Repository Manager proxy as follows:

   nexusRepositoryManager:
       # default path is `/nexus-repository-manager`
       proxyPath: /custom-path

   Copy to Clipboard Toggle word wrap

3. Optional: Enable the following experimental annotations:

   nexusRepositoryManager:
       experimentalAnnotations: true

   Copy to Clipboard Toggle word wrap

4. Annotate your entity using the following annotations:

   metadata:
       annotations:
       # insert the chosen annotations here
       # example
       nexus-repository-manager/docker.image-name: `<ORGANIZATION>/<REPOSITORY>`,

   Copy to Clipboard Toggle word wrap

Procedure

1. The Bulk Import plugins are installed but disabled by default. To enable the ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic and ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import plugins, edit your dynamic-plugins.yaml with the following content:

   dynamic-plugins.yaml fragment

   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic
       disabled: false
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
       disabled: false

   Copy to Clipboard Toggle word wrap

   See Installing and viewing plugins in Red Hat Developer Hub.

2. Configure the required bulk.import RBAC permission for the users who are not administrators as follows:

   rbac-policy.csv fragment

   p, role:default/bulk-import, bulk.import, use, allow
   g, user:default/<your_user>, role:default/bulk-import

   Copy to Clipboard Toggle word wrap

   Note that only Developer Hub administrators or users with the bulk.import permission can use the Bulk Import feature. See Permission policies in Red Hat Developer Hub.

Procedure

1. Click Bulk Import in the left sidebar.

2. Click the Add button in the top-right corner to see the list of all repositories accessible from the configured GitHub integrations.

   1. From the Repositories view, you can select any repository, or search for any accessible repositories. For each repository selected, a catalog-info.yaml is generated.
   2. From the Organizations view, you can select any organization by clicking Select in the third column. This option allows you to select one or more repositories from the selected organization.

3. Click Preview file to view or edit the details of the pull request for each repository.

   1. Review the pull request description and the catalog-info.yaml file content.
   2. Optional: when the repository has a .github/CODEOWNERS file, you can select the Use CODEOWNERS file as Entity Owner checkbox to use it, rather than having the content-info.yaml contain a specific entity owner.
   3. Click Save.

4. Click Create pull requests. At this point, a set of dry-run checks runs against the selected repositories to ensure they meet the requirements for import, such as:

   1. Verifying that there is no entity in the Developer Hub catalog with the name specified in the repository catalog-info.yaml
   2. Verifying that the repository is not empty

   3. Verifying that the repository contains a .github/CODEOWNERS file if the Use CODEOWNERS file as Entity Owner checkbox is selected for that repository

      • If any errors occur, the pull requests are not created, and you see a Failed to create PR error message detailing the issues. To view more details about the reasons, click Edit.
      • If there are no errors, the pull requests are created, and you are redirected to the list of added repositories.
5. Review and merge each pull request that creates a catalog-info.yml file.

Procedure

1. Click Bulk Import in the left sidebar to display all the current repositories that are being tracked as Import jobs, along with their status.

   Added

   The repository is added to the Developer Hub catalog after the import pull request is merged or if the repository already contained a catalog-info.yaml file during the bulk import. Note that it may take a few minutes for the entities to be available in the catalog.

   Waiting for approval

   There is an open pull request adding a catalog-info.yaml file to the repository. You can:

   • Click the pencil icon on the right to see details about the pull request or edit the pull request content right from Developer Hub.
   • Delete the Import job, this action closes the import PR as well.
   • To transition the Import job to the Added state, merge the import pull request from the Git repository.

   Empty

   Developer Hub is unable to determine the import job status because the repository is imported from other sources but does not have a catalog-info.yaml file and lacks any import pull request adding it.

Procedure

1. To activate the custom actions plugin, add a package with plugin name and update the disabled field in your Helm chart as follows:

   global:
     dynamic:
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-servicenow-dynamic
           disabled: false

   Copy to Clipboard Toggle word wrap
   Note

   The default configuration for a plugin is extracted from the dynamic-plugins.default.yaml file, however, you can use a pluginConfig entry to override the default configuration.

2. Set the following variables in the Helm chart to access the custom actions:

   servicenow:
     # The base url of the ServiceNow instance.
     baseUrl: ${SERVICENOW_BASE_URL}
     # The username to use for authentication.
     username: ${SERVICENOW_USERNAME}
     # The password to use for authentication.
     password: ${SERVICENOW_PASSWORD}

   Copy to Clipboard Toggle word wrap