Chapter 2. Deploying Red Hat Developer Hub on OpenShift Container Platform
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
- From the Developer perspective on the Developer Hub web console, click +Add.
- From the Developer Catalog panel, click Helm Chart.
- In the Filter by keyword box, enter Developer Hub and click the Red Hat Developer Hub card.
- From the Red Hat Developer Hub page, click Create.
-
From your cluster, copy the OpenShift Container Platform router host (for example:
apps.<clusterName>.com
). 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
-
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.
-
To configure the instance with the Form view, go to Root Schema
Using YAML view
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
Edit the other values if needed.
NoteThe 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.
- Click Create and wait for the database and Developer Hub to start.
Click the Open URL icon to start using the Developer Hub platform.
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
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
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>
NoteYou 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
Log in to the
registry.redhat.io
inpodman
by running the following command:podman login registry.redhat.io
For more information about registry authentication, see Red Hat Container Registry Authentication.
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
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.
ImportantIf an x509 error occurs, verify that you have installed the CA certificate used for OpenShift Container Platform routes on your system.
Use the following command to verify that both images are present in the internal OpenShift Container Platform registry:
oc get imagestream -n <project_name>
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
Go to YAML view and update the
image
section forbackstage
andpostgresql
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
- 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
- A cluster administrator has installed the Red Hat Developer Hub Operator. For more information, see Installing the Red Hat Developer Hub Operator.
Procedure
Create a project in OpenShift Container Platform for your Red Hat Developer Hub instance, or select an existing project.
TipFor 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.
- From the Developer perspective on the OpenShift Container Platform web console, click +Add.
- From the Developer Catalog panel, click Operator Backed.
- In the Filter by keyword box, enter Developer Hub and click the Red Hat Developer Hub card.
- Click Create.
- Add custom configurations for the Red Hat Developer Hub instance.
- 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.
- 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.
From the Topology view, click the Open URL icon on the Developer Hub pod.
Additional resources
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
andbackend.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 theCustom Resource spec.application.route field
and adjust the application configuration accordingly.
-
You can use the
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
- From the Developer perspective, select the ConfigMaps tab.
- Click Create ConfigMap.
- Select the YAML view option in Configure via and make the changes to the file, if necessary.
- Click Create.
- Select the Secrets tab.
- Click Create Key/value Secret.
-
Name the secret
secrets-rhdh
. 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")'
- Click Create.
- Select the Topology view.
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.
Add the
spec.application.appConfig.configMaps
andspec.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
- Click Save.
- Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
- Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.
Additional resources
- For more information about roles and responsibilities in Developer Hub, see Role-Based Access Control (RBAC) in Red Hat Developer Hub in the Administration Guide for Red Hat Developer Hub.
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.
If the pluginConfig
field references environment variables, you must define the variables in your secrets-rhdh
secret.
Procedure
- From the OpenShift Container Platform web console, select the ConfigMaps tab.
- Click Create ConfigMap.
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 pluginkind: 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: {}
- Click Create.
- Go to the Topology tab.
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.
Add the
dynamicPluginsConfigMapName
field to yourBackstage
CR. For example:apiVersion: rhdh.redhat.com/v1alpha1 kind: Backstage metadata: name: my-rhdh spec: application: # ... dynamicPluginsConfigMapName: dynamic-plugins-rhdh # ...
- Click Save.
- Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
- 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.
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
-
You have an active
oc
session with administrative permissions to the OpenShift Container Platform cluster. See Getting started with the OpenShift CLI. -
You have an active
oc registry
session to theregistry.redhat.io
Red Hat Ecosystem Catalog. See Red Hat Container Registry Authentication. -
The
opm
CLI tool is installed. See Installing the opm CLI. - The jq package is installed. See Download jq.
- Podman is installed. See Podman Installation Instructions.
- Skopeo version 1.14 or higher is installed. See Installing Skopeo.
- If you already have a mirror registry for your cluster, an active Skopeo session with administrative access to this registry is required. See Authenticating to a registry and Mirroring images for a disconnected installation.
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, thehtpasswd
command is available by installing thehttpd-tools
package.
Procedure
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"
NoteThe script can take several minutes to complete as it copies multiple images to the mirror registry.