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

Platform Engineering team creates two templates for importing existing Apps/Services and APIs into Developer Hub. While it is possible to use the same template to import both of them, there are some key differences in data gathered. As best practice, Platform Engg team creates as many Software Templates as necessary to assist developers.

Login as Platform Engineer

  • You will perform this activity as a Platform Engineer.

    • Logout from Developer Hub

      Click to see how to logout

      • Navigate to the Settings side-menu of Developer Hub and click on the kebab menu in the Profile card

        Settings of Red Hat Developer Hub

      • Sign out of Red Hat Developer Hub using the Settings screen as shown.

        Signing out of Red Hat Developer Hub

    • Logout from Gitlab

      Click to see how to logout

      • Click on the Profile icon, and Sign out from the dropdown.

        Signing out of Red Hat Developer Hub

  • Login to Red Hat Developer Hub and GitLab as pe1/{common_password}

Register the Import API/App Software Templates

Since you have already learnt how to create a Software Template, we will walk through a template that has been built for you.

Click here to view the import-existing-app Software Template

This template does the following:

  1. Gather details of the API, the target location of catalog info and the details of the software component

    st api params

  2. Update the _Envelope location file with the details as a two step process

    st api steps

    Why are there 2 merge requests?

    Gitlab allows only one type of action (such as Amend/Update) in a given Merge Request (MR). Therefore, we need a one MR to create the the new catalog-info and TechDocs file, and another MR to update the envelope location file with a reference to the catalog-info.yaml file

Register Import API Software Template

  • Access Red Hat Developer Hub (click here) and login using pe1/{common_password}

  • Click on the Create menu on the left-hand navigation.

    nav create

  • Click on the Register Existing Component button on the top-right of the page to launch the Register an existing component wizard

    nav register wizard

  • Paste the following URL into the Select URL field and click on Analyze button. This URL points to Software Template’s template.yaml file.

    https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-api-template/-/blob/main/template.yaml

  • Review, and Import the template by clicking on the Import button

    nav register import

  • The import-api-catalog Template is successfully registered

    nav access api template

Register Import App Software Template

  • Let us now register the import-app template as well similar to the Import API template.

  • Click Create (left hand nav) → Register Existing Component (top right)

  • Paste the following URL

    https://gitlab-gitlab.{openshift_cluster_ingress_domain}/rhdh/import-existing-app-template/-/blob/main/template.yaml

  • Review, and Import the template by clicking on the Import button

View the imported templates

  • Navigate back to Create (left hand nav) and you should be able to see both the templates for importing APIs and Apps to Developer hub

    import templates list

Setup Developer Hub config

Enable Dynamic Plugins

  1. The Import API/APP templates described above need a couple of Dynamic Plugins.

    1. The roadiehq-scaffolder-backend-module-utils-dynamic plugin helps in manipulating file system, and in this case helps in update the the Catalog Envelope file with references to the new component being imported.

    2. The backstage-plugin-catalog-backend-module-gitlab-dynamic plugin helps to discover catalog files located in your GitLab instance.

  2. You will also enable a couple of Community plugins which will help view Merge requests and Issues from Gitlab

    What are Dynamic Plugins?

    The Red Hat Developer Hub application offers a unified platform with various plugins. Plugins extend functionality, streamline development workflows, and improve the developer experience. You can add and configure plugins in RHDH to access various software development tools. RHDH provides both static and dynamic plugins that enhance its functionality. Static plugins are integrated into the core of the RHDH application, while dynamic plugins can be side-loaded into your Developer Hub instance without the need to recompile your code or rebuild the container.

  3. Visit your rhdh/developer-hub-config repository on GitLab. If prompted, login using (pe1/{common_password}).

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

  5. Locate the comment --- DYNAMIC_PLUGINS_IMPORT_COMPONENTS ---

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

    uncomment dynamic plugin

  7. Don’t commit the changes yet. We need to next turn on auto-discovery

Turn on 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 comment those lines. Type CMD+/ or CTRL+/ command to do so.

    uncomment auto discovery
    This YAML snippet enables auto-discovery for all files named envelope.yaml [entityFilename] where the repo name starts with the word envelope [projectPattern]. The Catalog Envelope for Parasol is called envelope-catalog-parasol

  3. Go ahead and commit the file now using the Commit Changes button at the bottom of the page with a suitable commit message.

    commit rhdh config

Refresh Developer Hub on Argo

Argo is tuned to pull changes from the repo every two minutes or so. Instead of waiting for the sync to kick in, you can Refresh the RHDH Argo Application as follows:

  • Access ArgoCD from here, and login as (admin/{openshift_gitops_password})

  • Click on the Refresh button of the backstage stage to trigger a refresh; this will sync the content from Gitlab.

    Click to view screenshot
    rhdh argo refresh

  • Wait till the app turns green and marked as Healthy.

Onboard Parasol’s System and Domain

In a previous chapter you learnt about how System and Domain help in organizing the 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 menu; 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.

    Learn more about Systems and Domain

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

    • Read more here