Many organizations today are grappling with serious challenges that hinder their development teams’ productivity. High cognitive load, lack of standardization, and fragmented domain knowledge are common issues that lead to inefficiencies, increased maintenance costs, and even security vulnerabilities.

Red Hat provides the tools and know-how to help "The Providers" (Platform Engineers) to create "The Product" (their internal developer portal) based on the needs of "The Customers" (all Development Teams within the organization).

This workshop is designed for Platform Engineers who are in charge of:

This workshop is built in a learn-by-example style, where we show you how to create, set up, and manage an IDP using Red Hat Developer Hub. The workshop is opinionated and should be viewed as an example of how to approach things. As always, make sure you, as a Platform Engineer, build what your customers (Development Teams) need by soliciting early feedback to ensure you’re on the right track.

This workshop can also help Development Teams who are in charge of creating a software solution, and empower (traditionally speaking) in picking their own tools for coding, building, deploying, running, monitoring and documentation.

After completing this workshop you’ll:

The following image is a journey map of the workshop modules. The modules must be executed sequentially.

Parasol is an Insurance company but looking at rapidly expanding into different other verticals such as retail etc. With business booming, and their online presence increasing, the teams also grow in numbers. But the team, while being quite technically proficient, is quite siloed in their way of working especially because they are widespread and this results in difficulties in collaborating with each other.

With a rapidly evolving and expanding team, it is getting harder and harder for the team to keep up with

The team hears about the magic words - Internal Developer Platform (IDP), and some research shows that Red Hat Developer Hub would be perfect because of how customizable it is and especially the fact that it can run on on-prem to air gap sensitive content.

Red Hat Developer Hub streamlines development through a unified and open platform that reduces cognitive load and frustration for developers. It provides pre-architected and supported approaches that can help Parasol get their applications into production faster and more securely—without sacrificing code quality.

Red Hat Developer Hub and its associated plugins extend the popular upstream Backstage product by providing additional features such as integration with OpenShift, enterprise role-based access control (RBAC), and dynamic plugins - while including all the nice goodies that come with Backstage project itself.

In this workshop, you will walk through in the steps of the platform engineers

All of this boiling down to how to setup Development Teams up for success in a cloud native, AI infused world!

Red Hat Developer Hub is based on the Backstage framework for building internal developer portals. The Backstage project was donated to the CNCF by Spotify in 2020. Platform engineers can use Red Hat Developer Hub to build internal developer portals. Doing so involves integrating Red Hat Developer Hub with various data sources, cataloging existing software components, infrastructure, and resources, configuring single sign-on, and more.

In this module you’ll learn how to architect, install, and bootstrap an instance of Red Hat Developer Hub to create a minimum viable internal developer portal for a select group of developers within your organization.

The initial use cases for your developer portal are:

Satisfying the previously defined use cases involves configuring Red Hat Developer Hub to integrate with your existing platforms, tools, and infrastructure. For example, if your organization uses OpenShift Pipelines for continuous integration, you’ll need to configure the Red Hat Developer Hub instance with the appropriate integration to fetch and display data from an OpenShift cluster used to perform Pipeline Runs.

It could be said that the value of an internal developer portal is proportional to the thought and energy invested into it by the platform engineer(s), and developers using it.

In this module you’ll:

Your workshop environment has been preconfigured with the following software and platform components:

For the purposes of this workshop, we’ll assume that your organization has standardized on these tools, and it’s your objective as the platform engineer to integrate them with Red Hat Developer Hub. :imagesdir: ../../assets/images

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:

Red Hat Developer Hub has been pre-deployed with a base configuration in your workshop environment. You can find and access your instance in the backstage project on OpenShift.

Login to Red Hat Developer Hub:

The sign-in page will be displayed, with the option to login as a Guest. Click the Enter button to use the Guest sign-in.

Visit the Catalog using the link in the menu on the left-hand side of the Red Hat Developer Hub UI. You’ll find that the Kind dropdown provides only Plugin and Package options. These represent plugins that can be installed in Red Hat Developer Hub, but these don’t represent any of the software components deployed by Parasol. An empty catalog is no good to your developers - you’ll address that soon!

In module 2.1 you learned that the Software Catalog contains Entities, and saw a sample appConfig that contained a catalog.locations configuration. That example configuration imported entities from a file located in a hardcoded Git repository. This pattern is known as a static configuration. Red Hat Developer Hub will occasionally poll for updates to the specified file locations and update the Entities in the Software Catalog accordingly.

An option for dynamically importing and synchronizing Entities is via providers. Providers are added to Red Hat Developer Hub using plugins, and are configured using the catalog.providers entry in the appConfig. Let’s use the Keycloak plugin to synchronize Users and Groups to your Software Catalog.

This block of configuration instructs the Keycloak provider to synchronize Users and Groups from the specified Keycloak Realm to the Software Catalog.

Your changes will start to rollout. Confirm this by visiting the backstage project on OpenShift and checking that a new Pod is being started, or waiting until the Application in OpenShift GitOps reports Healthy instead of Progressing.

Once the new Pod has started, navigate to OpenShift and check the logs for lines that reference the KeycloakOrgEntityProvider. You should see a line stating that a number of Users and Groups have been read from Keycloak.

You can further confirm that the Users and Groups have been synchronized by visiting the Software Catalog in Red Hat Developer Hub and setting the Kind dropdown to User.

Nice work! You enabled a dynamic plugin and configured a catalog provider based on it! :imagesdir: ../../assets/images

Red Hat Developer Hub supports four authentication providers:

In this activity you’ll configure an OpenID Connect authentication provider - this will enable developers within your organization to login using their single sign-on (SSO) credentials.

Now that the import of User and Group entities and authentication is enabled for those same users, let’s focus on importing more Entities from your Git repositories. Having a rich and complete Software Catalog increases the value of the your IDP.

Recall the techdocs configuration from your values.yaml file in GitLab. It should resemble the following example:

This particular configuration is instructing TechDocs to build (builder) and store documentation locally (publisher.type), in the running Red Hat Developer Hub container.

The generator: local option instructs TechDocs to build the documentation on-demand. This requires the underlying container to have the necessary dependencies installed - Red Hat Developer Hub has these dependencies in place.

It’s possible to offload the TechDocs build process to a CI/CD pipeline that uses the TechDocs CLI. In this scenario, the pipeline builds and publishes the TechDocs to S3 or other storage solution. The platform engineer must configure a builder of type external and the publisher to read from the same storage system to load the desired TechDocs for a given Entity if an alternative storage solution is used.

Using the external builder strategy reduces load on the Red Hat Developer Hub instance, but places the burden of building and publishing the TechDocs on authors. Repository owners and authors can build their TechDocs using the TechDocs CLI.

Congratulations! You’ve learned the core concepts of Backstage and Red Hat Developer Hub. You also learned how to deploy and manage an instance of Red Hat Developer Hub using the official Helm Chart via OpenShift GitOps.

Software Templates in Red Hat Developer Hub enable your team(s) to create Entities, such as new Components, and - through the use of "actions" provided by plugins - create resources in other systems such as your GitLab and OpenShift GitOps instances. Templates themselves are Entities, meaning you can import them similar to any other Entity!

Platform Engineers will often be the authors of Templates, and use them to create "golden paths" that follow best-practices and use approved processes and tooling. Development teams will be the consumers of Templates to create new software and automate their tasks. Using Templates reduces cognitive load on the development teams by allowing them to focus on development tasks, while platform concerns are addressed by the template.

Templates are defined using YAML, but are rendered as a rich form in the Red Hat Developer Hub UI when used by development teams.

As mentioned earlier, Templates are defined using YAML and rendered as a rich form in the Red Hat Developer Hub UI when used by development teams.

Let’s explore the Template structure using a sample Template in the rhdh/template-quarkus-simple repository in GitLab.

The Software Template you’ll be using in this activity is stored in the template.yaml file in the rhdh/template-quarkus-simple repository in GitLab.

Register this template using the Red Hat Developer Hub UI:

Return to the Catalog section, and set the Kind filter to Template. Your new Quarkus Service template will be listed. Clicking on the template reveals that it looks a lot like the Component Entity you imported in the previous module.

Before using the Template, we’ll need to onboard a developer. Continue to the next section to complete a developer-focused task. :imagesdir: ../../assets/images

Until now, you’ve been acting in the role of a platform engineer. Let’s switch persona to that of a developer: dev1.

Let’s assume that this developer needs to create a development environment to work on a new feature - we can use a Software Template to assist with this task. A prerequisite to using this template is that the developer has a Quay account, so their code can be built into a container image and pushed to an image registry for storage and scanning.

While OpenShift has a built-in image registry, there are various reasons we’re using Quay as our image registry:

Login as Developer

Create a new software Component and supporting infrastructure using the Quarkus Service template that was created by the platform engineer:

The Argo CD Backstage plugin brings sync status, health status, and update history of your Argo CD Application to your Red Hat Developer Hub’s Component view. However, simply installing the Argo CD plugin doesn’t automatically make the associated deployment information visible when viewing Components in the Software Catalog. An argocd/app-selector annotation must be added to the Component’s YAML definition. This annotation instructs the Argo CD plugin to fetch the information related to the Component from the Argo CD instance you configured.

While the developer can add the necessary annotations to their Component, it’s best to update the Template so future developers can benefit from the Argo CD integration without having to manually add the annotation.

Congratulations! You’ve learned how to:

By setting up Role-Based Access Control (RBAC), the Platform Engineer can restrict the visibility of entities and availability of actions to subsets of users. It’s possible to define roles with specific permissions and then assign those roles to the Users/Groups to meet the specific needs of your organization and teams. RBAC can be configured via the Red Hat Developer Hub UI and REST API, or by using configuration files.

In this module you will

Policies are stored on OpenShift using a ConfigMap. The ConfigMap containing policies has has been pre-deployed to streamline this section of the workshop. Click here to view the policies in the OpenShift backstage namespace. The RBAC policies are defined using the Casbin rules format.

Policies define roles and their associated permissions, and assign roles to groups and users. The following example states that any user or group with role role:default/platformengineer can create Catalog Entities:

To assign this role to a group group:default/platformengineers, you’d use the following sytntax:

The result is that users belonging to the platformengineers group can create Catalog Entities.

As with other Red Hat Developer Hub plugins, enabling RBAC involves modifying the configuration file stored in GitLab.

So far in this workshop we assumed that only Platform Engineers can create Catalog Entities, but without configuring RBAC policies any user can create, edit, and delete Entities. Using RBAC allows you to configure read/write access as it suits your organization.

For details on other ways to setup RBAC polices refer to the Authorization guide in the Red Hat Developer Hub documentation.

Organizations need to provide a pathway for teams to import their existing services, APIs and resources to Red Hat Developer Hub. This module focuses on an opinionated way to onboard existing projects and applications so that developer teams can discover them through the internal developer portal.

Platform Engineering teams can create Software Templates that enable teams to import their apps into Red Hat Developer Hub. The Software Template can gather details about the component’s repository, documentation, dependencies, CI/CD, and various other details which allows development teams to accelerate their inner-loop of developing the assigned features and tasks.

Let’s look at a few concepts relevant to using Software Templates to import existing applications.

The Platform Engineering team creates two Templates for importing existing applications/services, 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.

The new templates require a set of dynamic plugins to function detect the newly created Entities:

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.

In this module, you will import an existing API and an existing application (Component) using the Software Templates that were setup by the Platform Engineer in the previous section.

When developers are assigned a JIRA task or feature to enhance an application, they start by creating a feature branch on Git. They continue working on this branch until their changes are ready to be merged into the main branch. Providing an ephemeral development environment for these developers enables a continuous inner loop, enhancing productivity and accelerating development.

The Platform Engineer creates a new Software Template to set up an ephemeral development environment for Developers working on the parasol-store application. This template performs several tasks:

With this approach, the Platform Engineers enable developers to just focus on coding. The templates simplify the set up of these ephemeral dev environments in a self-service manner. This allows the developers to create them repeatedly and easily, thereby rapidly increasing developer productivity.

In this module, as a Developer you are tasked to make change to an existing service - the parasol-store service. You will create a feature branch of the repository and then work in an ephemeral environment that allows you to work independently without impacting other developers in your team. Once you are ready with the changes, you can raise a merge request to push your changes to main branch, and there progressing the changes to production deployment

In this module you learned how Software Templates and plugins can accelerate developer productivity. With Red Hat Developer Hub, developers have access to all the necessary tools via a single pane of glass, reducing cognitive load.

This marks the end of the inner loop within the ephemeral development environment. In the next section, you will create a merge request to the main branch to initiate the outer loop.

With the development inner-loop complete, the code running in the ephemeral environment’s feature branch namespace is now ready for deployment to Dev, Staging, and Production environments.

In reality, the merge would happen after a peer review, or a team lead would review and merge the PR. For the purposes of this workshop, let us go ahead and assume the role of a reviewer.

A developer can effortlessly set up an ephemeral development environment, build and test their code, and seamlessly advance it to production with the necessary guardrails in place.

All of this is accessible through a single-pane-of-glass experience on Red Hat Developer Hub, eliminating the need to switch between multiple tools and platforms to track both inner-loop and outer-loop progress and statuses.

The dynamic plugins that you enabled in previous modules provide incredible value to this experience by integrating real-time insights and providing contextual visibility, ensuring a smooth and efficient development lifecycle, there by reducing developer cognitive overload and streamlining the development lifecycle.

In modern organizations, platform engineering is not a one-time effort but a continuous process of refinement and improvement. Static platforms struggle to keep up with evolving application architectures, security needs, and developer workflows. This module explores strategies to ensure platforms remain efficient, scalable, and user-friendly over time.

This module addresses the following areas

In Module 1, we looked at how a well-designed platform can support a wide range of user and application needs. However, user requirements evolve quickly. Platforms that do not adapt risk becoming bottlenecks. Agile, flexible platforms are crucial for platform engineers who must account for shifting technologies, security concerns, and business objectives. By continuously improving platform capabilities, teams keep pace with organizational goals.

This chapter examines why static platforms fall behind, how unchecked platform divergence happens, and how to keep your platform current. The aim is to guide platform engineers in avoiding unnecessary complexity and in delivering consistent value.

Measuring developer engagement and understanding their usage of your internal developer portal is critical to better serving their needs. Red Hat Developer Hub includes an Adoption Insights plugin that can be enbaled by platform engineering teams to view detailed analytics on adoption and engagement within the internal developer portal.

Key metrics available include:

As a Platform Engineer and Red Hat Developer Hub administrator, you can track user activities, system events, and data changes with Developer Hub audit logs. These logs are accessible through the Red Hat OpenShift Container Platform web console, where administrators can view, search, filter, and manage log data.

In OpenShift Container Platform, metrics are exposed through an HTTP service endpoint under the /metrics path. You can create a ServiceMonitor custom resource (CR) to scrape metrics from a service endpoint in a user-defined project.

You can monitor user activities, system events, and data changes with Developer Hub audit logs. Telemetry data collection supports collecting and analyzing telemetry data to enhance Red Hat Developer Hub experience.

These topics are beyond the scope of this workshop, but you can explore them further in the Observability section of Red Hat Developer Hub product documentation.