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/v1alpha1
kind: Component
metadata:
name: order-service
description: This service receives new orders and processes them
tags:
- nodejs
- backend
spec:
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.
Top comments (0)