Platform Engineer Activity: Setup Software Templates to Import Existing API/Apps

As mentioned in the previous section, the Platform Engineering team created two Templates for importing existing applications/services (Components), and APIs into Red Hat Developer Hub. While it is possible to use the same template to import both of them, there are some key differences in the data that must be gathered for API and Component Entities.

Please make sure to log in as a Platform Engineer with pe1 / {common_password}. Refer to the below guide for assistance.
Click to learn how to login as a Platform Engineer

Login as Platform Engineer

You will perform this activity as a Platform Engineer. Please follow the below steps to logout from Red Hat Developer Hub and GitLab, and login back as a Platform Engineer (pe1 / {common_password})

  • Logout from Red Hat Developer Hub

    • Sign out of Red Hat Developer Hub from the Profile dropdown as shown in the screenshot below.

      Signing out of Red Hat Developer Hub
  • Logout from GitLab

    • Click on the Profile icon, and Sign out from the dropdown as shown in the screenshot below.

      Signing out of GitLab
  • Login back as a Platform Engineer to Red Hat Developer Hub and GitLab using the credentials pe1 / {common_password}

Register the Import API and Component Templates

Software Template Overview

You learned how to create and import Software Templates using the Red Hat Developer Hub UI in module 3. In this section, you’ll import Templates that have been pre-built for you by adding them directly to the catalog.locations configuration in your values.yaml file instead of using the UI registration wizard.

The two Software Templates you’ll be importing are:

The import-existing-api template does the following:

  1. Gather details of the API (GitLab org name, repo name) as template parameters.

  2. Creates a Merge Request to create the new catalog-info.yaml and TechDocs files, which will register the API in the Software Catalog once merged.

The import-existing-app template does the following:

  1. Gather details of the new Component to be created (Git repository for the Component, the catalog info, etc.)

  2. Creates a Merge Request to create the new catalog-info.yaml and TechDocs files, which will register the Component in the Software Catalog once merged.

Add Templates to Catalog Configuration

  1. Visit your rhdh/developer-hub-config repository on GitLab. If prompted, login with pe1 / {common_password}.

  2. You should already be in Edit mode of the values.yaml file if you clicked the link above.

  3. Locate the catalog: section and find the locations: array.

  4. Add the following two new entries to the locations: array to import both Software Templates:

    catalog:
      locations:
        - type: url
          target: https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-api-template/-/blob/main/template.yaml
        - type: url
          target: https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-app-template/-/blob/main/template.yaml
    Make sure to maintain proper YAML indentation and alignment with the existing locations: entries.
  5. Don’t commit the changes yet - you need to also enable the required dynamic plugins for these templates to function properly.

Your changes in GitLab should resemble the following screenshot.

gitlab locations

View the Imported Templates

After you complete the configuration in the following sections and commit your changes, you can verify the templates are available by navigating to the Create screen. You should see both templates for importing APIs and applications to Red Hat Developer Hub.

import templates list

Setup GitLab Entity Auto-Discovery

The new templates require plugins to function, and ensure the newly created Entities are detected by Red Hat Developer Hub:

  • backstage-plugin-catalog-backend-module-gitlab-dynamic to enable auto-discovery of catalog-info.yaml files.

  • immobiliarelabs-backstage-plugin to create Merge Requests using the GitLab API.

Enable the Plugins

  1. Visit your rhdh/developer-hub-config repository on GitLab. If prompted, login with pe1 / {common_password}.

  2. You should already be in Edit mode of the values.yaml file.

  3. Locate the comment --- DYNAMIC_PLUGINS_IMPORT_COMPONENTS ---

  4. Highlight the YAML section shown in the below screenshot, and uncomment those lines. Use CMD + / or CTRL + / to do so.

    uncomment dynamic plugin
  5. Don’t commit the changes yet - you need to also enable auto-discovery.

Enable Auto-Discovery

  1. Locate the comment --- AUTO_DISCOVERY_IMPORT_COMPONENTS --- in the same values.yaml file.

  2. Highlight the YAML as shown in the below screenshot, and uncomment those lines.

    uncomment auto discovery
    This YAML snippet enables auto-discovery for all files named all-location.yaml (entityFilename) where the repo name starts with the word all-location (projectPattern).
  3. Scroll down and enter a commit message feat: Enable GitLab plugin and component auto discovery.

  4. Commit the file now using the Commit Changes button at the bottom of the page.

  5. Refresh the backstage Application to rollout the new Red Hat Developer Hub configuration - login as admin / {openshift_gitops_password}. Wait until the Application turns green and marked as Healthy.

Onboard Parasol’s System and Domain

In a previous chapter you learned how System and Domain Entities help organize and provide a hierarchy of Components in Red Hat Developer Hub. In this section you will setup Parasol’s System and Domain.

  1. From Red Hat Developer Hub, navigate to Create screen; choose Register Existing Component button

  2. Paste the below URL and click on Analyze

    https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/rhdh-entities/-/blob/main/locations.yaml
  3. Click Import in the Review section.

  4. The Systems and Domain are setup.

Systems are the basic level of encapsulation for related entities. Domains are useful to group a collection of Systems that share terminology, domain models, business purpose etc.