Search

Chapter 2. Deploying Red Hat Developer Hub on OpenShift Container Platform

download PDF

You can install Red Hat Developer Hub on OpenShift Container Platform using one of the following methods:

  • The Helm chart
  • The Red Hat Developer Hub Operator

2.1. Deploying Red Hat Developer Hub on OpenShift Container Platform using Helm Chart

You can use a Helm chart in Red Hat OpenShift Container Platform to install Developer Hub, which is a flexible installation method.

Helm is a package manager on OpenShift Container Platform that provides the following features:

  • Applies regular application updates using custom hooks
  • Manages the installation of complex applications
  • Provides charts that you can host on public and private servers
  • Supports rolling back to previous application versions

The Red Hat Developer Hub Helm chart is available in the Helm catalog on OpenShift Dedicated and OpenShift Container Platform.

Prerequisites

  • You are logged in to your OpenShift Container Platform account.
  • A user with the OpenShift Container Platform admin role has configured the appropriate roles and permissions within your project to create an application. For more information about OpenShift Container Platform roles, see Using RBAC to define and apply permissions.
  • You have created a project in OpenShift Container Platform. For more information about creating a project in OpenShift Container Platform, see Red Hat OpenShift Container Platform documentation.

Procedure

  1. From the Developer perspective on the Developer Hub web console, click +Add.
  2. From the Developer Catalog panel, click Helm Chart.
  3. In the Filter by keyword box, enter Developer Hub and click the Red Hat Developer Hub card.
  4. From the Red Hat Developer Hub page, click Create.
  5. From your cluster, copy the OpenShift Container Platform router host (for example: apps.<clusterName>.com).
  6. Select the radio button to configure the Developer Hub instance with either the form view or YAML view. The Form view is selected by default.

    • Using Form view

      1. To configure the instance with the Form view, go to Root Schema global Enable service authentication within Backstage instance and paste your OpenShift Container Platform router host into the field on the form.
    • Using YAML view

      1. To configure the instance with the YAML view, paste your OpenShift Container Platform router hostname in the global.clusterRouterBase parameter value as shown in the following example:

        global:
          auth:
            backend:
              enabled: true
          clusterRouterBase: apps.<clusterName>.com
          # other Red Hat Developer Hub Helm Chart configurations
  7. Edit the other values if needed.

    Note

    The information about the host is copied and can be accessed by the Developer Hub backend.

    When an OpenShift Container Platform route is generated automatically, the host value for the route is inferred and the same host information is sent to the Developer Hub. Also, if the Developer Hub is present on a custom domain by setting the host manually using values, the custom host takes precedence.

  8. Click Create and wait for the database and Developer Hub to start.
  9. Click the Open URL icon to start using the Developer Hub platform.

    rhdh helm install
Note

Your developer-hub pod might be in a CrashLoopBackOff state if the Developer Hub container cannot access the configuration files. This error is indicated by the following log:

Loaded config from app-config-from-configmap.yaml, env
...
2023-07-24T19:44:46.223Z auth info Configuring "database" as KeyStore provider type=plugin
Backend failed to start up Error: Missing required config value at 'backend.database.client'

To resolve the error, verify the configuration files.

2.1.1. Installing Red Hat Developer Hub using the Helm Chart in an air-gapped environment

An air-gapped environment, also known as an air-gapped network or isolated network, ensures security by physically segregating the system or network. This isolation is established to prevent unauthorized access, data transfer, or communication between the air-gapped system and external sources.

You can install Red Hat Developer Hub in an air-gapped environment to ensure security and meet specific regulatory requirements.

To install Developer Hub in an air-gapped environment, you must have access to the registry.redhat.io and the registry for the air-gapped environment.

Prerequisites

  • You have installed an Red Hat OpenShift Container Platform 4.12 or later.
  • You have access to the registry.redhat.io.
  • You have access to the Red Hat OpenShift Container Platform image registry of your cluster. For more information about exposing the image registry, see the Red Hat OpenShift Container Platform documentation about Exposing the registry.
  • You have installed the oc command line tool on your workstation.
  • You have installed the podman command line tools on your workstation.
  • You you have an account in Red Hat Developer portal.

Procedure

  1. Log in to your OpenShift Container Platform account using the oc command line tool, by running the following command:

    oc login -u <user> -p <password> https://api.<hostname>:6443
  2. Log in to the OpenShift Container Platform image registry using the podman command line tool, by running the following command:

    podman login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.<hostname>
    Note

    You can run the following commands to get the full host name of the OpenShift Container Platform image registry, and then use the host name in a command to log in:

    REGISTRY_HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')
    podman login -u kubeadmin -p $(oc whoami -t) $REGISTRY_HOST
  3. Log in to the registry.redhat.io in podman by running the following command:

    podman login registry.redhat.io

    For more information about registry authentication, see Red Hat Container Registry Authentication.

  4. Pull Developer Hub and PostgreSQL images from Red Hat Image registry to your workstation, by running the following commands:

    podman pull registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-chart-version}
    podman pull registry.redhat.io/rhel9/postgresql-15:latest
  5. Push both images to the internal OpenShift Container Platform image registry by running the following commands:

    podman push --remove-signatures registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-chart-version} default-route-openshift-image-registry.<hostname>/<project_name>/rhdh-hub-rhel9:{product-chart-version}
    podman push --remove-signatures registry.redhat.io/rhel9/postgresql-15:latest default-route-openshift-image-registry.<hostname>/<project_name>/postgresql-15:latest

    For more information about pushing images directly to the OpenShift Container Platform image registry, see How do I push an Image directly into the OpenShift 4 registry.

    Important
  6. Use the following command to verify that both images are present in the internal OpenShift Container Platform registry:

    oc get imagestream -n <project_name>
  7. Enable local image lookup for both images by running the following commands:

    oc set image-lookup postgresql-15
    oc set image-lookup  rhdh-hub-rhel9
  8. Go to YAML view and update the image section for backstage and postgresql using the following values:

    Example values for Developer Hub image

    upstream:
      backstage:
        image:
          registry: ""
          repository: rhdh-hub-rhel9
          tag: latest

    Example values for PostgreSQL image

    upstream:
      postgresql:
        image:
          registry: ""
          repository: postgresql-15
          tag: latest

  9. Install the Red Hat Developer Hub using Helm chart. For more information about installing Developer Hub, see Section 2.1, “Deploying Red Hat Developer Hub on OpenShift Container Platform using Helm Chart”.

2.2. Deploying Red Hat Developer Hub on OpenShift Container Platform using the Operator

As a developer, you can deploy a Red Hat Developer Hub instance on OpenShift Container Platform by using the Developer Catalog in the Red Hat OpenShift Container Platform web console. This deployment method uses the Red Hat Developer Hub Operator.

Prerequisites

Procedure

  1. Create a project in OpenShift Container Platform for your Red Hat Developer Hub instance, or select an existing project.

    Tip

    For more information about creating a project in OpenShift Container Platform, see Creating a project by using the web console in the Red Hat OpenShift Container Platform documentation.

  2. From the Developer perspective on the OpenShift Container Platform web console, click +Add.
  3. From the Developer Catalog panel, click Operator Backed.
  4. In the Filter by keyword box, enter Developer Hub and click the Red Hat Developer Hub card.
  5. Click Create.
  6. Add custom configurations for the Red Hat Developer Hub instance.
  7. On the Create Backstage page, click Create

Verification

After the pods are ready, you can access the Red Hat Developer Hub platform by opening the URL.

  1. Confirm that the pods are ready by clicking the pod in the Topology view and confirming the Status in the Details panel. The pod status is Active when the pod is ready.
  2. From the Topology view, click the Open URL icon on the Developer Hub pod.

    operator install 1

2.2.1. Configuring the Developer Hub Custom Resource

Updates to the Backstage custom resource (CR) are automatically handled by the Red Hat Developer Hub Operator. However, updates to resources referenced by the CR, such as ConfigMaps or Secrets, are not updated automatically unless the CR itself is updated. If you want to update resources referenced by the CR, then you must manually delete the Backstage Deployment so that the Operator can re-create it with the updated resources.

2.2.1.1. Adding a custom application configuration file to OpenShift Container Platform

To change the configuration of your Red Hat Developer Hub instance, you must do the following:

  • Add a custom application configuration file to OpenShift Container Platform and reference it in the Custom Resource (CR). In OpenShift Container Platform, you can use the following example as a base template to create a ConfigMap such as app-config-rhdh.yaml:

    kind: ConfigMap
    apiVersion: v1
    metadata:
      name: app-config-rhdh
    data:
      "app-config-rhdh.yaml": |
        app:
          title: Red Hat Developer Hub
          baseUrl: https://backstage-developer-hub-my-ns.apps.ci-ln-vtkzr22-72292.origin-ci-int-gce.dev.rhcloud.com
        backend:
          auth:
            keys:
              - secret: "${BACKEND_SECRET}"
          baseUrl: https://backstage-backstage-sample-my-ns.apps.ci-ln-vtkzr22-72292.origin-ci-int-gce.dev.rhcloud.com
          cors:
            origin: https://backstage-backstage-sample-my-ns.apps.ci-ln-vtkzr22-72292.origin-ci-int-gce.dev.rhcloud.com
  • Use the mandatory backend auth key for Red Hat Developer Hub to reference an environment variable defined in an OpenShift Container Platform Secret.
  • Set the external URL of your Red Hat Developer Hub instance in the app.baseUrl, backend.baseUrl and backend.cors.origin fields of the application configuration. By default, the URL is similar to the following example: https://backstage-<CUSTOM_RESOURCE_NAME>-<NAMESPACE_NAME>.<OPENSHIFT_INGRESS_DOMAIN>;.

    • You can use the oc get ingresses.config/cluster -o jsonpath='{.spec.domain}' command to display your ingress domain. If you want to use a different host or sub-domain, customize the Custom Resource spec.application.route field and adjust the application configuration accordingly.
Note

You are responsible for protecting your Red Hat Developer Hub installation from external and unauthorized access. Manage the backend auth key like any other secret. Meet strong password requirements, do not expose it in any configuration files, and only inject it into configuration files as an environment variable.

Prerequisites

  • You have an active Red Hat OpenShift Container Platform account.

Procedure

  1. From the Developer perspective, select the ConfigMaps tab.
  2. Click Create ConfigMap.
  3. Select the YAML view option in Configure via and make the changes to the file, if necessary.
  4. Click Create.
  5. Select the Secrets tab.
  6. Click Create Key/value Secret.
  7. Name the secret secrets-rhdh.
  8. Add a key named BACKEND_SECRET and a base64 encoded string as a value. Use a unique value for each Red Hat Developer Hub instance. For example, you can use the following command to generate a key from your terminal:

    node -p 'require("crypto").randomBytes(24).toString("base64")'
  9. Click Create.
  10. Select the Topology view.
  11. 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.

    operator install 2
  12. Add the spec.application.appConfig.configMaps and spec.application.extraEnvs.secrets fields to the custom resource. For example:

    spec:
      application:
        appConfig:
          mountPath: /opt/app-root/src
          configMaps:
             - name: app-config-rhdh
        extraEnvs:
          secrets:
             - name: secrets-rhdh
        extraFiles:
          mountPath: /opt/app-root/src
        replicas: 1
        route:
          enabled: true
      database:
        enableLocalDb: true
  13. Click Save.
  14. Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
  15. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Additional resources

2.2.2. Configuring dynamic plugins with the Red Hat Developer Hub Operator

You can store the configuration for dynamic plugins in a ConfigMap object that your Backstage custom resource (CR) can reference.

Note

If the pluginConfig field references environment variables, you must define the variables in your secrets-rhdh secret.

Procedure

  1. From the OpenShift Container Platform web console, select the ConfigMaps tab.
  2. Click Create ConfigMap.
  3. From the Create ConfigMap page, select the YAML view option in Configure via and edit the file, if needed.

    Example ConfigMap object using the GitHub dynamic plugin

    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-catalog-backend-module-github-dynamic'
            disabled: false
            pluginConfig: {}

  4. Click Create.
  5. Go to the Topology tab.
  6. Click on 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.

    operator install 2
  7. Add the dynamicPluginsConfigMapName field to your Backstage CR. For example:

    apiVersion: rhdh.redhat.com/v1alpha1
    kind: Backstage
    metadata:
      name: my-rhdh
    spec:
      application:
    # ...
        dynamicPluginsConfigMapName: dynamic-plugins-rhdh
    # ...
  8. Click Save.
  9. Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
  10. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Verification

  • Ensure that the dynamic plugins configuration has been loaded, by appending /api/dynamic-plugins-info/loaded-plugins to your Red Hat Developer Hub root URL and checking the list of plugins:

    Example list of plugins

    [
      {
        "name": "backstage-plugin-catalog-backend-module-github-dynamic",
        "version": "0.5.2",
        "platform": "node",
        "role": "backend-plugin-module"
      },
      {
        "name": "backstage-plugin-techdocs",
        "version": "1.10.0",
        "role": "frontend-plugin",
        "platform": "web"
      },
      {
        "name": "backstage-plugin-techdocs-backend-dynamic",
        "version": "1.9.5",
        "platform": "node",
        "role": "backend-plugin"
      },
    ]

2.2.3. Installing Red Hat Developer Hub using the Operator in an air-gapped environment

On an OpenShift Container Platform cluster operating on a restricted network, public resources are not available. However, deploying the Red Hat Developer Hub Operator and running Developer Hub requires the following public resources:

  • Operator images (bundle, operator, catalog)
  • Operands images (RHDH, PostgreSQL)

To make these resources available, replace them with their equivalent resources in a mirror registry accessible to the OpenShift Container Platform cluster.

You can use a helper script that mirrors the necessary images and provides the necessary configuration to ensure those images will be used when installing the Red Hat Developer Hub Operator and creating Developer Hub instances.

Note

This script requires a target mirror registry which you should already have installed if your OpenShift Container Platform cluster is ready to operate on a restricted network. However, if you are preparing your cluster for disconnected usage, you can use the script to deploy a mirror registry in the cluster and use it for the mirroring process.

Prerequisites

Note

The internal OpenShift Container Platform cluster image registry cannot be used as a target mirror registry. See About the mirror registry.

  • If you prefer to create your own mirror registry, see Creating a mirror registry with mirror registry for Red Hat OpenShift.
  • If you do not already have a mirror registry, you can use the helper script to create one for you and you need the following additional prerequisites:

    • The cURL package is installed. For Red Hat Enterprise Linux, the curl command is available by installing the curl package. To use curl for other platforms, see the cURL website.
    • The htpasswd command is available. For Red Hat Enterprise Linux, the htpasswd command is available by installing the httpd-tools package.

Procedure

  1. Download and run the mirroring script to install a custom Operator catalog and mirror the related images: prepare-restricted-environment.sh (source).

    curl -sSLO https://raw.githubusercontent.com/janus-idp/operator/1.1.x/.rhdh/scripts/prepare-restricted-environment.sh
    
    # if you do not already have a target mirror registry
    # and want the script to create one for you
    # use the following example:
    bash prepare-restricted-environment.sh \
       --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v4.14" \
       --prod_operator_package_name "rhdh" \
       --prod_operator_bundle_name "rhdh-operator" \
       --prod_operator_version "v1.1.1"
    
    # if you already have a target mirror registry
    # use the following example:
    bash prepare-restricted-environment.sh \
       --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v4.14" \
       --prod_operator_package_name "rhdh" \
       --prod_operator_bundle_name "rhdh-operator" \
       --prod_operator_version "v1.1.1" \
       --use_existing_mirror_registry "my_registry"
    Note

    The script can take several minutes to complete as it copies multiple images to the mirror registry.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.