Configuring Red Hat Developer Hub

Procedure

1. Author your custom <my_product_secrets>.txt file to provision your secrets as environment variables values in an OpenShift Container Platform secret, rather than in clear text in your configuration files. It contains one secret per line in KEY=value form.

   • Enter your authentication secrets.

2. Author your custom app-config.yaml file. This is the main Developer Hub configuration file.

   The baseUrl field is mandatory in your app-config.yaml file to ensure proper functionality of Developer Hub. You must specify the baseUrl in both the app and backend sections to avoid errors during initialization.

   Example 1.1. Configuring the baseUrl in app-config.yaml

   app:
     title: Red Hat Developer Hub
     baseUrl: https://<my_developer_hub_url>
   
   backend:
     auth:
       externalAccess:
         - type: legacy
           options:
             subject: legacy-default-config
             secret: "${BACKEND_SECRET}"
     baseUrl: https://<my_developer_hub_url>
     cors:
       origin: https://<my_developer_hub_url>

   Copy to Clipboard Toggle word wrap

   Optionally, enter your configuration such as:

   • Authentication in Red Hat Developer Hub.
   • Authorization in Red Hat Developer Hub.
   • Customization.
   • Configure your OpenShift Container Platform integration.

3. Provision your custom configuration files to your OpenShift Container Platform cluster.

   1. Create the <my-rhdh-project> project aimed at containing your Developer Hub instance.

      $ oc create namespace my-rhdh-project

      Copy to Clipboard Toggle word wrap

      Alternatively, create the project by using the web console.

   2. Provision your app-config.yaml file to the my-rhdh-app-config config map in the <my-rhdh-project> project.

      $ oc create configmap my-rhdh-app-config --from-file=app-config.yaml --namespace=my-rhdh-project

      Copy to Clipboard Toggle word wrap

      Alternatively, create the config map by using the web console.

   3. Provision your <my_product_secrets>.txt file to the <my_product_secrets> secret in the <my-rhdh-project> project.

      $ oc create secret generic <my_product_secrets> --from-file=<my_product_secrets>.txt --namespace=my-rhdh-project

      Copy to Clipboard Toggle word wrap

      Alternatively, create the secret by using the web console.

Procedure

1. Author your Backstage CR in a my-rhdh-custom-resource.yaml file to use your custom config maps and secrets.

   Example 1.2. Minimal my-rhdh-custom-resource.yaml custom resource example

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: my-rhdh-custom-resource
   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
       extraFiles:
         mountPath: /opt/app-root/src
       replicas: 1
       route:
         enabled: true
     database:
       enableLocalDb: true

   Copy to Clipboard Toggle word wrap

   Example 1.3. my-rhdh-custom-resource.yaml custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets.

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: <my-rhdh-custom-resource>
   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
            - name: rbac-policies
       dynamicPluginsConfigMapName: dynamic-plugins-rhdh
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
            - name: my-rhdh-database-secrets
       extraFiles:
         mountPath: /opt/app-root/src
         secrets:
           - name: my-rhdh-database-certificates-secrets
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key
       replicas: 1
       route:
         enabled: true
     database:
       enableLocalDb: false

   Copy to Clipboard Toggle word wrap

   Mandatory fields

   No fields are mandatory. You can create an empty Backstage CR and run Developer Hub with the default configuration.

   Optional fields

   spec.application.appConfig.configMaps

   Enter your config map name list.

   .Mount files in the my-rhdh-app-config config map.

   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config

   Copy to Clipboard Toggle word wrap

   Example 1.4. Mount files in the my-rhdh-app-config and rbac-policies config maps.

   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
            - name: rbac-policies

   Copy to Clipboard Toggle word wrap

   spec.application.extraEnvs.envs

   Optionally, enter your additional environment variables that are not secrets, such as your proxy environment variables.

   Example 1.5. Inject your HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.

   spec:
     application:
       extraEnvs:
         envs:
           - name: HTTP_PROXY
             value: 'http://10.10.10.105:3128'
           - name: HTTPS_PROXY
             value: 'http://10.10.10.106:3128'
           - name: NO_PROXY
             value: 'localhost,example.org'

   Copy to Clipboard Toggle word wrap

   spec.application.extraEnvs.secrets

   Enter your environment variables secret name list.

   Example 1.6. Inject the environment variables in your Red Hat Developer Hub secret

   spec:
     application:
       extraEnvs:
         secrets:
            - name: <my_product_secrets>

   Copy to Clipboard Toggle word wrap

   Example 1.7. Inject the environment variables in the Red Hat Developer Hub and my-rhdh-database-secrets secrets

   spec:
     application:
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
            - name: my-rhdh-database-secrets

   Copy to Clipboard Toggle word wrap

Procedure

1. Configure Helm to use your custom configuration files in Developer Hub.

   1. Go to the Helm tab to see the list of Helm releases.
   2. Click the overflow menu on the Helm release that you want to use and select Upgrade.
   3. Use the YAML view to edit the Helm configuration.

   4. Set the value of the upstream.backstage.extraAppConfig.configMapRef and upstream.backstage.extraAppConfig.filename parameters as follows:

      Helm configuration excerpt

      upstream:
        backstage:
          extraAppConfig:
            - configMapRef: my-rhdh-app-config
              filename: app-config.yaml

      Copy to Clipboard Toggle word wrap

   5. Click Upgrade.

Procedure

1. Optional: Create a certificate secret to configure your PostgreSQL instance with a TLS connection:

   cat <<EOF | oc -n my-rhdh-project create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: my-rhdh-database-certificates-secrets 

   1

   
   type: Opaque
   stringData:
    postgres-ca.pem: |-
     -----BEGIN CERTIFICATE-----
     <ca-certificate-key> 

   2

   
    postgres-key.key: |-
     -----BEGIN CERTIFICATE-----
     <tls-private-key> 

   3

   
    postgres-crt.pem: |-
     -----BEGIN CERTIFICATE-----
     <tls-certificate-key> 

   4

   
     # ...
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Provide the name of the certificate secret.

   2

   Provide the CA certificate key.

   3

   Optional: Provide the TLS private key.

   4

   Optional: Provide the TLS certificate key.

2. Create a credential secret to connect with the PostgreSQL instance:

   cat <<EOF | oc -n my-rhdh-project create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: my-rhdh-database-secrets 

   1

   
   type: Opaque
   stringData: 

   2

   
    POSTGRES_PASSWORD: <password>
    POSTGRES_PORT: "<db-port>"
    POSTGRES_USER: <username>
    POSTGRES_HOST: <db-host>
    PGSSLMODE: <ssl-mode> # for TLS connection 

   3

   
    NODE_EXTRA_CA_CERTS: <abs-path-to-pem-file> # for TLS connection, e.g. /opt/app-root/src/postgres-crt.pem 

   4

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Provide the name of the credential secret.

   2

   Provide credential data to connect with your PostgreSQL instance.

   3

   Optional: Provide the value based on the required Secure Sockets Layer (SSL) mode.

   4

   Optional: Provide the value only if you need a TLS connection for your PostgreSQL instance.

3. Create your Backstage custom resource (CR):

   cat <<EOF | oc -n my-rhdh-project create -f -
   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: <backstage-instance-name>
   spec:
     database:
       enableLocalDb: false 

   1

   
     application:
       extraFiles:
         mountPath: <path> # e g /opt/app-root/src
         secrets:
           - name: my-rhdh-database-certificates-secrets 

   2

   
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key # key name as in my-rhdh-database-certificates-secrets Secret
       extraEnvs:
         secrets:
           - name: my-rhdh-database-secrets 

   3

   
           # ...

   Copy to Clipboard Toggle word wrap

   1

   Set the value of the enableLocalDb parameter to false to disable creating local PostgreSQL instances.

   2

   Provide the name of the certificate secret if you have configured a TLS connection.

   3

   Provide the name of the credential secret that you created.

   Note

   The environment variables listed in the Backstage CR work with the Operator default configuration. If you have changed the Operator default configuration, you must reconfigure the Backstage CR accordingly.

4. Apply the Backstage CR to the namespace where you have deployed the Developer Hub instance.

Procedure

1. Optional: Create a certificate secret to configure your PostgreSQL instance with a TLS connection:

   cat <<EOF | oc -n <your-namespace> create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: my-rhdh-database-certificates-secrets 

   1

   
   type: Opaque
   stringData:
    postgres-ca.pem: |-
     -----BEGIN CERTIFICATE-----
     <ca-certificate-key> 

   2

   
    postgres-key.key: |-
     -----BEGIN CERTIFICATE-----
     <tls-private-key> 

   3

   
    postgres-crt.pem: |-
     -----BEGIN CERTIFICATE-----
     <tls-certificate-key> 

   4

   
     # ...
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Provide the name of the certificate secret.

   2

   Provide the CA certificate key.

   3

   Optional: Provide the TLS private key.

   4

   Optional: Provide the TLS certificate key.

2. Create a credential secret to connect with the PostgreSQL instance:

   cat <<EOF | oc -n <your-namespace> create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: my-rhdh-database-secrets 

   1

   
   type: Opaque
   stringData: 

   2

   
    POSTGRES_PASSWORD: <password>
    POSTGRES_PORT: "<db-port>"
    POSTGRES_USER: <username>
    POSTGRES_HOST: <db-host>
    PGSSLMODE: <ssl-mode> # for TLS connection 

   3

   
    NODE_EXTRA_CA_CERTS: <abs-path-to-pem-file> # for TLS connection, e.g. /opt/app-root/src/postgres-crt.pem 

   4

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Provide the name of the credential secret.

   2

   Provide credential data to connect with your PostgreSQL instance.

   3

   Optional: Provide the value based on the required Secure Sockets Layer (SSL) mode.

   4

   Optional: Provide the value only if you need a TLS connection for your PostgreSQL instance.

3. Configure your PostgreSQL instance in the Helm configuration file named values.yaml:

   # ...
   upstream:
     postgresql:
       enabled: false  # disable PostgreSQL instance creation 

   1

   
       auth:
         existingSecret: my-rhdh-database-secrets # inject credentials secret to Backstage 

   2

   
     backstage:
       appConfig:
         backend:
           database:
             connection:  # configure Backstage DB connection parameters
               host: ${POSTGRES_HOST}
               port: ${POSTGRES_PORT}
               user: ${POSTGRES_USER}
               password: ${POSTGRES_PASSWORD}
               ssl:
                 rejectUnauthorized: true,
                 ca:
                   $file: /opt/app-root/src/postgres-ca.pem
                 key:
                   $file: /opt/app-root/src/postgres-key.key
                 cert:
                   $file: /opt/app-root/src/postgres-crt.pem
     extraEnvVarsSecrets:
       - my-rhdh-database-secrets # inject credentials secret to Backstage 

   3

   
     extraEnvVars:
       - name: BACKEND_SECRET
         valueFrom:
           secretKeyRef:
             key: backend-secret
             name: '{{ include "janus-idp.backend-secret-name" $ }}'
     extraVolumeMounts:
       - mountPath: /opt/app-root/src/dynamic-plugins-root
         name: dynamic-plugins-root
       - mountPath: /opt/app-root/src/postgres-crt.pem
         name: postgres-crt # inject TLS certificate to Backstage cont. 

   4

   
         subPath: postgres-crt.pem
       - mountPath: /opt/app-root/src/postgres-ca.pem
         name: postgres-ca # inject CA certificate to Backstage cont. 

   5

   
         subPath: postgres-ca.pem
       - mountPath: /opt/app-root/src/postgres-key.key
         name: postgres-key # inject TLS private key to Backstage cont. 

   6

   
         subPath: postgres-key.key
     extraVolumes:
       - ephemeral:
           volumeClaimTemplate:
             spec:
               accessModes:
                 - ReadWriteOnce
               resources:
                 requests:
                   storage: 1Gi
         name: dynamic-plugins-root
       - configMap:
           defaultMode: 420
           name: dynamic-plugins
           optional: true
         name: dynamic-plugins
       - name: dynamic-plugins-npmrc
         secret:
           defaultMode: 420
           optional: true
           secretName: '{{ printf "%s-dynamic-plugins-npmrc" .Release.Name }}'
       - name: postgres-crt
         secret:
           secretName: my-rhdh-database-certificates-secrets 

   7

   
           # ...

   Copy to Clipboard Toggle word wrap

   1

   Set the value of the upstream.postgresql.enabled parameter to false to disable creating local PostgreSQL instances.

   2

   Provide the name of the credential secret.

   3

   Provide the name of the credential secret.

   4

   Optional: Provide the name of the TLS certificate only for a TLS connection.

   5

   Optional: Provide the name of the CA certificate only for a TLS connection.

   6

   Optional: Provide the name of the TLS private key only if your TLS connection requires a private key.

   7

   Provide the name of the certificate secret if you have configured a TLS connection.

4. Apply the configuration changes in your Helm configuration file named values.yaml:

   helm upgrade -n <your-namespace> <your-deploy-name> openshift-helm-charts/redhat-developer-hub -f values.yaml --version 1.5.3

   Copy to Clipboard Toggle word wrap

Procedure

1. Configure port forwarding for the local PostgreSQL database pod by running the following command on a terminal:

   oc port-forward -n <your-namespace> <pgsql-pod-name> <forward-to-port>:<forward-from-port>

   Copy to Clipboard Toggle word wrap

   Where:

   • The <pgsql-pod-name> variable denotes the name of a PostgreSQL pod with the format backstage-psql-<deployment-name>-<_index>.
   • The <forward-to-port> variable denotes the port of your choice to forward PostgreSQL data to.

   • The <forward-from-port> variable denotes the local PostgreSQL instance port, such as 5432.

     Example: Configuring port forwarding

     oc port-forward -n developer-hub backstage-psql-developer-hub-0 15432:5432

     Copy to Clipboard Toggle word wrap

2. Make a copy of the following db_copy.sh script and edit the details based on your configuration:

   #!/bin/bash
   
   to_host=<db-service-host> 

   1

   
   to_port=5432 

   2

   
   to_user=postgres 

   3

   
   
   from_host=127.0.0.1 

   4

   
   from_port=15432 

   5

   
   from_user=postgres 

   6

   
   
   allDB=("backstage_plugin_app" "backstage_plugin_auth" "backstage_plugin_catalog" "backstage_plugin_permission" "backstage_plugin_scaffolder" "backstage_plugin_search") 

   7

   
   
   for db in ${!allDB[@]};
   do
     db=${allDB[$db]}
     echo Copying database: $db
     PGPASSWORD=$TO_PSW psql -h $to_host -p $to_port -U $to_user -c "create database $db;"
     pg_dump -h $from_host -p $from_port -U $from_user -d $db | PGPASSWORD=$TO_PSW psql -h $to_host -p $to_port -U $to_user -d $db
   done

   Copy to Clipboard Toggle word wrap

   1

   The destination host name, for example, <db-instance-name>.rds.amazonaws.com.

   2

   The destination port, such as 5432.

   3

   The destination server username, for example, postgres.

   4

   The source host name, such as 127.0.0.1.

   5

   The source port number, such as the <forward-to-port> variable.

   6

   The source server username, for example, postgres.

   7

   The name of databases to import in double quotes separated by spaces, for example, ("backstage_plugin_app" "backstage_plugin_auth" "backstage_plugin_catalog" "backstage_plugin_permission" "backstage_plugin_scaffolder" "backstage_plugin_search").

3. Create a destination database for copying the data:

   /bin/bash TO_PSW=<destination-db-password> /path/to/db_copy.sh 

   1

   Copy to Clipboard Toggle word wrap

   1

   The <destination-db-password> variable denotes the password to connect to the destination database.

   Note

   You can stop port forwarding when the copying of the data is complete. For more information about handling large databases and using the compression tools, see the Handling Large Databases section on the PostgreSQL website.

4. Reconfigure your Backstage custom resource (CR). For more information, see Configuring an external PostgreSQL instance using the Operator.

5. Check that the following code is present at the end of your Backstage CR after reconfiguration:

   # ...
   spec:
     database:
       enableLocalDb: false
     application:
     # ...
       extraFiles:
         secrets:
           - name: my-rhdh-database-certificates-secrets
             key: postgres-crt.pem # key name as in my-rhdh-database-certificates-secrets Secret
       extraEnvs:
         secrets:
           - name: my-rhdh-database-secrets
   # ...

   Copy to Clipboard Toggle word wrap
   Note

   Reconfiguring the Backstage CR deletes the corresponding StatefulSet and Pod objects, but does not delete the PersistenceVolumeClaim object. Use the following command to delete the local PersistenceVolumeClaim object:

   oc -n developer-hub delete pvc <local-psql-pvc-name>

   Copy to Clipboard Toggle word wrap

   where, the <local-psql-pvc-name> variable is in the data-<psql-pod-name> format.

6. Apply the configuration changes.

Verification

1. Verify that your RHDH instance is running with the migrated data and does not contain the local PostgreSQL database by running the following command:

   oc get pods -n <your-namespace>

   Copy to Clipboard Toggle word wrap

2. Check the output for the following details:

   • The backstage-developer-hub-xxx pod is in running state.

   • The backstage-psql-developer-hub-0 pod is not available.

     You can also verify these details using the Topology view in the OpenShift Container Platform web console.

Procedure

1. In your Backstage CR, add the securityContext specification. For example:

   spec:
     deployment:
       patch:
         spec:
           template:
             spec:
               containers:
                 - name: backstage-backend 

   1

   
                   securityContext:
                     readOnlyRootFilesystem: true

   Copy to Clipboard Toggle word wrap

   1

   Name of the main container defined in the Operator default configuration.

Procedure

1. In your values.yaml file, add the readOnlyRootFilesystem: true line to the containerSecurityContext section. For example:

   upstream:
     backstage:
       containerSecurityContext:
         readOnlyRootFilesystem: true

   Copy to Clipboard Toggle word wrap

Procedure

1. Perform one of the following steps based on your role:

   • As an administrator, set the proxy information in the Operator’s default ConfigMap file:

     1. Search for a ConfigMap file named backstage-default-config in the default namespace rhdh-operator and open it.
     2. Find the deployment.yaml key.

     3. Set the value of the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables in the Deployment spec as shown in the following example:

        Example: Setting proxy variables in a ConfigMap file

        # Other fields omitted
          deployment.yaml: |-
            apiVersion: apps/v1
            kind: Deployment
            spec:
              template:
                spec:
                  # Other fields omitted
                  initContainers:
                    - name: install-dynamic-plugins
                      # command omitted
                      env:
                        - name: NPM_CONFIG_USERCONFIG
                          value: /opt/app-root/src/.npmrc.dynamic-plugins
                        - name: HTTP_PROXY
                          value: 'http://10.10.10.105:3128'
                        - name: HTTPS_PROXY
                          value: 'http://10.10.10.106:3128'
                        - name: NO_PROXY
                          value: 'localhost,example.org'
                      # Other fields omitted
                  containers:
                    - name: backstage-backend
                      # Other fields omitted
                      env:
                        - name: APP_CONFIG_backend_listen_port
                          value: "7007"
                        - name: HTTP_PROXY
                          value: 'http://10.10.10.105:3128'
                        - name: HTTPS_PROXY
                          value: 'http://10.10.10.106:3128'
                        - name: NO_PROXY
                          value: 'localhost,example.org'

        Copy to Clipboard Toggle word wrap

   • As a developer, set the proxy information in your Backstage CR file as shown in the following example:

     Example: Setting proxy variables in a CR file

     spec:
       # Other fields omitted
       application:
         extraEnvs:
           envs:
             - name: HTTP_PROXY
               value: 'http://10.10.10.105:3128'
             - name: HTTPS_PROXY
               value: 'http://10.10.10.106:3128'
             - name: NO_PROXY
               value: 'localhost,example.org'

     Copy to Clipboard Toggle word wrap

2. Save the configuration changes.

Procedure

1. Set the proxy information in your Helm configuration file:

   upstream:
     backstage:
       extraEnvVars:
         - name: HTTP_PROXY
           value: '<http_proxy_url>'
         - name: HTTPS_PROXY
           value: '<https_proxy_url>'
         - name: NO_PROXY
           value: '<no_proxy_settings>'

   Copy to Clipboard Toggle word wrap

   Where,

   <http_proxy_url>

   Denotes a variable that you must replace with the HTTP proxy URL.

   <https_proxy_url>

   Denotes a variable that you must replace with the HTTPS proxy URL.

   <no_proxy_settings>

   Denotes a variable that you must replace with comma-separated URLs, which you want to exclude from proxying, for example, foo.com,baz.com.

   Example: Setting proxy variables using Helm Chart

   upstream:
     backstage:
       extraEnvVars:
         - name: HTTP_PROXY
           value: 'http://10.10.10.105:3128'
         - name: HTTPS_PROXY
           value: 'http://10.10.10.106:3128'
         - name: NO_PROXY
           value: 'localhost,example.org'

   Copy to Clipboard Toggle word wrap

2. Save the configuration changes.

Procedure

1. To specify a PVC mount path, add the rhdh.redhat.com/mount-path annotation to your configuration file as shown in the following example:

   Example specifying where the PVC mounts

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: <my_claim>
     annotations:
       rhdh.redhat.com/mount-path: /mount/path/from/annotation

   Copy to Clipboard Toggle word wrap

   where:

   rhdh.redhat.com/mount-path

   Specifies which mount path the PVC mounts to (in this case, /mount/path/from/annotation directory).

   <my_claim>

   Specifies the PVC to mount.

2. To specify a Secret mount path, add the rhdh.redhat.com/mount-path annotation to your configuration file as shown in the following example:

   Example specifying where the Secret mounts

   apiVersion: v1
   kind: Secret
   metadata:
     name: <my_secret>
     annotations:
       rhdh.redhat.com/mount-path: /mount/path/from/annotation

   Copy to Clipboard Toggle word wrap

   where:

   <my_secret>

   Specifies the Secret name.

Procedure

1. To mount Secrets to all containers, set the rhdh.redhat.com/containers annotation to * in your configuration file:

   Example mounting to all containers

   apiVersion: v1
   kind: Secret
   metadata:
     name: <my_secret>
     annotations:
       rhdh.redhat.com/containers: *

   Copy to Clipboard Toggle word wrap

   Important

   Set rhdh.redhat.com/containers to * to mount it to all containers in the deployment.

2. To mount to specific containers, separate the names with commas:

   Example separating the list of containers

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: <my_claim>
     annotations:
       rhdh.redhat.com/containers: "init-dynamic-plugins,backstage-backend"

   Copy to Clipboard Toggle word wrap

   Note

   This configuration mounts the <my_claim> PVC to the init-dynamic-plugins and backstage-backend containers.