Top examples of service catalogs in action

What are service catalogs?

Service catalogs are a core element of platform engineering, and are an important part of an internal developer portal. They are a central metadata store for everything microservice and application-related in your engineering, from CI/CD metadata through cloud resources, Kubernetes, AppSec, cost and more.

As opposed to old ‘service catalogs’ which dealt with IT or business services made available in an enterprise (such as CMDBs), modern service catalogs are there to help dealing with the complexity in modern development environments brought about by cloud-native technologies. 

This modern form of service catalogs are gaining traction; indeed, in Viktor Farcic’s ‘best DevOps tools for 2024’, service catalogs was listed as the top category of tool with the open-source Backstage and Port mentioned as top service catalog options.

In one example of complexity; the sheer number of microservices, each possibly managed by different teams, adds to the operational complexity, making it difficult to understand even basic elements such as service ownership, who is on-call and dependencies. Things get more complex when context is added: which services are mission critical and need to comply with stringent AppSec requirements? Where are they running and what are the costs associated with them? 

On top of this, developers are faced with more responsibilities - going beyond coding. Now, they must also handle the deployment, operation, and sometimes the entire lifecycle management of software. 

The catalog addresses this complexity and increased responsibility by serving as a centralized interface containing comprehensive information about microservices, including ownership and dependencies. This high-level overview, which presents microservices in a consistent format, allows developers to monitor all of their services and efficiently scale their operations.

Benefits of service catalogs

Without a functioning service catalog, the developer experience suffers since the data is hidden, stale or requires tapping into tribal knowledge that isn’t documented anywhere. Answering simple information questions becomes too difficult. The knock-on effect is a reduction in developer productivity, as well as job satisfaction, and the overall efficiency of the software development lifecycle. 

A service catalog can help to improve the developer experience in several ways:

• Finding the information they need; service catalogs provide a centralized repository for all data related to microservices and the infrastructure they run on, including dependencies, packages, APIs, relevant AppSec, cost data and more. Service catalogs are updated automatically and in real time, eliminating the need for manually maintained spreadsheets or Jira data, CMDBs that serve as a service catalog or the use of plain old tribal knowledge.

• Reducing tedious, manual work: by automating the cataloging of microservices, service catalogs eliminate the mundane and repetitive task of manually updating data related to application security, feature flags, in order to identify issues and maintain software quality standards. This automation ensures that information is updated in real-time, enhancing efficiency. 

• Improving usability: Service catalogs show microservice data in context - which services run on which infrastructure, dependencies etc. This saves time as developers do not have to switch between various interfaces with differing data about microservices and their infrastructure, causing confusion. Service catalogs provide a unified interface, streamlining access to necessary information and tools. 

• Enhancing InnerSource practices: By providing a structured and accessible way to share internal services, tools and resources, a service catalog can play a big part in the adoption of InnerSource practices. Libertex Group used Port’s software catalog to facilitate easier sharing and collaboration across development teams. 

Examples of service catalogs in action

Discoverability and context 

Maintaining a service catalog that reflects everything in real time is critical for many enterprises, but as the amount of information in an organization grows, and changes become more frequent, it becomes impossible for staff to manually keep the data accurate.

Take TransferGo, for example. Developers had been using spreadsheets to manually record all information about microservices and other platform elements. The software engineering team had tried using tags to identify the ownership of specific assets or initiatives. However, this tedious process lacked standardization because users used the tags in different ways, and therefore made it more difficult to establish a reliable single source of truth. In fact, the spreadsheet method failed to effectively identify resources, or owners and ended up increasing the cognitive burden on developers, negatively affecting their experience. Without real-time data and context, answering important questions and ensuring ownership and accountability became nearly impossible. 

The company used Port’s software catalog (what we call our service catalog) as a central metadata store for everything application-related, enabling the company to answer critical questions (eg. What is the version of the checkout service in staging vs production?). For TransferGo, the big improvement was the ability to automatically add AppSec data to the portal, saving labor and allowing the organization to act in real time upon any changes in the AppSec status of certain service catalog software entities (more on this below). 

Real time service catalogs create trusted data 

Trust in the service catalog is a big, often overlooked, issue when the data isn’t up-to-date.

As Libertex Group’s head of enterprise architecture, Alexander Bukarev, explained, the company needs the catalog to automatically ingest data and update itself.

“It’s mandatory to have a simple API but also some ready-to-use plugins. Otherwise, the data becomes inaccurate in just a few days or weeks and then nobody trusts this data or uses the system that retains the data because everyone assumes it’s out-of-date, so we wanted to fundamentally solve this issue,” said Bukarev.
With Port’s software catalog, the data is continuously updated and enriched. This helps developers answer critical questions such as ‘what is the version of this service in staging vs production?’.

AppSec

Without a service catalog, it is difficult to tie AppSec vulnerabilities to specific services and almost impossible to understand the data in context. Without context it is difficult to prioritize the AppSec vulnerabilities that require team attention.

For example, when TransferGo was using spreadsheets, it was difficult to tell the AppSec status of services, without considerable manual work. To keep it updated, the team required multiple developers and team leads to update it, affecting developer productivity and satisfaction. 
By mapping vulnerabilities and misconfigurations to microservices within the software catalog, TransferGo’s developers could better understand the severity of a vulnerability and its context. This lets them prioritize remediation accordingly. In addition, developers can understand whether a vulnerability is in production or not, as well as the relevant data about the application, in one place, and in context. 

With everything in one place, the team can easily communicate AppSec standards/posture and drive change. 

Costs

Many engineering organizations struggle to optimize the cost of their applications because of a lack of context (despite investing in cloud cost tracking and optimization tools). Developers do not have the visibility into the many resources that comprise a single service, so they can’t understand how much a service costs, and can therefore do little to optimize a service’s cloud costs. Meanwhile engineering team leads are unable to determine which team owns a resource, FinOps can’t track which resources are aligned to which services, and tech leads are unable to see how much a namespace costs.

By incorporating cost data into Port’s software catalog, you can align specific data to teams, services, and domains, giving developers, managers and FinOps teams a common operating picture to optimize the cost of a service (not just the resources that serve it).

Developing a new service

The service catalog can be used to keep up to date with new services and to drive the development of new services through self-service actions. Naveh Katz, director of cloud operations at cyber security company Cybersixgill explained that the service catalog the organization had been using (which was in a wiki), made it difficult for developers to get all of the data they needed for developing a new service. This data came  from a variety of sources (Kubernetes, Bitbucket, ArgoCD, Kafka, Terraform, Jira). This meant developers couldn’t understand the relationship between services that interacted and their availability.

“We used to manage it manually, running a script every few months to update it but if someone added a new service and forgot to update it in the service catalog we didn’t know,” Katz said.

Using Port’s software catalog, Cybersixgill’s developers can get all of the up-to-date data from all of the relevant sources in the portal, in one place.

“Now it’s all dynamic, it’s automatic, so it’s very easy for developers to look for a specific service,” said Katz.

Managing technical documentation

Technical documentation is often spread across an organization’s systems and applications. It is also often out-of-date, in varying formats, and is difficult to find.

Libertex Group is planning to use Port’s software catalog to make documentation easier to find, access, store and use. In addition, the team will use scorecards to ensure documentation standards are maintained. 

Customizing views

Customizing views of the catalog for different teams makes the catalog far more user-friendly. TransferGo used Port’s dashboards to customize its software catalog for engineers, developer experience personnel, managers, directors and the SRE team, as they all require different information. This delivers the next step of creating service catalogs: using them to abstract the right information rather than just dumping a lot of raw data onto developers, which can increase their cognitive load rather than decrease it.

Key takeaways

In conclusion, modern service catalogs have become essential in platform engineering. They have transformed from traditional IT catalogs into dynamic repositories for managing the complexity of contemporary development environments. These catalogs enhance the developer experience by centralizing metadata, automating updates, and providing a comprehensive view of microservices and infrastructure.

By addressing operational challenges such as service ownership, dependencies, and compliance, service catalogs improve productivity and satisfaction. They also optimize resource costs, support the development of new services through self-service capabilities, and aid in AppSec management by contextualizing vulnerabilities.

Real-world examples from TransferGo, Libertex Group, and Cybersixgill demonstrate the benefits of a service catalog within an internal developer portal. Service catalogs are now indispensable tools, driving efficiency in modern software development.