⚡ Tl;dr
- A microservice catalog is a central repository that is the source of truth for all entities in your software architecture and the relationships between them.
- Microservice catalogs give teams visibility into services so they can reuse existing functionality and ensure changes are compatible with the wider ecosystem.
- Microservice catalogs store information such as name, description, owner, on-call, dependencies, runtime, packages, API specs, environment and links.
🚀 Let’s kick-off
In recent years, many engineering teams have transitioned to microservice architectures, and there’s no doubt it has provided many benefits, such as stability and re-usability. As architectures reach hundreds and even thousands of microservices distributed across many teams, keeping track of what exists and who the point of contact is becomes a challenge.
This is where microservice catalogs can help; let’s jump right into it.
❓ What is a microservice catalog?
A microservice or service catalog is a central, up-to-date repository that lists your software architecture’s microservices. It is the source of truth for all entities in your software system and the relationships between them.
The goal is to give teams and individuals visibility into the services available so they can properly reuse existing functionality and ensure their changes are compatible with the wider ecosystem. A simple user interface makes it easy for developers to discover the information they need to introduce new services, change existing ones and deprecate old ones.
Microservice catalogs help distribute previously tribal knowledge across teams and departments to ensure everyone is on the same page working in the ecosystem.
📦 What information should catalogs store?
Name and description to identify the service and provide a high-level summary for anyone who is not familiar with the purpose and responsibility of the service.
Owning team or individual for anyone who needs to contact the person responsible for a specific microservice so they can ask a question or request changes.
On-call team members in case an incident occurs that is caused by or affects a given microservice in which only specific team members have domain expertise.
Dependencies for visibility into other services needed to function or services that may rely on this. Seeing dependencies makes it possible to see how much impact making a change may have on other parts of the architecture.
Runtime and packages to give an overview of what technologies are being used in this microservice and can provide insights into issues caused by specific technologies.
Tags or labels allow the service to be discovered when filtering the list to a smaller subset. For example, each service could be tagged with its version numberer or risk level.
API specifications such as OpenAPI or Protocol Buffers give insight into how to integrate with the service and allow the generation of client-side libraries for communication.
Deployment status for visibility on which environments the service has been deployed into, such as the testing, staging or production environment. This helps developers know if a service is ready to be depended upon.
External links to source control, CI/CD pipelines, documentation, cloud platforms or live websites. A great resource to allow developers to quickly jump to other places where the microservice exists or is referenced.
🏢 Service catalogs for enterprise architectures
While a microservice catalog may be great for most organizations looking to keep track of their services, it may not be broad enough for larger enterprises with a complex landscape.
A typical enterprise architecture often contains legacy services, monoliths, deprecated technologies and other components that don’t fit into the bracket of a microservice. For these situations, a more flexible tool that can represent a wide range of IT assets and service types would be more suitable.
🧰 Top tools for microservice catalogs
Microservice catalog tooling is still relatively new but is becoming more popular for teams adopting microservice architectures. We’ve collated three tools to try out in your team.
1️⃣ Backstage.io
Backstage is an open-source platform from Spotify for maintaining your software catalog through source control and exposing it through a unified developer portal. Backstage supports various projects, such as microservices, libraries, data pipelines, websites, and ML models. It provides templates for quickly creating new services with standardized tooling and frameworks.
2️⃣ Cortex.io
Cortex is a service catalog for helping teams track their microservice ecosystem. Catalogs can be created through the user interface or source control using a YAML entity description. The cortex software catalog tightly integrates with its ecosystem to provide project scaffolding, team tracking and integrations with 3rd party tools.
3️⃣ OpsLevel.com
OpsLevel detects services from various 3rd party integrations and lists them in a centralized and up-to-date view. It surfaces markdown documentation in the repository to give your team instant context and details about each service. OpsLevel integrates with other services, such as incident management tools, to provide deeper insight into what is happening right now in your software architecture.
🏁 To wrap up
As organizations move to microservice architectures, catalog tools will become essential for tracking hundreds of services and other entities in the software architecture. The data queried from these tools gives teams insights into their architecture and helps them make changes safely, aligning them on common goals across services and teams.
Let us know if you’ve found other tooling for microservice catalogs that we should include on this list!
Stay chill 🧊