DEV Community

Thy Pham
Thy Pham

Posted on

Build a service catalog for your software system using Backstage


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.

Image description

Image description

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 fullscreen mode Exit fullscreen mode

Enter y to proceed

Image description

Type in the name of your app:

Image description

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.

Image description

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

> cd my-system
> yarn dev
Enter fullscreen mode Exit fullscreen mode

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

Image description

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 :))

Image description

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:

kind: Component
  name: order-service
  description: This service receives new orders and processes them
    - nodejs
    - backend
  type: service
  lifecycle: production
  owner: backend-team
Enter fullscreen mode Exit fullscreen mode

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!

Image description

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

Image description

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.

Top comments (0)