Introduction to Concepts

Red Hat Developer Hub, and internal developer portals in general, can be thought of as a modular system where you aggregate and display data related to the software within an organization.

The core features of Red Hat Developer Hub are the:

  • Software Catalog

  • Software Templates

  • TechDocs

  • Kubernetes Integration

Software Templates

Software Templates have been referred to as "Golden Paths" in the past. These templates are designed and curated by platform engineers to provide a starting point for new software components that adhere to best practices within an organization. Templates can also be used to patch and update existing source code repositories.

We’ll dive deeper into Software Templates in another module!

Software Catalog

The Software Catalog is a centralised asset tracker for all of the software in your organization. It stores and tracks Entities:

  • Components: Units of software, e.g microservices, websites, libraries.

  • Resources: Databases, S3 buckets, brokers.

  • APIs: Represent interfaces such as REST, gRPC, and GraphQL APIs.

  • Systems: Collections of Components that make up an application or platform.

  • Domains: A higher-level grouping of Systems and Entities.

  • User: Individual users that are part of your organization.

  • Group: Groups of Users.

Entities are typically imported and synchronized in one of three ways:

  1. Using plugins that automatically find and import them.

  2. Manually registering entities via the UI by providing a link to a repository containing them.

  3. Declaring them in the Backstage configuration.

In all cases, the Entities will be synchronized on a regular schedule to ensure the information in the Software Catalog remains up to date. You’ll utilize all three methods throughout this workshop.

If Entity information is stored in a Git repository, the convention is to place them in a catalog-info.yaml. This file will look similar to the following example:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-amazing-microservice
  description: A microservice written to do amazing things

  # Annotations are typically used to provide extra context to plugins, e.g TechDocs
  annotations:
    # Tells the TechDocs plugin where to find documentation sources. In this case
    # "dir:." means in the root of the repo containing this catalog-info.yaml
    backstage.io/techdocs-ref: dir:.

  # Arbitrary list of string that can be used to filter Entities in the Software Catalog
  tags:
    - docs

spec:
  type: Documentation
  lifecycle: development

  # Reference to the User or Group Entity that is responsible this Component
  owner: "pe1"

Users and Groups can be specified as owners of other Entities. If this seems abstract, don’t worry, you’ll see it in definitive terms shortly. A well curated Software Catalog will enable your developers to find API documentation and teams that are responsible for the Components powering those APIs, for example.

Plugins

Backstage - and by extension Red Hat Developer Hub - supports the concept of plugins. Utilizing plugins is a critical part of enabling the desired functionality for your IDP.

Currently, running an instance and adding plugins to upstream Backstage requires a platform engineer to:

  1. Create a Backstage project using Node.js and npm.

  2. Install the plugin(s) from npm.

  3. Edit the Backstage React and Node.js source code to load the plugin.

  4. Build a container image and deploy it.

The ability to load plugins dynamically is a value added feature included in Red Hat Developer Hub that’s currently unavailable in upstream Backstage - you can read more about it in the Red Hat Developer Hub documentation. The dynamic plugin support in Red Hat Developer Hub means that new plugins can be installed without the need to edit code and rebuild the Red Hat Developer Hub container image.

You’ll see dynamic plugins in action shortly.

Understanding the Red Hat Developer Hub Configuration

Upstream Backstage uses an app-config.yaml file to define configuration values. Red Hat Developer Hub is no different.

A simple Backstage configuration file looks similar to the following example:

# Define authentication configuration (this example is for testing only!)
auth:
  providers:
    guest:
      dangerouslyAllowOutsideDevelopment: true

# Static configuration for the Software Catalog. Can be used to import
# entities on startup, and restrict the entity types that can be imported.
catalog:
  rules:
    - allow: [Component, System, API, Resource, Location, Template]
  locations:
    - type: file
      target: https://github.com/org-name/repo-name/entities.yaml

# A configuration for the TechDocs plugin. This example instructs the plugin to
# build documentation at runtime, instead of pulling prebuilt HTML from S3
techdocs:
  builder: 'local'
  publisher:
    type: 'local'
  generator:
    runIn: local

Since you’re using the Red Hat Developer Hub Helm Chart to install and manage your internal developer portal, your configuration is nested under an upstream.backstage.appConfig property in a Helm Values file. View your configuration by visiting your rhdh/developer-hub-config repository on GitLab.

Your workshop environment has been pre-configured such that this repository in GitLab is continuously monitored and deployed using a backstage Application in OpenShift GitOps (login using the admin user and the password {openshift_gitops_password}).

With that out of the way, let’s get to work on configuring your instance of Red Hat Developer Hub!