[!TIP] Ongoing and occasional updates and improvements.

RHDH (redhat developer hub) integration with ADO (azure devops)

In this document, we will show you how to integrate rhdh with ado (azure devops), and use azure sso to login to rhdh. As the time of writing, the rhdh version is 1.3.1, we will use helm to install rhdh in ocp4.16.

The architecture is like this:

[!NOTE] Azure make changes from time to time, so the steps may not be exactly the same as the time of writing, but the general idea is the same.

pre-requisites

This document assumes you have the following pre-requisites:

working connected ocp4.16 cluster
azure account

azure sso setup

There is official document for azure sso setup, you can refer to this link.

We need to create 2 app registration in azure portal, one for sso login and one for azure devops integration.

Both app registration is created with default settings.

For the sso login demo-backstage app registration, we set the redirect url to https://redhat-developer-hub-demo-rhdh.apps.demo-01-rhsys.wzhlab.top/api/auth/microsoft/handler/frame.

And set the sso login demo-backstage app registration permission, based on the offical documents.

email
offline_access
openid
profile
User.Read

The app registration for azure devops integration is rhdh-azure-devops, and we keep it as the default settings.

[!NOTE] Write down the tenant id, client id and client secret for both app registration, we will use it in the next step.

And for demo purpose, we create several group and users

L1Support(group)
- l1.u01(user)
- l1.u02(user)
L2Support(group)
- l2.u01(user)
- l2.u02(user)
L3Support(group)
- l3.u01(user)
- l3.u02(user)

azure devops setup

Sometimes, you need to login to https://dev.azure.com/ to switch to correct directory.

You can also access azure devops profile setting page, to have a overview of your organization and projects.

Now, it is time to create a project under your organization.

And in organization settings, you can find the users settings, add the app registration rhdh-azure-devops as a user, and give it project administator permission.

Install Code Search Feature for Azure devops

Now, we finished the azure devops setup, and we can move to the next step.

rhdh setup

We needs some pre-installed plugins related with azure sso and ado, for detailed information, following the offical docs.

For configuration around azure ado, here is upstream docs.

For configuration around azure sso, here is upstream docs.

As the time of writing, we install rhdh with version 1.3.1, and install using helm. You can patch the helm config like this:

global:
  # patch the base url
  clusterRouterBase: apps.demo-01-rhsys.wzhlab.top
  # patch for plugins
  dynamic:
    plugins:
      # for azure and ado (azure devops)
      # Azure Devops UI
      # redhat version is too old (0.1.14 by the time of writing), has some compatibility issue with azure devops
      # so we switch to upstream version
      - package: ./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic
        disabled: true
      # https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend-module-azure?activeTab=versions
      - package: '@backstage/plugin-scaffolder-backend-module-azure@0.2.3'
        disabled: false
        integrity: sha512-ZXYsvjPHImrc+qnS4uJjLJ23TUjduVzbQeN9BIIyr+EHMHOWujwFc81Y5F9Gb5dA7ui1o4N5S92ukHQ/9+vCkA==

      # Azure Devops
      - package: ./dynamic-plugins/dist/backstage-plugin-azure-devops
        disabled: false

      # Azure Devops
      - package: ./dynamic-plugins/dist/backstage-plugin-azure-devops-backend-dynamic
        disabled: false

      # MS Graph
      # this is used to import users from azure ad.
      - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic
        disabled: false

upstream:
  backstage:
    # patch for app config
    extraAppConfig:
      - configMapRef: app-config-rhdh
        filename: app-config-rhdh.yaml
    # patch for secrets
    extraEnvVarsSecrets:
      - wzh-rhdh-credentials

After you patch the helm config, the rhdh will deploy a new version, but it will not process, because the new config depends on a configmap, which is not existed right now. We will craete it in the next step.

Set the wzh-rhdh-credentials secret with the bash


NAMESPACES="demo-rhdh"

# create secret based on env variable
# the log level is set to debug, so we can debug the rhdh easily, we can remove it in production.
# the tls_reject
oc delete secret wzh-rhdh-credentials -n $NAMESPACES
oc create secret generic wzh-rhdh-credentials -n $NAMESPACES \
--from-literal=AZURE_TENANT_ID=$AZURE_TENANT_ID \
--from-literal=AZURE_CLIENT_ID=$AZURE_CLIENT_ID \
--from-literal=AZURE_CLIENT_SECRET=$AZURE_CLIENT_SECRET \
--from-literal=AZURE_DEVOPS_TENANT_ID=$AZURE_DEVOPS_TENANT_ID \
--from-literal=AZURE_DEVOPS_CLIENT_ID=$AZURE_DEVOPS_CLIENT_ID \
--from-literal=AZURE_DEVOPS_CLIENT_SECRET=$AZURE_DEVOPS_CLIENT_SECRET \
--from-literal=AZURE_DEVOPS_ORG=$AZURE_DEVOPS_ORG \
--from-literal=SESSION_SECRET=`openssl rand -hex 32` \
--from-literal=NODE_TLS_REJECT_UNAUTHORIZED=0 \
--from-literal=LOG_LEVEL=debug


# create app config
oc delete configmap app-config-rhdh -n $NAMESPACES

cat << EOF > ${BASE_DIR}/data/install/app-config-rhdh.yaml
---
kind: ConfigMap
apiVersion: v1
metadata:
  name: app-config-rhdh
data:
  app-config-rhdh.yaml: |
    app:
      title: WZH Developer Hub

    auth:
      # environment: production
      # using development, will give you guest login options :)
      environment: development
      session:
        secret: \${SESSION_SECRET}
      providers:
        microsoft:
          production:
            clientId: \${AZURE_CLIENT_ID}
            clientSecret: \${AZURE_CLIENT_SECRET}
            tenantId: \${AZURE_TENANT_ID}
          development:
            clientId: \${AZURE_CLIENT_ID}
            clientSecret: \${AZURE_CLIENT_SECRET}
            tenantId: \${AZURE_TENANT_ID}
        guest:
          dangerouslyAllowOutsideDevelopment: true
          userEntityRef: user:default/guest

    signInPage: microsoft

    # use in no-production, to allow all users to login
    # dangerouslyAllowSignInWithoutUserInCatalog: true

    integrations:
      azure:
        - host: dev.azure.com
          credentials:
            # - personalAccessToken: \${AZURE_DEVOPS_PERSONAL_ACCESS_TOKEN}
            #   organizations:
            #     - \$AZURE_DEVOPS_ORG
            - clientId: \${AZURE_DEVOPS_CLIENT_ID}
              clientSecret: \${AZURE_DEVOPS_CLIENT_SECRET}
              tenantId: \${AZURE_DEVOPS_TENANT_ID}
              # organizations:
              #   - \$AZURE_DEVOPS_ORG

    catalog:
      rules:
        - allow: [Component, System, API, Resource, Location, Template]

      locations:
        - target: https://github.com/wangzheng422/red-hat-developer-hub-software-templates/blob/wzh-hack/wzh-data/org.yaml
          type: url
          rules:
            - allow: [Group, User]
        - target: https://github.com/wangzheng422/red-hat-developer-hub-software-templates/blob/wzh-hack/templates/azure/dotnet-frontend/template.yaml
          type: url
          rules:
            - allow: [Template]

      providers:
        microsoftGraphOrg:
          providerId:
            target: https://graph.microsoft.com/v1.0
            tenantId: \${AZURE_TENANT_ID}
            clientId: \${AZURE_CLIENT_ID}
            clientSecret: \${AZURE_CLIENT_SECRET}
            # queryMode: advanced
            # user:
            #   loadPhotos: true
            userGroupMember:
              filter: >
                displayName eq 'L1Support' OR displayName eq 'L2Support' OR displayName eq 'L3Support'
            group:
              filter: >
                displayName eq 'L1Support' OR displayName eq 'L2Support' OR displayName eq 'L3Support'
            schedule:
              frequency: { hours: 1 }
              timeout: { minutes: 50 }
              # frequency: { minutes: 10 }
              # timeout: { minutes: 5 }

        azureDevOps:
          yourProviderId: # identifies your dataset / provider independent of config changes
            organization: \$AZURE_DEVOPS_ORG
            project: '*'
            repository: '*' # this will match all repos 
            path: /catalog-info.yaml
            schedule: # optional; same options as in TaskScheduleDefinition
              # supports cron, ISO duration, "human duration" as used in code
              frequency: { minutes: 30 }
              # supports ISO duration, "human duration" as used in code
              timeout: { minutes: 3 }

    permission:
      enabled: false

    enabled:
      azure: true
      azureDevOps: true
      microsoftGraphOrg: true
      microsoft: true
      permission: false
EOF

oc create -f ${BASE_DIR}/data/install/app-config-rhdh.yaml -n $NAMESPACES

# scale-in and scale-out to restart the rhdh, to apply the new config.
oc scale deployment redhat-developer-hub --replicas=0 -n $NAMESPACES

oc scale deployment redhat-developer-hub --replicas=1 -n $NAMESPACES


# if you want to see the logs and debug
POD_NAME=$(oc get pods --selector=app.kubernetes.io/instance=redhat-developer-hub --output=jsonpath='{.items[0].metadata.name}')

oc logs $POD_NAME | grep --color=always -i 'error' | awk '{print; print "";}'

rhdh demo run through

Input the parameter that defined in the template, in the first page, there is based information for azure devops, which is organization, project, and the name of the repository which will be created.

In the next page, fill in the component information, like title, owner which is a azure user, and system.

Review the settings, and click the create button. It will try to create the azure devops repository.

After the creation, you can see the repository is created successfully.

you can also see the repository is created in the azure devops.

source code highlight

Here is the example of the catalog-info.yaml file, which is created in the azure devops repository. The source code is here, but it is templatized, you can see the result after the creation here, to help you understand the structure.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: dummy-repo-01
  title: wzh-demo-component-01
  description: wzh-demo-component-01
  annotations:
    backstage.io/kubernetes-id: dummy-repo-01
    backstage.io/techdocs-ref: dir:.
    dev.azure.com/project-repo: demo/dummy-repo-01
    dev.azure.com/host-org: dev.azure.com/wangzheng422-devops
spec:
  type: website
  system: wzh-demo
  lifecycle: production
  owner: user:default/azure.demo.user.01_wzhlab.top

run the azure devops pipeline

After the repository is created, you can create a pipeline in the azure devops to build and deploy the application.

For free user, we need to change the project/repo into public to run the pipeline with self-host agent.

First we need to active the public project in our organization.

Next, we go to a project under the organization, and change the project’s visibility into public.

To run with self-host agent, we need to add agent into a agent pool, we use the build-in agent pool Default.

And click the new agent, and follow the steps to install the agent on your machine. Here we can see an agent is added into the pool.

The detailed steps to install the agent is popped up.

If you use rhel9 as the agent base os, you can use the following command to install the agent:


# you need to install docker ce as systemd service
# because our pipeline definition needs docker daemons.
dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker


# add user ado to run the agent
useradd -m ado

usermod -aG docker ado

su - ado

mkdir -p ~/azure
cd ~/azure

wget https://vstsagentpackage.azureedge.net/agent/4.248.0/vsts-agent-linux-x64-4.248.0.tar.gz

tar zvxf *

./config.sh
# ......
# Server URL : https://dev.azure.com/<your organization>
# PAT : <your personal access token>
# agent pool : <Default>
# ......

./run.sh

After created agent, we need to create quay.io’s credential in the azure devops, which is used by the pipeline to upload the container image. In azure devops, it is service connections. Open project setting, and under the pipeline, click service connections, and click new service connection,

and select docker registry.

In the next step, input the following information:

Docker Registry: quay.io
Docker ID: your quay.io username, a robot account is recommended, which is more secure.
Docker Password: your quay.io password
Service connection name: quay.io

Now, we are ready to run the pipeline, first, we need to create a pipeline in the azure devops, click pipelines in the left menu, and click new pipeline.

Select azure repos git, because our pipeline definition file is in the azure devops repository.

Next, select the repository that contains the pipeline definition file.

The pipeline definition file is azure-pipelines.yml, which is in the root of the repository, and is loaded automatically. Click run will run and save the pipeline.

You can check the source code of the azure-pipelines.yml file here, and change it based on your own env:

azure-pipelines.yml

Wait a moment, it will trigger a build on the self-host agent, and the build will be successful. The container image will be uploaded to quay.io. Here is the build result.

And we can see the container image is created on quay.io.

Deploy the container image quay.io/wangzheng422/qimgs:azure-devops-demo-latest on openshift, expose the service (the app port is default to 5000), and access the application.

The application is running on openshift, and we can access it via the route. It is a very simple dotnet application.