Build a service catalog for your software system using Backstage

Problem

A software system often contains multiple components such as backend services, database, API, documentation, etc. Is usually hard for us to have an overview, such as how many components we have? which component is connected to which? Who is the owner? Where can I find the documentation? Where can I see the API? etc.
One way to solve this problem is to build a catalog for our infrastructure. We can achieve this quickly with the help of Backstage.

What is Backstage?

Backstage is an open source project launched by a team at Spotify and is currently a CNCF Incubation project. Its purpose is to manage the microservices and infrastructure of the software systems.

Backstage has a Dashboard UI. It uses plugins for different features. Each plugin is presented on a separate page in the Dashboard and has its own URL. So, for example, we can access the catalog plugin using /catalog and the documentation plugin using /docs.

In the scope of this post, I will demonstrate the use of the catalog plugin. More plugins can be found in the market here. In addition, I suggest visiting its Docs page for more details on the Backstage project.

Catalog plugin

The catalog plugin lists all the services, libraries, databases, etc. It also shows the ownership, like who owns what and the relationship between the entities. We can describe this info using YAML files committed together with the code and link these files to the catalog to show them on the UI.

Let's get our hands dirty.

Step 1: Installation

Install Backstage using npx:

> npx @backstage/create-app

Enter y to proceed

Type in the name of your app:

Choose database for Backstage backend. Here I choose SQLite just for demonstration. Note that the data will be wiped out whenever we stop the app.

After the app is created, we can go to its directory and start it locally with yarn dev command.

> cd my-system> yarn dev

Backstage runs at localhost:3000 by default. Open the catalog page http://localhost:3000/catalog, and we will see this screen below.

As you can see, Backstage already includes three services playback-order, searcher, and shuffle-api, just for demonstration. Backstage defines these services in app-config.yaml file located in the root directory of the Backstage project code. You can see them at catalog.locations. Feel free to remove them if you like. I will just let them there. insert lazy meme :))

Step 2: Define our services

We can define our service by writing a YAML file. We should name it catalog-info.yaml, as Backstage suggests.

Let's say we have an order service written in Node JS. We can define this service like this:

apiVersion: backstage.io/v1alpha1kind: Componentmetadata:  name: order-service  description: This service receives new orders and processes them  tags:    - nodejs    - backendspec:  type: service  lifecycle: production  owner: backend-team

Backstage has explained the meanings of all the fields in the file above very clearly in its documentation. Commit this file to your Github order repository.

Step 3: Add the service to the Backstage catalog

Go to your catalog page at localhost:3000/catalog.
Click on "Create component" -> "Register existing component".
Paste the Github URL to your catalog-info.yaml file in the "Repository URL" input field. Then review and tap on import. And we're done!

Go back to localhost:3000/catalog. Select the tags nodejs, and we can see our order service is listed there!

Some thoughts

I like the feature of Backstage that allows us to define our infrastructure using YAML files and commit together with the code. This way, we can track the changes in our system by reviewing the commits.

Having everything (backend services, API, docs, resources...) in one place is super helpful. That helps dev teams have an overview and look up the info when necessary.

In my humble opinion, it would be even better to have a feature that automatically discovers our software components instead of manually writing the YAML files, so that the catalog is always up-to-date with the changes of our system.