Internal Developer Platforms – Part 10: Working with Software Templates and Backstage Search

After having described how to install Backstage, we want finally show how to work with Backstage. In this blog post, we will focus on software templates and the Backstage Search.

Software Catalog

The Software Catalog is a fundamental component of a Backstage deployment, serving as an essential management tool. After deployment and login, users can easily access the Software Catalog by clicking the „Home“ button. This interface presents a list of all registered entities—such as software components, resources, or users—and offers filtering options to navigate through them. Entities, defined in YAML files and registered in Backstage, represent either physical or virtual organizational units, each classified by type and kind. Initially, the catalog displays entities of the „Component“ type, but users can adjust the view to include „Location,“ „Resource,“ „System,“ and „Template“ types based on available registrations. The availability of entity types in the dropdown menus depends directly on their presence in the catalog, exemplifying the customizable and interconnected nature of the Backstage ecosystem.

As a user, we can register applications into Backstage in different ways:

1. Direct Creation from Backstage: Users can create and register new entities directly in Backstage using pre-existing templates. This involves selecting a template via the „Create…“ button in the sidebar, which leads to the „Create a New Component“ page. After completing the creation and registration process, the new component becomes available in the Software Catalog.

2. Configuration File Entry: Entities can be added by specifying a „Location“ in the app-config.yaml configuration file, which links to a YAML descriptor file for each entity. These files are read and their entities are registered in the Software Catalog upon deployment.

catalog:
  locations:
    - type: url
      target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/react-ssr-template/template.yaml
      rules:
        - allow: [Template]
    - type: file
      target: template.yaml # Backstage will expect the file to be in packages/backend/template.yaml


 

3. Custom Entity Providers or Processors: For companies with extensive software portfolios, Backstage’s backend can be extended with custom entity providers or processors. These read from internal or external sources to generate new entities automatically and regularly. For example, you can use a provider for GitHub to automatically load entities like users from an external source into your Backstage instance.

4. Manual Registration via UI: If a component is already stored online in a repository with the required YAML descriptor file, it can be manually registered. Users navigate to the „Create a New Component“ page, click „Register existing component,“ and input the URL of the YAML file. After verification, the „Import“ button adds the component to the Software Catalog.

How to define entities

When manually registering an entity, a YAML file must be available for the corresponding entry. Each entry in the Software Catalog corresponds to a YAML file, ideally housed alongside the code of the related software in a repository. This YAML file contains metadata and additional information required to display the component in the Software Catalog. While users can choose any name for the YAML file, known as the „descriptor file,“ Backstage recommends the name „catalog-info.yaml.“ Consequently, when creating a repository, especially in „mono-repos“ where multiple components are hosted in a single repository, it’s crucial to structure the repository using folders to avoid name conflicts with existing descriptor files.

In the following we show how you could define your repository structure to register an application consisting of a backend with api and db, and a frontent:

The structure of the YAML files used by Backstage must adhere to specific rules for the entries to be properly recognized during the import process. An example of such a descriptor file, specifically for the exampleApp frontend component, illustrates the essential structure which consists of elements like `apiVersion`, `kind`, `metadata`, and `spec` that are mandatory in the YAML file. The `apiVersion` describes the specification format version for the entity the file is created for, consistently set as `backstage.io/v1alpha1` in the current project. The `kind` field defines the type of entity it should be listed as in the Software Catalog. Recognized types by Backstage and its plugins include Component, API, Group, User, Resource, and Location, among others. Backstage provides detailed definitions for all entity types in its documentation, assisting the platform team in orientation and categorization of the units represented.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: exampleappfrontend
  description: Simple Webseite
  links:
    - url: http://simple-website.sclabs.cloud
      title: ExampleApp
      icon: web
  annotations:
    github.com/project-slug: sclabs/exampleApp/frontend/
    backstage.io/techdocs-ref: dir:.
spec:
  type: Website
  lifecycle: production
  owner: Joseph Cooper
  system: exampleapp
  consumesApis: ['component:exampleappservice']

That’s it for today. In the next blog post, we will describe the different entity types in detail.