Procedure

1. In your Red Hat Developer Hub navigation menu, click Catalog.
2. On the Catalog page, click Self-service.

Procedure

1. In the root directory of your software project, create a file named catalog-info.yaml.

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
       name: _<your_software_component>_
       description: _<software_component_brief_description>_
       tags:
            - example
            - service
       annotations:
            github.com/project-slug: _<repo_link_of_your_component_to_register>_
   spec:
       type: _<your_service>_
       owner: _<your_team_name>_
       lifecycle: _<your_lifecycle>_

2. Commit the catalog-info.yaml file to the root of your project source code repository.
3. In your Red Hat Developer Hub navigation menu, go to Catalog > Self-service.
4. On the Self-service page, click Register Existing Component.
5. On the Register an existing component page, enter the full URL of the catalog-info.yaml file in your repository. For example: Artist lookup component.
6. Complete the wizard instructions.

Procedure

1. Configure the Bulk Import plugin by editing your app-config.yaml file to enable Orchestrator mode.

   bulkImport:
     orchestratorWorkflow: your_workflow_id
     importAPI: 'orchestrator'

   where:

   orchestratorWorkflow

   The ID of the workflow to run for each repository.

   importAPI

   The execution mode for the workflow. Enter orchestrator to enable workflow execution.

2. Verify that the Orchestrator workflow receives the following input:

   {
     "inputData": {
       "owner": "redhat-developer",
       "repo": "rhdh-plugins",
       "baseBranch": "main",
       "targetBranch": "bulk-import-orchestrator"
     },
     "authTokens": [
       {
         "token": "<github_token>",
         "provider": "github"
       }
     ]
   }

   where:

   owner

   Specifies the repository owner (organization or user name).

   repo

   Specifies the repository name.

   baseBranch

   Specifies the default branch of the Git repository (for example, main).

   targetBranch

   Specifies the target branch for the import operation. By default, this is set to bulk-import-orchestrator.

   authTokens

   Specifies the authentication tokens for the Git provider:

3. For GitHub: { token: <github_token>, provider: github }
4. For GitLab: { token: <gitlab_token>, provider: gitlab }

5. Navigate to the Bulk Import page in the sidebar and complete the following steps:

   1. Select your Git provider (for example, GitHub or GitLab).
   2. Select the projects you want to import.
6. Click import to run the workflow.

Procedure

1. Use the kn-workflow CLI to create a new workflow project, which adheres to the Quarkus structure as shown in the following example:

   $ kn-workflow quarkus create --name <specify project name, for example ,00_new_project>

2. Edit the workflow, add schema and specific files, and run it locally from project folder as shown in the following example:

   $ kn-workflow quarkus run

3. Run the workflow locally using the kn-workflow run which pulls the following image:

   registry.redhat.io/openshift-serverless-1/logic-swf-devmode-rhel9:1.38.0

4. For building the workflow image, the kn-workflow CLI pulls the following images:

   registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.38.0
   registry.access.redhat.com/ubi9/openjdk-17:1.21-2

Procedure

1. Clone the project as shown in the following example:

   git clone git@github.com:rhdhorchestrator/orchestrator-demo.git
   cd orchestrator-demo

2. Check the help menu of the script:

   ./scripts/build.sh --help

3. Run the build.sh script, providing the required flags, for example, the image path (-i), workflow source directory (-w), and manifests output directory (-m).

   Important

   You must specify the full target image path with a tag as shown in the following example:

   ./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests

Procedure

1. Run the following command:

   $ ./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests

   This build command produces the following two artifacts:

2. A workflow image and Kubernetes manifests: quay.io/orchestrator/demo-basic:test and tagged as latest.
3. Kubernetes manifests under: 01_basic/manifests/
4. Optional: You can add the --push flag to automatically push the image after building. Otherwise, pushing manually is mandatory before deploying.

Procedure

1. Install the orchestrator-software-templates-infra chart.
2. Install the orchestrator-software-templates chart.

Procedure

1. Install the software templates chart:

   $ helm repo add redhat-developer https://redhat-developer.github.io/rhdh-chart
   $ helm install my-orchestrator-templates redhat-developer/orchestrator-software-templates --version 0.2.0

2. Create your environment-specific values file:

   1. Retrieve your RHDH route URL:

      RHDH_ROUTE="https://$(oc get route -n {{ .Values.orchestratorTemplates.rhdhChartNamespace }} -o jsonpath='{.items[0].spec.host}')"

   2. Copy the template and replace placeholders

      cp charts/orchestrator-software-templates/orchestrator-templates-values.yaml.template orchestrator-templates-values.yaml
      sed -i "s|RHDH_BASE_URL|$RHDH_ROUTE|g" orchestrator-templates-values.yaml

3. Backup your RHDH configuration:

   helm show values charts/backstage \
        -n {{ .Values.orchestratorTemplates.rhdhChartNamespace }} > current-backstage-values.yaml

4. Upgrade the RHDH chart with both value files:

    helm upgrade {{ .Values.orchestratorTemplates.rhdhChartReleaseName }} charts/backstage \
        -n {{ .Values.orchestratorTemplates.rhdhChartNamespace }} \
        -f current-backstage-values.yaml \
        -f orchestrator-templates-values.yaml

Verification

1. Wait for the deployment to complete.
2. Open your RHDH instance and verify the new software templates appear in the Create menu.

Procedure

1. Create an ImageSetConfiguration file for oc mirror. You must include the images and operators required by the Serverless Logic Operator in the ImageSetConfiguration file, as shown in the following example:

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     additionalimages:
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@<digest>
   
     operators:
       - catalog: registry.redhat.io/redhat/redhat-operator-index:v<ocp-version>
        # For example: registry.redhat.io/redhat/redhat-operator-index:v4.21
         packages:
         - name: logic-operator
           channels:
           - name: stable
             minVersion: 1.38.0
             maxVersion: 1.38.0
         - name: serverless-operator
           channels:
           - name: stable
             minVersion: 1.37.1
             maxVersion: 1.37.1

   where:

   <digest>

   Locate the image digests for your version of RHDH in the dynamic-plugins.default.yaml file. You can extract this file from the plugin catalog index image to verify the default settings for your specific release:

   #!/bin/bash
   
   unpack () {
     local IMAGE="$1"
     DIR="${IMAGE//:/}" DIR="/tmp/${DIR//\//-}" rm -fr "$DIR"; mkdir -p "$DIR"; container_id=$(podman create "${IMAGE}") podman export $container_id -o /tmp/image.tar && tar xf /tmp/image.tar -C "${DIR}/"; podman rm $container_id; rm -f /tmp/image.tar echo "Unpacked $IMAGE into $DIR" cd $DIR; tree -d -L 3 -I "usr|root|buildinfo" } unpack "registry.access.redhat.com/rhdh/plugin-catalog-index:{product-version)" # you can then find the dynamic-plugins.default.yaml under /tmp/registry.access.redhat.com/rhdh/plugin-catalog-index{product-version)/dynamic-plugins.default.yaml

2. Mirror the images in the ImageSetConfiguration.yaml file by running the oc mirror command. For example:

   $ oc mirror --config=ImageSetConfiguration.yaml file:///path/to/mirror-archive --authfile /path/to/authfile --v2

   Note

   1. The --v2 flag is required for OpenShift Container Platform 4.21 and later.
   2. The oc mirror command generates a local workspace containing the mirror archive files and the required cluster manifests.
3. Transfer the directory specified by /path/to/mirror-archive to a bastion host within your disconnected environment.

4. From the bastion host which has access to the mirror registry, mirror the images from the disk directory to your target registry. For example:

   $ oc mirror --v2 --from <mirror-archive-file> docker://<target-registry-url:port> --workspace file://<workspace folder> --authfile /path/to/authfile

   where:

   <mirror-archive-file>

   Enter the name of the transferred tar file.

   <target-registry-url:port>

   Enter your local registry, for example, registry.localhost:5000.

5. Apply the cluster-wide resources generated during the push step to redirect all image pulls to your local registry, as shown in the following example:

   $ cd <workspace folder>/working-dir/cluster-resources/
   $ oc apply -f .

6. Install the OpenShift Serverless Operator and OpenShift Serverless Logic Operators using OperatorHub.
7. Create a Backstage custom resource (CR).

8. Configure the Backstage CR for the Orchestrator as described in the Orchestrator plugin dependencies for Operator installation.

   Create all the resources and configure the Backstage instance accordingly.

Verification

1. Restart the RHDH pod and wait for the components to deploy properly.
2. Once stable, go to the RHDH UI, and confirm that the Orchestrator UI is accessible and functioning correctly.

Procedure

1. Create an ImageSetConfiguration file for oc mirror. You must include the images and operators required by the Serverless Logic Operator in the ImageSetConfiguration file, as shown in the following example:

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     additionalimages:
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@<digest>
   
     operators:
       - catalog: registry.redhat.io/redhat/redhat-operator-index:v<ocp-version>
        # For example: registry.redhat.io/redhat/redhat-operator-index:v4.21
         packages:
         - name: logic-operator
           channels:
           - name: stable
             minVersion: 1.38.0
             maxVersion: 1.38.0
         - name: serverless-operator
           channels:
           - name: stable
             minVersion: 1.37.1
             maxVersion: 1.37.1

   Where:

   <digest>

   Locate the image digests for your version of RHDH in the dynamic-plugins.default.yaml file. You can extract this file from the plugin catalog index image to verify the default settings for your specific release:

   #!/bin/bash
   
   unpack () {
     local IMAGE="$1"
     DIR="${IMAGE//:/}" DIR="/tmp/${DIR//\//-}" rm -fr "$DIR"; mkdir -p "$DIR"; container_id=$(podman create "${IMAGE}") podman export $container_id -o /tmp/image.tar && tar xf /tmp/image.tar -C "${DIR}/"; podman rm $container_id; rm -f /tmp/image.tar echo "Unpacked $IMAGE into $DIR" cd $DIR; tree -d -L 3 -I "usr|root|buildinfo" } unpack "registry.access.redhat.com/rhdh/plugin-catalog-index:{product-version)" # you can then find the dynamic-plugins.default.yaml under /tmp/registry.access.redhat.com/rhdh/plugin-catalog-index{product-version)/dynamic-plugins.default.yaml

2. Mirror the images in the ImageSetConfiguration.yaml file by running the oc mirror command. For example:

   $ oc mirror --config=imagesetconfiguration.yaml docker://<registry URL:port> --workspace file://<workspace folder> --authfile /path/to/authfile --v2
   $ cd <workspace folder>/working-dir/cluster-resources/
   $ oc apply -f .

   Note

   The --v2 flag is required for OpenShift Container Platform 4.21 and later.

3. Install the OpenShift Serverless Operator and OpenShift Serverless Logic Operators using OperatorHub.
4. Create a Backstage custom resource (CR).

5. Configure the Backstage CR for the Orchestrator as described in the Orchestrator plugin dependencies for Operator installation.

   Create all the resources and configure the Backstage instance accordingly.

Verification

1. Restart the RHDH pod and wait for the components to deploy properly.
2. Once stable, go to the RHDH UI, and confirm that the Orchestrator UI is accessible and functioning correctly.

Procedure

1. Create an ImageSetConfiguration.yaml file for oc mirror. You must use an ImageSetConfiguration file to include all mirrored images required, as shown in the following example:

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     additionalimages:
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@<digest>
   
     helm:
       repositories:
         - name: openshift-charts
           url: https://charts.openshift.io
           charts:
             - name: redhat-developer-hub
               version: "1.10.0"
             - name: redhat-developer-hub-orchestrator-infra
               version: "1.10.0"
     operators:
       - catalog: registry.redhat.io/redhat/redhat-operator-index:v<ocp-version>
        # For example: registry.redhat.io/redhat/redhat-operator-index:v4.21
         packages:
         - name: logic-operator
           channels:
           - name: stable
             minVersion: 1.38.0
             maxVersion: 1.38.0
         - name: serverless-operator
           channels:
           - name: stable
             minVersion: 1.37.1
             maxVersion: 1.37.1

   where:

   <digest>

   Locate the image digests for your version of RHDH in the dynamic-plugins.default.yaml file. You can extract this file from the plugin catalog index image to verify the default settings for your specific release:

   #!/bin/bash
   
   unpack () {
     local IMAGE="$1"
     DIR="${IMAGE//:/_}"
     DIR="/tmp/${DIR//\//-}"
     rm -fr "$DIR"; mkdir -p "$DIR"; container_id=$(podman create "${IMAGE}")
     podman export $container_id -o /tmp/image.tar && tar xf /tmp/image.tar -C "${DIR}/"; podman rm $container_id; rm -f /tmp/image.tar
     echo "Unpacked $IMAGE into $DIR"
     cd $DIR; tree -d -L 3 -I "usr|root|buildinfo"
   }
   
   unpack "registry.access.redhat.com/rhdh/plugin-catalog-index:1.10"
   
   # you can then find the dynamic-plugins.default.yaml under /tmp/registry.access.redhat.com/rhdh/plugin-catalog-index_1.10/dynamic-plugins.default.yaml

2. Mirror the images in the ImageSetConfiguration.yaml file by running the oc mirror command. For example:

   $ oc mirror --config=ImageSetConfiguration.yaml file:///path/to/mirror-archive --authfile /path/to/authfile --v2

   Note

   1. The --v2 flag is required for OpenShift Container Platform 4.21 and later.
   2. The oc mirror command pulls the charts listed in the ImageSetConfiguration file and makes them available as tgz archives under the /path/to/mirror-archive directory.

3. Apply the cluster-wide resources generated during the push step to redirect all image pulls to your local registry, as shown in the following example:

   $ cd <workspace folder>/working-dir/cluster-resources/
   $ oc apply -f .

4. Transfer the generated mirror archive file, for example, /path/to/mirror-archive/mirror_000001.tar, to a bastion host within your disconnected environment.

5. From the bastion host in your disconnected environment, which has access to the mirror registry, mirror the images from the archive file to your target registry. For example:

   $ oc mirror --v2 --from <mirror-archive-file> docker://<target-registry-url:port> --workspace file://<workspace folder> --authfile /path/to/authfile

   where:

   <mirror-archive-file>

   Enter the name of the transferred tar file.

   <target-registry-url:port>

   Enter your local registry, for example, registry.localhost:5000.

6. Apply the redhat-developer-hub-orchestrator-infra Helm chart and approve the install plans. See Air-gapped installation with Helm chart instructions for details.

7. Apply the RHDH 1.10 Helm chart. Include the version 1.10.0 and enable the Orchestrator plugin, as shown in the following example:

   orchestrator.enabled=true

8. The RHDH 1.10 Helm chart defaults to pulling Orchestrator plugins from the official Red Hat OCI registry using full URL references. Override this default behavior to point the chart to your local registry.

   To configure the Orchestrator plugins to use a custom registry, complete the following steps:

9. Open your values.yaml file.

10. List the Orchestrator plugin packages under the orchestrator.plugins section. You must replace the simplified package references with the full URLs that point to your custom OCI registry.

    Important

    You must explicitly include the pluginConfig configuration for each plugin as shown in the following example:

    orchestrator:
      plugins:
        - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@_<digest>_
          disabled: true
          pluginConfig:
            orchestrator:
              dataIndexService:
                url: http://sonataflow-platform-data-index-service
        - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@_<digest>_
          disabled: true
          pluginConfig:
            dynamicPlugins:
              frontend:
                red-hat-developer-hub.backstage-plugin-orchestrator-form-widgets: {}
        - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@_<digest>_
          disabled: true
          pluginConfig:
            dynamicPlugins:
              frontend:
                red-hat-developer-hub.backstage-plugin-orchestrator:
                  appIcons:
                  - importName: OrchestratorIcon
                    name: orchestratorIcon
                  dynamicRoutes:
                  - importName: OrchestratorPage
                    menuItem:
                      icon: orchestratorIcon
                      text: Orchestrator
                      textKey: menuItem.orchestrator
                    path: /orchestrator
                  entityTabs:
                  - path: /workflows
                    title: Workflows
                    titleKey: catalog.entityPage.workflows.title
                    mountPoint: entity.page.workflows
                  mountPoints:
                  - mountPoint: entity.page.workflows/cards
                    importName: OrchestratorCatalogTab
                    config:
                      layout:
                        gridColumn: 1 / -1
                      if:
                        anyOf:
                          - IsOrchestratorCatalogTabAvailable
        - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@_<digest>_
          disabled: true
          pluginConfig:
            orchestrator:
              dataIndexService:
                url: http://sonataflow-platform-data-index-service

    where:

    <custom_registry_url>

    Enter the address of your custom registry where the OCI images have been mirrored.

    <digest>

    Locate the image digests for your version of RHDH in the dynamic-plugins.default.yaml file. You can extract this file from the plugin catalog index image to verify the default settings for your specific release:

    #!/bin/bash
    
    unpack () {
      local IMAGE="$1"
      DIR="${IMAGE//:/}" DIR="/tmp/${DIR//\//-}" rm -fr "$DIR"; mkdir -p "$DIR"; container_id=$(podman create "${IMAGE}") podman export $container_id -o /tmp/image.tar && tar xf /tmp/image.tar -C "${DIR}/"; podman rm $container_id; rm -f /tmp/image.tar echo "Unpacked $IMAGE into $DIR" cd $DIR; tree -d -L 3 -I "usr|root|buildinfo" } unpack "registry.access.redhat.com/rhdh/plugin-catalog-index:{product-version)" # you can then find the dynamic-plugins.default.yaml under /tmp/registry.access.redhat.com/rhdh/plugin-catalog-index{product-version)/dynamic-plugins.default.yaml

Verification

1. Restart the RHDH Pod and wait for the components to deploy properly.
2. After deployment is complete, go to the RHDH UI and confirm that the Orchestrator UI is accessible and functioning correctly.

Procedure

1. Create an ImageSetConfiguration.yaml file for oc mirror. You must use an ImageSetConfiguration file to include all mirrored images required, as shown in the following example:

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     additionalimages:
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@<digest>
     - name: registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@<digest>
   
     helm:
       repositories:
         - name: openshift-charts
           url: https://charts.openshift.io
           charts:
             - name: redhat-developer-hub
               version: "1.10.0"
             - name: redhat-developer-hub-orchestrator-infra
               version: "1.10.0"
     operators:
       - catalog: registry.redhat.io/redhat/redhat-operator-index:v<ocp-version>
        # For example: registry.redhat.io/redhat/redhat-operator-index:v4.21
         packages:
         - name: logic-operator
           channels:
           - name: stable
             minVersion: 1.38.0
             maxVersion: 1.38.0
         - name: serverless-operator
           channels:
           - name: stable
             minVersion: 1.37.1
             maxVersion: 1.37.1

2. Mirror the images in the ImageSetConfiguration.yaml file by running the oc mirror command to pull images and charts, and push the images directly to the target registry. For example:

   $ oc mirror --config=imagesetconfiguration.yaml docker://<registry URL:port> --workspace file://<workspace folder> --authfile /path/to/authfile --v2

   Note

   1. The --v2 flag is required for OpenShift Container Platform 4.21 and later.
   2. The oc mirror command pulls the charts listed in the ImageSetConfiguration file and makes them available as tgz archives under the <workspace folder> directory.

3. Apply the generated cluster resources to the disconnected cluster. For example:

   $ cd <workspace folder>/working-dir/cluster-resources/
   $ oc apply -f .

4. Apply the redhat-developer-hub-orchestrator-infra Helm chart and approve the install plans. See Air-gapped installation with Helm chart instructions for details.

5. Apply the RHDH 1.10 Helm chart. Include the version 1.10.0 and enable the Orchestrator plugin, as shown in the following example:

   orchestrator.enabled=true

6. The RHDH 1.10 Helm chart defaults to pulling Orchestrator plugins from the official Red Hat OCI registry using full URL references. You must override this behavior to point to your local registry.

   To configure the Orchestrator plugins to use a custom registry, complete the following steps:

   • Open your values.yaml file.

   • Explicitly list the Orchestrator plugin packages under the orchestrator.plugins section.

     You must replace the simplified package references with the full URLs that point to your custom OCI registry. You must explicitly include the pluginConfig configuration for each plugin as shown in the following example:

     orchestrator:
       plugins:
         - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@_<digest>_
           disabled: true
           pluginConfig:
             orchestrator:
               dataIndexService:
                 url: http://sonataflow-platform-data-index-service
         - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets@_<digest>_
           disabled: true
           pluginConfig:
             dynamicPlugins:
               frontend:
                 red-hat-developer-hub.backstage-plugin-orchestrator-form-widgets: {}
         - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator@_<digest>_
           disabled: true
           pluginConfig:
             dynamicPlugins:
               frontend:
                 red-hat-developer-hub.backstage-plugin-orchestrator:
                   appIcons:
                   - importName: OrchestratorIcon
                     name: orchestratorIcon
                   dynamicRoutes:
                   - importName: OrchestratorPage
                     menuItem:
                       icon: orchestratorIcon
                       text: Orchestrator
                       textKey: menuItem.orchestrator
                     path: /orchestrator
                   entityTabs:
                   - path: /workflows
                     title: Workflows
                     titleKey: catalog.entityPage.workflows.title
                     mountPoint: entity.page.workflows
                   mountPoints:
                   - mountPoint: entity.page.workflows/cards
                     importName: OrchestratorCatalogTab
                     config:
                       layout:
                         gridColumn: 1 / -1
                       if:
                         anyOf:
                           - IsOrchestratorCatalogTabAvailable
         - - package: oci://<custom_registry_url>/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator@_<digest>_
           disabled: true
           pluginConfig:
             orchestrator:
               dataIndexService:
                 url: http://sonataflow-platform-data-index-service

     Where:

     <custom_registry_url>

     Enter the address of your custom registry where the OCI images have been mirrored.

     <digest>

     Locate the image digests for your version of RHDH in the dynamic-plugins.default.yaml file. You can extract this file from the plugin catalog index image to verify the default settings for your specific release:

     #!/bin/bash
     
     unpack () {
       local IMAGE="$1"
       DIR="${IMAGE//:/}" DIR="/tmp/${DIR//\//-}" rm -fr "$DIR"; mkdir -p "$DIR"; container_id=$(podman create "${IMAGE}") podman export $container_id -o /tmp/image.tar && tar xf /tmp/image.tar -C "${DIR}/"; podman rm $container_id; rm -f /tmp/image.tar echo "Unpacked $IMAGE into $DIR" cd $DIR; tree -d -L 3 -I "usr|root|buildinfo" } unpack "registry.access.redhat.com/rhdh/plugin-catalog-index:{product-version)" # you can then find the dynamic-plugins.default.yaml under /tmp/registry.access.redhat.com/rhdh/plugin-catalog-index{product-version)/dynamic-plugins.default.yaml

Verification

1. Restart the RHDH pod and wait for the components to deploy properly.
2. After deployment is complete, go to the RHDH UI and confirm that the Orchestrator UI is accessible and functioning correctly.

Procedure

1. On the AWS console, create an AWS S3 bucket.

   1. On the Create bucket page, enter a Bucket name and use the default selections for all other settings.
   2. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.

   3. On the Create policy > Specify permissions page, in the Policy editor, enter the following JSON content:

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "TechDocsList",
                  "Effect": "Allow",
                  "Action": "s3:ListBucket",
                  "Resource": "arn:aws:s3:::_<bucket_name>_"
              },
              {
                  "Sid": "TechDocsObjects",
                  "Effect": "Allow",
                  "Action": [
                      "s3:GetObject",
                      "s3:PutObject",
                      "s3:DeleteObject",
                      "s3:DeleteObjectVersion"
                  ],
                  "Resource": "arn:aws:s3:::_<bucket_name>_/*"
              }
          ]
      }

      where

      <bucket_name>

      Specifies the name of your Amazon S3 bucket.

   4. On the Create policy > Specify permissions page, enter a Policy name.
2. Assign the IAM policy to a new or existing user.

3. Generate a new access key and a new secret access key.

   Note

   You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.

4. From the OpenShift Container Platform web console, click Topology > Actions > Restart rollout to restart the pod.

   Note

   You must restart the pod to apply the configuration changes.

Procedure

1. From the Developer perspective in the OpenShift Container Platform web console, click ConfigMaps > Create ConfigMap.
2. From the Create ConfigMap page, select the YAML view option in the Configure via field.

3. In the newly created ConfigMap, add the default backstage-plugin-techdocs-module-addons-contrib package configuration. For example:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

4. In the techdocsAddons section of the ConfigMap, add importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to add from the specified plugin package. For example:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   where:

   <external_techdocs_add-on>

   Specifies the external TechDocs add-on that you want to install, for example, TextSize or LightBox.

5. Click Create.
6. In the web console navigation menu, click Topology.
7. Click the overflow menu for the Red Hat Developer Hub instance that you want to use and select Edit Backstage to load the YAML view of the Red Hat Developer Hub instance.

8. In your Backstage CR, add the dynamicPluginsConfigMapName: <dynamic_plugins_configmap> key-value pair. For example:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: my-rhdh
   spec:
     application:
   # ...
       dynamicPluginsConfigMapName: <dynamic_plugins_configmap>
   # ...

   where:

   <dynamic_plugins_configmap>

   Specifies the name of your dynamic plugins ConfigMap for your Red Hat Developer Hub instance, for example, dynamic-plugins-rhdh.

9. Click Save.
10. In the web console navigation menu, click Topology and wait for the Red Hat Developer Hub pod to start.
11. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Procedure

1. In your Helm chart, add the global.dynamic parameters required to install a dynamic plugin, as shown in Installing dynamic plugins using the Helm chart

   Note

   The default configuration includes the dynamic-plugins.default.yaml file, which contains all of the dynamic plugins, including TechDocs add-ons, that are preinstalled in Red Hat Developer Hub, whether they are enabled or disabled by default.

2. In your Helm chart, add the default backstage-plugin-techdocs-module-addons-contrib package configuration. For example:

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

3. In the techdocsAddons section of the Helm chart, add importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to add from the specified plugin package. For example:

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   where:

   <external_techdocs_add-on>

   Specifies the external TechDocs add-on that you want to install, for example, TextSize or LightBox.

Procedure

1. From the Developer perspective in the OpenShift Container Platform web console, click ConfigMaps.
2. From the ConfigMaps page, click the ConfigMap that contains the TechDocs add-on that you want to remove.
3. Select the YAML view option in the Configure via field.

4. In the plugins section of the ConfigMap, do one of the following actions based on whether you want to disable or remove a TechDocs add-on:

   • To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the disabled field to true. For example:

     kind: ConfigMap
     apiVersion: v1
     metadata:
       name: dynamic-plugins-rhdh
     data:
       dynamic-plugins.yaml: |
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
             disabled: true
             pluginConfig:
               dynamicPlugins:
                 frontend:
                   backstage.plugin-techdocs-module-addons-contrib:
                     techdocsAddons:
                       - importName: ReportIssue
                       - importName: <external_techdocs_add-on>

     where:

     <external_techdocs_add-on>

     Specifies the external TechDocs add-on that you want to remove, for example, TextSize.

   • To remove one or more TechDocs add-ons from your Red Hat Developer Hub instance, delete importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to remove from the techdocsAddons section of your ConfigMap. For example:

     kind: ConfigMap
     apiVersion: v1
     metadata:
       name: dynamic-plugins-rhdh
     data:
       dynamic-plugins.yaml: |
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
             disabled: false
             pluginConfig:
               dynamicPlugins:
                 frontend:
                   backstage.plugin-techdocs-module-addons-contrib:
                     techdocsAddons:
                       - importName: ReportIssue
                       - importName: <external_techdocs_add-on>

     where:

     <external_techdocs_add-on>

     Specifies the external TechDocs add-on that you want to remove, for example, TextSize.

5. Click Save.
6. In the web console navigation menu, click Topology and wait for the Red Hat Developer Hub pod to start.
7. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Procedure

1. In your TechDocs documentation, highlight the text that you want to report an issue for.
2. Click the text in the ReportIssue box, for example, Open new GitHub issue.

3. From the new issue page in your repository, use the template to create the issue that you want to report.

   Note

   The default issue title is Documentation feedback: <highlighted_text>, where <highlighted_text> is the text that you highlighted in your TechDocs documentation.

   In the issue description, <highlighted_text> is the default value for the The highlighted text field.

Procedure

1. In your TechDocs header, click the Settings icon.

2. Use the sliding scale to adjust the size of your documentation text.

   Note

   1. The default text size is 100%
   2. The minimize text size is 90%
   3. The maximum text size is 150%

Procedure

1. In your TechDocs documentation, click the image that you want to view in a lightbox.
2. In the lightbox, you can do any of the following actions:
3. Click the image or scroll to zoom in or zoom out.
4. Click the arrow to navigate between images.

Procedure

1. Enable the Keycloak catalog provider plugin in your dynamic-plugins.yaml file.

   The plugin is named after RHBK upstream project.

   plugins:
     - package: './dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic'
       disabled: false

2. Add a catalog.providers.keycloakOrg section to your app-config.yaml file:

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           realm: ${KEYCLOAK_REALM}
           loginRealm: ${KEYCLOAK_LOGIN_REALM}

   baseUrl

   Enter your RHBK server URL, defined earlier.

   clientId

   Enter your Developer Hub application client ID in RHBK, defined earlier.

   clientSecret

   Enter your Developer Hub application client secret in RHBK, defined earlier.

   realm

   Enter the realm name to provision users.

   loginRealm

   Enter the realm name to authenticate users.

3. Optional: Add optional fields to the keycloackOrg catalog provider section in your app-config.yaml file:

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           realm: ${KEYCLOAK_REALM}
           loginRealm: ${KEYCLOAK_LOGIN_REALM}
           userQuerySize: 100
           groupQuerySize: 100
           schedule:
             frequency: { hours: 1 }
             timeout: { minutes: 50 }
             initialDelay: { seconds: 15}

   userQuerySize

   Enter the user count to query simultaneously. Default value: 100.

   groupQuerySize

   Enter the group count to query simultaneously. Default value: 100.

   schedule

   frequency

   Enter the schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.

   timeout

   Enter the timeout for the user provisioning job. Supports ISO duration and "human duration" as used in code.

   initialDelay

   Enter the initial delay to wait for before starting the user provisioning job. Supports ISO duration and "human duration" as used in code.

Procedure

1. Create a new backend module with the yarn new command.

   $ yarn new
   ? What type of module would you like to create? backend-plugin-module
   ? Enter the ID of the plugin [required] catalog
   ? Enter the ID of the module [required] keycloak-org-transformer

   The command creates a plugin named catalog-backend-module-keycloak-org-transformer.

2. Install required packages:

   $ yarn --cwd plugins/catalog-backend-module-keycloak-org-transformer add @backstage/plugin-catalog-backend-module-keycloak-org

3. Refer to the sample plugin and implement plugins/catalog-backend-module-keycloak-org-transformer/src/module.ts.

4. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.

   $ npx @red-hat-developer-hub/cli@latest plugin export \
     --embed-package @backstage/plugin-catalog-backend-module-keycloak-org

   Important

   Verify that the installed plugin version is compatible with the Backstage version.

   See the Dynamic plugins reference for the version to import.

5. Publish and enable the plugin in Developer Hub. For more information, see Installing and viewing plugins in Red Hat Developer Hub.

Verification

1. Every time that Developer Hub starts, it imports the users and groups. Check the console logs to verify the synchronization result.

   Successful synchronization example:

   {"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
   {"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}

2. After the first import is complete, go to the Catalog page and select User to view the list of users.
3. When you select a user, you see the information imported from RHBK. Verify that the user entities reflect the custom transformations you defined in the plugin.
4. You can select a group, view the list, and access or review the information imported from RHBK. Verify that the group entities reflect the custom transformations you defined in the plugin.
5. You can log in with an RHBK account.

Procedure

1. Enable the LDAP catalog provider plugin in your dynamic-plugins.yaml file.

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic'
       disabled: false

2. Enable provisioning LDAP users and groups to the Developer Hub software catalog, by adding the LDAP catalog provider section to your app-config.yaml file:

   1. Optional: Remove other catalog providers, by removing the other catalog providers section.

   2. Enter the mandatory fields:

      catalog:
        providers:
          ldapOrg:
            default:
              target: ldaps://ds.example.net
              bind:
                dn: cn=admin,ou=Users,dc=rhdh
                secret: ${LDAP_SECRET}
              users:
                - dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
                  options:
                    filter: (uid=*)
              groups:
                - dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
              schedule:
                frequency: PT1H
                timeout: PT15M

      target

      Enter your LDAP server URL, such as ldaps://ds.example.net.

      bind

      Enter your service account information:

      dn

      Enter your service account distinguished name (DN), such as cn=admin,OU=Users,DC=rhdh,DC=test

      secret

      Enter the name of the variable containing your LDAP secret: ${LDAP_SECRET}.

      users

      Enter information about how to find your users:

      dn

      Enter the DN containing the user information.

      options

      filter

      Enter your filter, such as (uid=*) to provision to the RHDH software catalog only users with an existing uid.

      groups

      Enter information about how to find your groups:

      dn

      Enter the DN containing the group information.

      schedule

      Enter your schedule information:

      frequency

      Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.

      timeout

      Enter your schedule timeout, in the ISO duration or "human duration" format.

      initialDelay

      Enter your schedule initial delay, in the ISO duration or "human duration" format.

   3. Optional: To change how Developer Hub maps LDAP user fields to the software catalog, enter optional maps and set fields.

      catalog:
        providers:
          ldapOrg:
            default:
              target: ldaps://ds.example.net
              bind:
                dn: cn=admin,ou=Users,dc=rhdh
                secret: ${LDAP_SECRET}
              users:
                - dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
                  options:
                    filter: (uid=*)
                  map:
                    rdn: uid
                    name: uid
                    description: {}
                    displayName: cn
                    email: mail
                    picture: {}
                    memberOf: memberOf
                  set:
                    metadata.customField: 'hello'
              groups:
                - dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
              schedule:
                frequency: PT1H
                timeout: PT15M

      rdn

      To change the default value: uid, enter the relative distinguished name of each entry.

      name

      To change the default value: uid, enter the LDAP field to map to the RHDH metadata.name field.

      description

      To set a value, enter the LDAP field to map to the RHDH metadata.description field.

      displayName

      To change the default value: cn, enter the LDAP field to map to the RHDH metadata.displayName field.

      email

      To change the default value: mail, enter the LDAP field to map to the RHDH spec.profile.email field.

      picture

      To set a value, enter the LDAP field to map to the RHDH spec.profile.picture field.

      memberOf

      To change the default value: memberOf, enter the LDAP field to map to the RHDH spec.memberOf field.

      set

      To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as metadata.customField: 'hello'.

   4. Optional: To change how Developer Hub maps LDAP group fields to the software catalog, enter optional groups.maps fields.

      catalog:
        providers:
          ldapOrg:
            default:
              target: ldaps://ds.example.net
              bind:
                dn: cn=admin,ou=Users,dc=rhdh
                secret: ${LDAP_SECRET}
              users:
                - dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
                  options:
                    filter: (uid=*)
              groups:
                - dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
                  map:
                    rdn: uid
                    name: uid
                    description: {}
                    displayName: cn
                    email: mail
                    picture: {}
                    memberOf: memberOf
                    members: member
                    type: groupType
                  set:
                    metadata.customField: 'hello'
              schedule:
                frequency: PT1H
                timeout: PT15M

      rdn

      To change the default value: cn, enter the relative distinguished name of each entry.

      name

      To change the default value: cn, enter the LDAP field to map to the RHDH metadata.name field.

      description

      To set a value, enter the LDAP field to map to the RHDH metadata.description field.

      displayName

      To change the default value: cn, enter the LDAP field to map to the RHDH metadata.displayName field.

      email

      To change the default value: mail, enter the LDAP field to map to the RHDH spec.profile.email field.

      picture

      To set a value, enter the LDAP field to map to the RHDH spec.profile.picture field.

      memberOf

      To change the default value: memberOf, enter the LDAP field to map to the RHDH spec.memberOf field.

      members

      To change the default value: member, enter the LDAP field to map to the RHDH spec.children field.

      type

      To change the default value: groupType, enter the LDAP field to map to the RHDH spec.type field.

      set

      To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as metadata.customField: 'hello'.

   5. Recommended: To use a secure LDAP connection (ldaps://), enter optional tls fields.

      catalog:
        providers:
          ldapOrg:
            default:
              target: ldaps://ds.example.net
              bind:
                dn: cn=admin,ou=Users,dc=rhdh
                secret: ${LDAP_SECRET}
              users:
      ldapOrg:
        default:
          tls:
            rejectUnauthorized: true
            keys: '/path/to/keys.pem'
            certs: '/path/to/certs.pem'

      rejectUnauthorized

      Set to false to allow self-signed certificates

      Warning

      This option is not recommended for production.

      keys

      Enter a file containing private keys in PEM format

      certs

      Enter a file containing cert chains in PEM format

   6. Optional: Enter configuration for vendor-specific attributes to set custom attribute names for distinguished names (DN) and universally unique identifiers (UUID) in LDAP directories. Default values are defined per supported vendor and automatically detected.

      catalog:
        providers:
          ldapOrg:
            default:
              vendor:
                dnAttributeName: customDN
                uuidAttributeName: customUUID

      dnAttributeName

      Enter the attribute name that holds the distinguished name (DN) for an entry.

      uuidAttributeName

      Enter the attribute name that holds a universal unique identifier (UUID) for an entry.

   7. Optional: Enter low level users and groups configuration in the options subsection.

      catalog:
        providers:
          ldapOrg:
            default:
              target: ldaps://ds.example.net
              bind:
                dn: cn=admin,ou=Users,dc=rhdh
                secret: ${LDAP_SECRET}
              users:
                options:
                  scope: sub
                  filter: (uid=*)
                  attributes:
                    - cn
                    - uid
                    - description
                  paged:
                  pageSize: 500
              groups:
                options:
                  scope: sub
                  filter: (cn=*)
                  attributes:
                    - cn
                    - uid
                    - description
                  paged:
                    pageSize: 500
                    pagePause: true

      scope

      To change the default value: one, enter how deep the search should go within the directory tree:

3. base to search only the base DN.
4. one to search one level below the base DN.

5. sub to search all descendant entries.

   filter

   To change the default value: (objectclass=*), enter your LDAP filter. With the default mapping:

6. For users, enter (uid=*) to make sure only users with valid uid field is synced, since users without uid will cause error and ingestion fails.

7. For groups, enter (cn=*)

   Tip

   When you change the mapping, also update the filter.

   attributes

   To change the default value: all attributes ['*', '+'], enter the array of attribute names to import from LDAP.

   paged

   Enter a value to enable paged results.

   pageSize

   Enter a value to set the results page size, such as 500.

   pagePause

   Enter true to tell the client to wait for the asynchronous results of the next page, when the page limit has been reached.

8. Recommended: To use a secure LDAP connection (ldaps://), mount your LDAP certificates and keys files in your Developer Hub deployment, by editing your Backstage custom resource.

   kind: Backstage
   spec:
     application:
       extraFiles:
         mountPath: /opt/ldap-secrets
         secrets:
           - name: my-rhdh-database-database-secrets
             key: ldap-certs.pem, ldap-keys.pem

Procedure

1. Create a new backend module:

   $ yarn new
   ? What type of module would you like to create? backend-plugin-module
   ? Enter the ID if the plugin [required]? catalog
   ? Enter the ID of the module [required]? ldap-transformer

   The command creates a plugin named catalog-backend-module-ldap-transformer.

2. Install required packages:

   $ yarn --cwd plugins/catalog-backend-module-ldap-transformer add @backstage/plugin-catalog-backend-module-ldap

3. Refer to the sample plugin and implement plugins/catalog-backend-module-ldap-transformer/src/module.ts.

4. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.

   $ npx @red-hat-developer-hub/cli@latest plugin export \
     --embed-package @backstage/plugin-catalog-backend-module-ldap

   Important

   Verify that the installed plugin version is compatible with the Backstage version.

   See the Dynamic plugins reference for the version to import.

5. Publish and enable the plugin in Developer Hub. For more information, see Installing and viewing plugins in Red Hat Developer Hub.

Verification

1. Every time that Developer Hub starts, it imports the users and groups. Check the console logs to verify the synchronization result.
2. After the first import is complete, go to the Catalog page and select User to view the list of users.
3. When you select a user, you see the information imported from LDAP. Verify that the user entities reflect the custom transformations you defined in the plugin.
4. You can select a group, view the list, and access or review the information imported from LDAP. Verify that the group entities reflect the custom transformations you defined in the plugin.
5. You can log in with an LDAP account.

Procedure

1. Enable the GitHub catalog provider plugin in your dynamic-plugins.yaml file.

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic'
       disabled: false

2. Add a GitHub catalog provider and integration section to your app-config.yaml file:

   catalog:
     providers:
       githubOrg:
         id: githuborg
         githubUrl: "${GITHUB_URL}"
         orgs: [ "${GITHUB_ORG}" ]
         schedule:
           frequency:
             minutes: 30
           initialDelay:
             seconds: 15
           timeout:
             minutes: 15
   integrations:
     github:
       - host: "${GITHUB_URL}"
         apps:
           - appId: ${GITHUB_APP_APP_ID}
             clientId: ${GITHUB_APP_CLIENT_ID_INTEGRATION}
             clientSecret: ${GITHUB_APP_CLIENT_SECRET_INTEGRATION}
             privateKey: |
               ${GITHUB_APP_PRIVATE_KEY}

   id

   Enter a stable identifier for this provider, such as githuborg.

   Warning

   Entities from this provider are associated with this identifier. Therefore, do not to change the identifier over time since that might lead to orphaned entities or conflicts.

   githubUrl

   Enter the configured secret variable name: ${GITHUB_URL}.

   orgs

   Enter the configured secret variable name: ${GITHUB_ORG}.

   schedule.frequency

   Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.

   schedule.timeout

   Enter your schedule timeout, in the ISO duration or "human duration" format.

   schedule.initialDelay

   Enter your schedule initial delay, in the ISO duration or "human duration" format.

   integrations.github.host

   Enter the configured secret variable name: ${GITHUB_URL}.

   integrations.github.apps.appId

   Enter the configured secret variable name: ${GITHUB_APP_APP_ID}.

   integrations.github.apps.clientId

   Enter the configured secret variable name: ${GITHUB_APP_CLIENT_ID_INTEGRATION}.

   integrations.github.apps.clientSecret

   Enter the configured secret variable name: ${GITHUB_APP_CLIENT_SECRET_INTEGRATION}.

   integrations.github.apps.privateKey

   Enter the configured secret variable name: ${GITHUB_APP_PRIVATE_KEY}.

Procedure

1. Create a new backend module:

   $ yarn new
   ? What type of module would you like to create? backend-plugin-module
   ? Enter the ID if the plugin [required]? catalog
   ? Enter the ID of the module [required]? github-org-transformer

   The command creates a plugin named catalog-backend-module-github-org-transformer.

2. Install required packages:

   $ yarn --cwd plugins/catalog-backend-module-github-org-transformer add @backstage/plugin-catalog-backend-module-github-org

3. (Optional) Install recommended packages to extend the default transformers or Transformer type checking:

   $ yarn --cwd plugins/catalog-backend-module-github-org-transformer add @backstage/plugin-catalog-backend-module-github

4. (Optional) Install recommended packages for UserEntity or GroupEntity type checking:

   $ yarn --cwd plugins/catalog-backend-module-github-org-transformer add @backstage/catalog-model

5. Refer to the sample plugin and implement your custom plugins/catalog-backend-module-github-org-transformer/src/module.ts and make your required transformations to user and group entities.

6. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.

   $ npx @red-hat-developer-hub/cli@latest plugin export \
     --embed-package @backstage/plugin-catalog-backend-module-github \
     --embed-package @backstage/plugin-catalog-backend-module-github-org

   Important

   Verify that the installed plugin version is compatible with the Backstage version.

   See the Dynamic plugins reference for the version to import.

7. Publish and enable the plugin in Developer Hub. For more information, see Installing and viewing plugins in Red Hat Developer Hub.

Verification

1. Every time that Developer Hub starts, it imports the users and groups. Check the console logs to verify the synchronization result.
2. After the first import is complete, go to the Catalog page and select User to view the list of users.
3. When you select a user, you see the information imported from GitHub. Verify that the user entities reflect the custom transformations you defined in the plugin.
4. You can select a group, view the list, and access or review the information imported from GitHub. Verify that the group entities reflect the custom transformations you defined in the plugin.
5. You can log in with a GitHub account.

Procedure

1. Enable the Microsoft Graph catalog provider plugin in your dynamic-plugins.yaml file.

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
       disabled: false

2. Add a Microsoft Graph catalog provider section to your app-config.yaml file:

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           target: https://graph.microsoft.com/v1.0
           tenantId: ${MICROSOFT_TENANT_ID}
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           schedule:
             frequency:
               hours: 1
             timeout:
               minutes: 50
             initialDelay:
               minutes: 50

   target

   Enter https://graph.microsoft.com/v1.0 to define the MSGraph API endpoint the provider is connecting to. You might change this parameter to use a different version, such as the beta endpoint.

   tenantId

   Enter the configured secret variable name: ${MICROSOFT_TENANT_ID}.

   clientId

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_SECRET}.

   schedule

   frequency

   Enter the schedule frequency in the cron, ISO duration, or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.

   timeout

   Enter the schedule timeout in the ISO duration or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.

   initialDelay

   Enter the schedule initial delay in the ISO duration or human duration format.

3. Optional: Add optional fields to the Microsoft authentication provider section in your app-config.yaml file:

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           authority: https://login.microsoftonline.com/
           queryMode: advanced
           user:
             expand: manager
             filter: accountEnabled eq true and userType eq 'member'
             loadPhotos: true
             select: ['id', 'displayName', 'description']
           userGroupMember:
             filter: "displayName eq 'Backstage Users'"
             search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
           group:
             expand: member
             filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
             search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
             select: ['id', 'displayName', 'description']

   authority

   Enter your Azure authority URL if it is different from the default: https://login.microsoftonline.com.

   queryMode

   Enter advanced when the default basic query mode is insufficient for your queries to the Microsoft Graph API. See Microsoft Azure advanced queries.

   user

   Add this section to configure optional user query parameters.

   expand

   Enter your expansion parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. A single request can expand only one relationship. See Microsoft Graph query expand parameter.

   You can combine this parameter with userGroupMember.filter or user.filter.

   filter

   Enter your user filter. See Microsoft Graph API and Microsoft Graph API query filter parameters syntax.

   This parameter and userGroupMember.filter are mutually exclusive, specify only one.

   loadPhotos

   Developer Hub loads photos by default. Enter false to avoid loading user photos.

   select

   Enter the Microsoft Graph resource type list to retrieve.

   userGroupMember

   Add this section to use group membership to get users.

   filter

   Enter your filter to filter groups and fetch their members.

   This parameter and user.filter are mutually exclusive, specify only one.

   search

   Enter your search query to search for groups and fetch their members.

   This parameter and user.filter are mutually exclusive, specify only one.

   group

   Enter your configuration to get groups.

   expand

   Enter your expansion parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. A single request can expand only one relationship. See Customize Microsoft Graph responses with query parameters.

   You can combine this parameter with user.filter or userGroupMember.filter.

   filter

   Enter your group filter parameter. See Microsoft Graph API query group syntax.

   search

   Enter your group search parameter. See Microsoft Graph API query search parameter.

   select

   Enter the Microsoft Graph resource type list to retrieve.

Procedure

1. Create a new backend module:

   $ yarn new
   ? What type of module would you like to create? backend-plugin-module
   ? Enter the ID if the plugin [required]? catalog
   ? Enter the ID of the module [required]? msgraph-transformer

   The command creates a plugin named catalog-backend-module-msgraph-transformer.

2. Install required packages:

   $ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/plugin-catalog-backend-module-msgraph

3. (Optional) Install recommended packages for UserEntity or GroupEntity type checking:

   $ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/catalog-model

4. Refer to the sample plugin and implement plugins/catalog-backend-module-msgraph-transformer/src/module.ts.

5. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.

   $ npx @red-hat-developer-hub/cli@latest plugin export \
     --embed-package @backstage/plugin-catalog-backend-module-msgraph

   Important

   Verify that the installed plugin version is compatible with the Backstage version.

   See the Dynamic plugins reference for the version to import.

6. Publish and enable the plugin in Developer Hub. For more information, see Installing and viewing plugins in Red Hat Developer Hub.

Verification

1. Every time that Developer Hub starts, it imports the users and groups. Check the console logs to verify the synchronization result.
2. After the first import is complete, go to the Catalog page and select User to view the list of users.
3. When you select a user, you see the information imported from Microsoft Entra ID. Verify that the user entities reflect the custom transformations you defined in the plugin.
4. You can select a group, view the list, and access or review the information imported from Microsoft Azure. Verify that the group entities reflect the custom transformations you defined in the plugin.
5. You can log in with an Entra ID account.

Procedure

1. Create a new backend module:

   $ yarn new
   ? What type of module would you like to create? backend-plugin-module
   ? Enter the ID if the plugin [required]? catalog
   ? Enter the ID of the module [required]? gitlab-org-transformer

   The command creates a plugin named catalog-backend-module-gitlab-org-transformer.

2. Install required packages:

   $ yarn --cwd plugins/catalog-backend-module-gitlab-org-transformer add @backstage/plugin-catalog-backend-module-gitlab-org

3. (Optional) Install recommended packages to extend the default transformers or Transformer type checking:

   $ yarn --cwd plugins/catalog-backend-module-gitlab-org-transformer add @backstage/plugin-catalog-backend-module-gitlab

4. (Optional) Install recommended packages for UserEntity or GroupEntity type checking:

   $ yarn --cwd plugins/catalog-backend-module-gitlab-org-transformer add @backstage/catalog-model

5. Refer to the sample plugin and implement plugins/catalog-backend-module-gitlab-org-transformer/src/module.ts.

6. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.

   $ npx @red-hat-developer-hub/cli@latest plugin export \
     --embed-package @backstage/plugin-catalog-backend-module-gitlab \
     --embed-package @backstage/plugin-catalog-backend-module-gitlab-org \
     --ignore-version-check @backstage/backend-defaults

   Important

   Verify that the installed plugin version is compatible with the Backstage version.

   See the Dynamic plugins reference for the version to import.

7. Publish and enable the plugin in Developer Hub. For more information, see Installing and viewing plugins in Red Hat Developer Hub.

Verification

1. Every time that Developer Hub starts, it imports the users and groups. Check the console logs to verify the synchronization result.
2. After the first import is complete, go to the Catalog page and select User to view the list of users.
3. When you select a user, you see the information imported from GitLab. Verify that the user entities reflect the custom transformations you defined in the plugin.
4. You can select a group, view the list, and access or review the information imported from GitLab. Verify that the group entities reflect the custom transformations you defined in the plugin.
5. You can log in with a GitLab account.