Administration guide for Red Hat Developer Hub

Procedure

1. From the OpenShift Container Platform web console, select the ConfigMaps tab.
2. Click Create ConfigMap.
3. From Create ConfigMap page, select the YAML view option in Configure via and make changes to the file, if needed.
4. Click Create.
5. Go to the Helm tab to see the list of Helm releases.
6. Click the overflow menu on the Helm release that you want to use and select Upgrade.

7. Use either the Form view or YAML view to edit the Helm configuration.

   • Using Form view

     1. Expand Root Schema → Backstage chart schema → Backstage parameters → Extra app configuration files to inline into command arguments.
     2. Click the Add Extra app configuration files to inline into command arguments link.

     3. Enter the value in the following fields:

        • configMapRef: app-config-rhdh
        • filename: app-config-rhdh.yaml
     4. Click Upgrade.

   • Using YAML view

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

        # ... other Red Hat Developer Hub Helm Chart configurations
        upstream:
          backstage:
            extraAppConfig:
              - configMapRef: app-config-rhdh
                filename: app-config-rhdh.yaml
        # ... other Red Hat Developer Hub Helm Chart configurations

        Copy to Clipboard Toggle word wrap
     2. Click Upgrade.

Procedure

1. From the Developer perspective in the OpenShift Container Platform web console, select the Topology view, and click the Open URL icon on the Developer Hub pod to identify your Developer Hub external URL: <RHDH_URL>.
2. From the Developer perspective in the OpenShift Container Platform web console, select the ConfigMaps view.
3. Click Create ConfigMap.

4. Select the YAML view option in Configure via and use the following example as a base template to create a ConfigMap object, 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: <RHDH_URL> 

   1

   
       backend:
         auth:
           externalAccess:
               - type: legacy
                 options:
                   subject: legacy-default-config
                   secret: "${BACKEND_SECRET}" 

   2

   
         baseUrl: <RHDH_URL> 

   3

   
         cors:
           origin: <RHDH_URL> 

   4

   Copy to Clipboard Toggle word wrap

   1

   Set the external URL of your Red Hat Developer Hub instance.

   2

   Use an environment variable exposing an OpenShift Container Platform secret to define the mandatory Developer Hub backend authentication key.

   3

   Set the external URL of your Red Hat Developer Hub instance.

   4

   Set the external URL of your Red Hat Developer Hub instance.

5. Click Create.
6. Select the Secrets view.
7. Click Create Key/value Secret.
8. Create a secret named secrets-rhdh.

9. 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")'

   Copy to Clipboard Toggle word wrap
10. Click Create.
11. Select the Topology view.

12. 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.

    

13. In the CR, enter the name of the custom application configuration config map as the value for the spec.application.appConfig.configMaps field, and enter the name of your secret as the value for the spec.application.extraEnvs.secrets field. For example:

    apiVersion: rhdh.redhat.com/v1alpha1
    kind: Backstage
    metadata:
      name: developer-hub
    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

    Copy to Clipboard Toggle word wrap
14. Click Save.
15. Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
16. Click the Open URL icon to use the Red Hat Developer Hub platform with the configuration changes.

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: <crt-secret> 

   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: <cred-secret> 

   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 a Backstage custom resource (CR):

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

   1

   
     application:
       extraFiles:
         mountPath: <path> # e g /opt/app-root/src
         secrets:
           - name: <crt-secret> 

   2

   
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key # key name as in <crt-secret> Secret
       extraEnvs:
         secrets:
           - name: <cred-secret> 

   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 RHDH 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: <crt-secret> 

   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: <cred-secret> 

   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: <cred-secret> # 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:
       - <cred-secret> # 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: dynamic-plugins-npmrc
       - name: postgres-crt
         secret:
           secretName: <crt-secret> 

   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.3.5

   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: <crt-secret>
             key: postgres-crt.pem # key name as in <crt-secret> Secret
       extraEnvs:
         secrets:
           - name: <cred-secret>
   # ...

   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. 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. 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 custom resource (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. Access the Template Editor by using one of the following options:

   
   • Open the URL https://<rhdh_url>/create/edit for your Red Hat Developer Hub instance.
   • Click Create…​ in the navigation menu of the Red Hat Developer Hub console, then click the overflow menu button and select Template editor.
2. Click Edit Template Form.
3. Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see Section 6.2, “Creating a template as a YAML file”.
4. In the Name * field, enter a unique name for your template.
5. From the Owner drop-down menu, choose an owner for the template.
6. Click Next.

7. In the Repository Location view, enter the following information about the hosted repository that you want to publish the template to:

   1. Select an available Host from the drop-down menu.

      Note

      Available hosts are defined in the YAML parameters by the allowedHosts field:

      Example YAML

      # ...
              ui:options:
                allowedHosts:
                  - github.com
      # ...

      Copy to Clipboard Toggle word wrap

   2. In the Owner * field, enter an organization, user or project that the hosted repository belongs to.
   3. In the Repository * field, enter the name of the hosted repository.
   4. Click Review.
8. Review the information for accuracy, then click Create.

Verification

1. Click the Catalog tab in the navigation panel.
2. In the Kind drop-down menu, select Template.
3. Confirm that your template is shown in the list of existing templates.

Verification

1. Click the Catalog tab in the navigation panel.
2. In the Kind drop-down menu, select Template.
3. Confirm that your template is shown in the list of existing templates.