Build your first Software Template for Backstage

More organizations are adopting the discipline of platform engineering and deploying internal developer portals (IDPs) to streamline developer onboarding and provide self-service capabilities. The goal of these initiatives is to reduce cognitive load on development teams and boost developer productivity.

Red Hat Developer Hub provides a distribution of the Cloud Native Computing Foundation (CNCF) Backstage project for enterprises building their IDPs. Software Templates are a core feature of Backstage that platform engineering teams can use to automate developer tasks and enable self-service.

This article guides you through the process of creating your first Software Template for Backstage, importing it into a Red Hat Developer Hub instance, and verifying that it works as planned from the perspective of a developer using the IDP. Specifically, your Software Template will create a new application repository on GitHub that includes a continuous integration (CI) pipeline implemented using a GitHub Actions workflow. The pipeline builds and publishes a container image that can be deployed on Red Hat OpenShift.

Prerequisites

This guide assumes that you have administrative access to a Red Hat Developer Hub instance. If you don't have access to an environment, follow this guide to get Red Hat Developer Hub running quickly on Red Hat's Developer Sandbox or refer to the documentation if you'd like to review the available installation options for your own OpenShift cluster.

You'll also need to configure the GitHub integration and provider to allow the template to create repositories in your GitHub organization.

Understanding Software Templates in Backstage

Software Templates are defined using a Backstage-specific YAML structure and are stored in a Git repository that your instance of Red Hat Developer Hub can access. The template YAML contains metadata about the template and a series of parameters and steps that the template collects and performs, respectively. A set of outputs can also be defined to link to resources created by the template. Internally, these templates are processed by a Backstage component known as the scaffolder when developers interact with them.

A form is rendered in the Red Hat Developer Hub user interface when developers interact with your Software Template. Developers are prompted to input parameters, as seen in Figure 1. When the template is executed, it will usually perform actions provided by Backstage plug-ins, such as creating a repository in GitHub or GitLab.

For example, developers can use Software Templates to generate new software projects that adhere to an organization's best practices, use supported frameworks and dependencies, or even provision virtual machines. A platform engineering team typically creates and maintains Software Templates.

As an example, a platform engineering team might provide a template that teams can use to bootstrap new software services. A well-crafted template could generate repositories with starter code, continuous integration and continuous delivery pipelines, deployment manifests, and include code signing and scanning to implement robust software supply chain security. You can also enable other self-service capabilities such as the provisioning of virtual machines. The process of a developer using a template to bootstrap a new project is illustrated in Figure 2.

Building a Software Template for Backstage

The basic steps for building your first template are:

1. Create a public Git repository (using a private repository requires extra configuration that's outside the scope of this article).
2. Create a template.yaml file in the Git repository.
3. Define parameters, steps, and outputs in a template.yaml file in the Git repository.
4. Import the template into Red Hat Developer Hub.
5. (Optional) Experiment with the template using the Template Editor in Red Hat Developer Hub.

Create a Git Repository to Store Templates

The easiest method to import templates into Red Hat Developer Hub is by storing template.yaml files in a Git repository that can be accessed by your Red Hat Developer Hub instance. We've provided a template repository on GitHub to expedite the getting started process—think of it as a template repository that can be used to create your own repository of Software Templates. 😉

Click the Use this template button, then select Create a new repository to make a copy of the template repository in your GitHub account or organization as shown in Figure 3.

The template repository includes a templates directory where each subdirectory contains a template.yaml file. This means you can use it to store all of your templates in a single repository, separating them by folders. You'll use the location.yaml file at the root of the repository to have Red Hat Developer Hub import each template.yaml file in the subfolders; you'll see this in action later.

Understanding the structure of a Software Template

Take a look inside the templates/nodejs-backend folder in your new repository. This folder contains a basic template.yaml file that scaffolds a new codebase based on the files in the skeleton directory and creates a Git repository to store the new code. The template collects a single parameter: the name of the application.

parameters:
  - title: Service Details
    required:
      - name
    properties:
      name:
        title: Service Name
        type: string
        description: Unique name for the service.
        maxLength: 50
        pattern: '^([a-zA-Z][a-zA-Z0-9]*)(-[a-zA-Z0-9]+)*$'

Next, the template performs two steps: it generates source code using the skeleton directory as a template and publishes the resulting source code to a new GitHub repository.

The fetch:template action fetches a codebase from the specified directory/URL and renders each file in the tree by passing the specified values as variables. In this case, that means any occurrence of ${{ values.name }} within a file in the skeleton directory will be replaced with the value of name in the rendered codebase.

The publish:github action will publish the code to a new or existing repository on GitHub. It requires the GitHub Backstage scaffolder plug-in to be installed and the GitHub integration to be configured (more on these later).

steps:
  - id: generateSource
    name: Generate Node.js Application Codebase
    action: fetch:template
    input:
      url: ./skeleton
      targetPath: ./source
      values:
        name: ${{ parameters.name }}
  - id: publishSource
    name: Create GitHub Repository
    action: publish:github
    input:
      allowedHosts: ['github.com']
      # IMPORTANT: replace "your-org" with the name of your own GitHub Organization
      repoUrl: github.com?owner=your-org&repo=${{ parameters.name }}
      defaultBranch: main
      sourcePath: ./source

You can find more information about available scaffolder actions by visiting the /create/actions endpoint of your Red Hat Developer Hub instance, as seen in Figure 4.

Import the Templates into Red Hat Developer Hub

At this point you need administrator access to an instance of Red Hat Developer Hub. You can get access to an instance for free by following the guide in Red Hat Developer Hub: The fastest path to Backstage on Kubernetes.

Importing the template involves registering the location.yaml from the root of your repository as a Location in Red Hat Developer Hub. Once a Location is registered, Red Hat Developer Hub will occasionally poll it and import the entities specified by the spec.targets field. The specific location.yaml in our example contains a glob pattern that instructs Red Hat Developer Hub to import all template.yaml files in subdirectories of the templates folder in your repository.

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: my-templates
spec:
  targets:
    - ./templates/**/template.yaml

After logging in to your instance of Red Hat Developer Hub, use the Self-service button in the top navigation menu (v1.6+) or the Create menu item (v1.5 and older) on the left to access the Self-service screen. Click the Register Existing Component button, shown in Figure 5.

Enter the URL to the location.yaml at the root of your template repository in the URL input. It should resemble the following example, with YOUR_USERNAME replaced by your GitHub username:

https://github.com/YOUR_USERNAME/backstage-template-template/blob/main/location.yaml

Click Analyze (Figure 6) and then Import when prompted.

All of the templates in your repository will be listed on the Self-service screen after a few seconds. Assuming you didn't add an extra template.yaml, a single template should be visible, as shown in Figure 7.

Now that the template has been loaded into Red Hat Developer Hub, you can experiment with future edits using the Template Editor. Visit the /create/edit endpoint and select the Template Form Playground to view the Template Editor. Existing templates can be viewed by clicking the Templates menu item and selecting a template, as seen in Figure 8. You can test the addition of new parameters using this interface, before committing them to your templates repository on GitHub.

Test your Template

One of the steps in the template you've imported creates a repository on GitHub using the publish:github action. This action is provided by the @backstage/plugin-scaffolder-backend-module-github plug-in. To enable this plug-in in Red Hat Developer Hub, add the following package to your dynamic plug-ins configuration:

dynamic:
  includes:
    - dynamic-plugins.default.yaml
  plugins:
    - disabled: false
      package: ./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic

Once you've configured the GitHub integration and installed the GitHub scaffolder plug-in for Backstage, your developers can use your template to create a new application. Select the template and enter a name for your new application, as shown in Figure 9.

Review the parameters, then run the template. Once it completes, a link to your new repository will be displayed; click it. Your new repository will contain source code from your template's skeleton. Notice that a GitHub Actions Workflow has also run automatically and published a container image to the repository's Packages section, because the generated repository includes a continuous integration pipeline and Dockerfile. See Figure 10.

Conclusion

Software Templates enable your platform engineering team to codify best practices, freeing your developers from the tedium of configuring infrastructure related YAML files and learning the ins and outs of your supply chain security, build pipelines, and continuous delivery processes. The template in this example is trivial, but can easily be extended to inject additional fields in the Component defined in the catalog-info.yaml, adding information such as API consumers and providers or TechDocs.

Go ahead and try Red Hat Developer Hub for yourself using our Developer Sandbox or your own OpenShift environment. When you're ready to take things further, you can take a look at our article that teaches you how to enable continuous delivery using Red Hat Developer Hub and Red Hat OpenShift GitOps.