Structuring the Service Catalog in Spotify's Backstage

05 Mar 2023

Spotify’s Backstage is an open-source platform that aims to streamline the software development process. One of its key features is the service catalog, a central place for managing all your services. In this blog post, we’ll explore how to structure the service catalog in Backstage.

Understanding the Service Catalog

The service catalog in Backstage is a comprehensive list of all the software components, resources, and services that your team or organization uses. It provides a single source of truth about the software you own, the status of the services, and who’s responsible for them.

How to Structure the Service Catalog

Define Your Services

The first step in structuring your service catalog is to define your services. A service in Backstage can be anything from a microservice, a library, a data pipeline, or even a team. Each service should have a clear purpose and ownership.

When defining your services, consider the following

Purpose

Clearly define the purpose of each service. What problem does it solve? What functionality does it provide? Understanding the purpose of a service helps teams and stakeholders determine its value and relevance within the organization. It also aids in making informed decisions about service dependencies, resource allocation, and future enhancements.

Some examples of service types:

• Microservice: A small, independent service that focuses on a specific business capability.
• Library: A reusable collection of code or functions that can be used by other services or applications.
• Data Pipeline: A system for processing and transforming data from one source to another.
• Frontend Application: A user-facing application that interacts with users and displays information.
• Backend Application: A server-side application that handles business logic and data processing.
• Infrastructure Service: A service that provides infrastructure resources, such as databases, storage, or networking.

These are just a few examples, and the specific types of services can vary depending on your organization and the nature of your software projects.

Ownership

Assign ownership to each service. This helps establish accountability and ensures that someone is responsible for maintaining and improving the service.

To ease management of ownership, Backstage supports using CODEOWNERS files to define service ownership. This allows you to specify who owns a service directly in the code repository, making it easy to keep track of service ownership and changes over time.

This means that ownership is dedfined in a single place so ensures it is maintained and up-to-date.

Catalog file

The catalog file is a YAML file that defines the services in your Backstage catalog. It’s a central place where you can define your services, their metadata, and their relationships. The catalog file is used to generate the service catalog in Backstage and is stored in the projects repository.

An example catalog-info.yaml file might look like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My service
  owner: my-team
spec:
  type: service
  lifecycle: production
  providesApis:
    - my-api
  dependsOn:
    - my-dependency
  system: my-system
---
apiVersion: backstage.io/v1alpha1
kind: system
metadata:
  name: my-system
  description: My system
spec
  owner: my-team
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-api
  description: My API
spec
  owner: my-team
  system: my-system

This file defines a service called my-service that provides an API called my-api and depends on a library called my-dependency. It also defines a system called my-system that the service belongs to.

The Backstage catalog system can model complex relationships between services, systems, and APIs, allowing you to define a rich and detailed service catalog that accurately reflects your software architecture. This is show in their diageam below.

Conclusion

Structuring your service catalog in Backstage can help you manage your services more effectively. By defining your services, using descriptors, organizing services by teams, using labels, and keeping your catalog up-to-date, you can create a service catalog that truly serves as a single source of truth for your software.