Open source service catalogs in 2024

Introduction

Question:
What are the devops tools that Viktor Farcic foresees becoming part of his daily life in 2024?

Answer: 
Looking at the title of this post, you’re probably guessing that one of them is “service catalog”.

Indeed, in In Farcics’ “best devops tools for 2024”, the number one category was service catalogs, or, as we in Port call them, software catalogs. 

What are service catalogs, how are they used and built and what are the open source options? Also, how do they relate to internal developer portals, and what are the best open source options? 

Let’s begin:

We begin with complexity. The emergence of cloud native, devops practices, GitOps, Kubernetes and more means a lot of complexity, tooling with different interfaces, non-uniform terminology and a lot of expertise that is required to know what is going on.

The other thing to consider is responsibility. Developers are now responsible for more moving parts. Whereas in the past they were required to code and not much more, today developers are responsible for coding, shipping and running software and in some cases, full lifecycle responsibility for software.  

If managing 10 microservices (their dependencies, resources, associated developer tooling etc) is difficult, imagine doing the same for hundreds or thousands of microservices. This is what is going on and why service catalogs are needed. 

Service catalogs actually solve the three resulting problems with the developer experience. 

1. Discoverability - they create a central repository of all the data about microservices, their dependencies, packages, APIs, and anything else, creating organization and obviating the need to collect data in spreadsheets (yes, people really do that).

2. Mindless toil - by eliminating manual catalogs of microservices they save the mindless toil of manually updating appsec, feature flag and other pertinent data about microservices (which needs to be updated automatically and in real time, anyway)

3. Inconsistent experiences - without service catalogs, developers need to access the different interfaces with different (and confusing) data about microservices and the associated infra and tools.

The evolution of service catalogs

In the past, searching for the meaning of a “service catalog” resulted in the following, IT-centric definition:

“The service catalog is a list of the set of services offered by an organization, such as IT services, operations services etc”. 

This really is what service catalogs meant in the past. The idea was showing - like in a restaurant menu - what can be requested of IT and operations teams.

The result was streamlined communication and the ability of service managers to know which of their services was needed and to prioritize accordingly. An example of such service catalogs was jira service management.

However, today service catalogs have evolved to mean something that’s very different, mainly in assigning a different meaning both to the word “service” and to the word “catalog”.

While in the past the confusion was what are the services provided by the IT team, today the confusion is different - what is going on in a cloud native development environment and how can it be controlled, managed and grown.

From service catalog to microservice catalog

Today when we speak about a service catalog we actually mean a microservice catalog.

As microservices architectures become the norm, the question becomes a different one. Not which services are offered in the IT or ops sense, but which microservices exist within the engineering organization, how are they connected to each other, which APIs do they use and on what resources are they deployed. 

But why would you need a microservice catalog. Anyway?

The reason is that the complex architecture makes it impossible to track all services and answer simple questions

• Who is the code owner
• What is the appsec posture
• Are the services healthy, production ready etc (a scorecard functionality) 
• API data (API catalogs are a secondary use case for service catalogs)
• Dependencies and related services/resources etc
• Packages and more (a package catalog)

In short, we need a centralized metadata store with all the relevant data about the services. This would make it easy to avoid duplication, be easy to search resources and be able to deal with incidents etc.

Alternatives to open source service catalogs

What do people do instead of using a service catalog?

• They use a spreadsheet to track services (we explained why this doesn’t work well above)
• They use a CMDB (configuration management database) - which actually works more like a manual service catalog and was really defined for a previous era in software development
• They use a servicenow catalog 
• They use a service catalog in that’s part of the offering of their cloud service provider
• They use some catalog in their developer tooling
• They use an API catalog

Yet, these approaches don’t work well

• They are usually opinionated and not flexible, making adjustments to how your engineering DNA works almost impossible
• They are not context aware since they don’t contain all the ownership and metadata for all the software in the SDLC (services, websites, libraries, data pipelines, etc).
• They don’t support scorecards - although adding scorecards to services in the catalog can actually greatly boost tracking initiatives, production readiness and general compliance with engineering standards
• They don’t support adding documentation about the services
• They are not real time and they don’t update automatically 
• They aren’t aware of dependencies or context

This is why the service catalog was born.

Today the service catalogs form the core of internal developer portals. They are used by developers, devops, SREs and more to understand the entire environment from code to production. 

Despite the fact that service catalogs are just the first step in letting developers shift left, they are often the first tool required by platform engineers and anyone thinking of platform engineering. The reason is simple: before the pain of letting developers self-serve is solved, with reusable self-service actions, developers and devops first need to master the mess that is cloud native, this can only be done with a software catalog.

One of the basic things to understand is that a service catalog should be much more than a list of services.

• It should show additional information about the service - appsec, packages, languages, incident management, feature flags and more
• It should show additional information about the ecosystem of the services, such as cloud resource data etc

Commerical internal developer portals such as Port can and do support these functionalities. 

What is an open source service catalog?

For all the reasons above, engineers at Spotify discovered they needed a service catalog, and in a broader sense, an internal developer portal. 

The idea was simple:

Let developers self-serve and at the same time ensure golden paths and guardrails. At the center was a service catalog. In 2020 backstage was accepted into the cncf, and today it is one of the most popular projects there. 

Backstage states that its service catalog (which it calls “software catalog”) serves two benefits:

• Discoverability since the catalogs “sees” everything in the SDLC; and 
• Helping teams manage all their services as a result of being able to see everything in one place: APIs, services, resources, packages and more

To build the service catalog, Backstage uses a data model and ingests data from integrations, serving as a central metadata store about everything in the SDLC.

Another open source service catalog is meshery, but the dominant one is backstage, which is a fully fledged internal developer portal. 

As with all things open source, backstage is really a platform to build internal developer portals. It requires quite a lot of work and isn’t simple to implement, requiring extensive coding. However, the ideas surrounding it helped create the huge interest in platform engineering and internal developer portals, all beginning with a service catalog.