Service catalog: what is it, benefits, components

What is a service catalog?

For many years, a service catalog was considered a simple inventory with links to various services. But as organizations have evolved, the service catalog is used for so much more; it is a system of record that represents everything software. That means it provides a holistic view of everything related to a service including dependencies, relationships and more. It also serves as the foundation of the internal developer portal, which is the central hub for developers and managers using an internal developer platform. The portal acts as the basis for creating experiences like incident management, cost management, just-in-time permissions and more. 
The service catalog (also called a software catalog) is a system of records, holding information about all of the services which can be used to track metrics, set standards, create dashboards and more. A good catalog provides the basis for a great internal developer portal.

What are the benefits of a service catalog?

To act as a central system of record that provides insights and metrics, the service catalog should contain data from the different tools, systems, infrastructure and processes that make up the software development lifecycle.  Without adding this information, developers have to extract information from various tools - and have knowledge of how best to do that. By adding all this data into the catalog, you’re extracting the information from your siloed platform tools in an abstracted form, enabling richer context and insights.

You choose what data to bring to the portal, and once it’s in, you choose how to slice and dice it per persona. A dev won’t have the same view as a manager and an SRE will also see a completely different view.  In short, the catalog creates an accurate (and therefore trusted) central system of record that then has three key benefits:

1. Context and clarity for developers, so they can complete tasks more efficiently with more informed decision-making (for eg. getting more context around incidents to reduce MTTR).
   
2. Managers gain control and visibility from the added context - for instance around costs and standards for each service. They can also be rest assured that developers have the data they need, adhering to organizational standards and policies.
   
3. VPs can identify gaps and bottlenecks early by pulling together engineering metrics from these different elements in every stage of the development lifecycle. By aggregating this data you can unearth a correlation between issues; for instance a higher deployment frequency and an increase in incidents may signal that the team is prioritizing speed over quality leading to more bugs and errors in production. What’s more, leaders can assess the impact of metrics that aren’t quite right; if a key metric decreases, the catalog can identify which product lines or customers are impacted. 

There are three wider benefits of using a service catalog:

• They enable users to easily discover anything they need about a service, package, workload, cloud resource, API or anything else software
• They reduce the need for manual updates (this is especially true for dynamic data that tends to change often such as AppSec or feature flag or health status of the workloads data)
• They reduce the need to context-switch between different tools since all the information needed is centralized in the catalog. 

What should you be able to see in your service catalog?

In your service catalog, you should be able to see a number of elements. Let’s look at them one-by-one: 

1. Code visibility
   First, you want to see all of your repositories, owners, packages, etc, so you integrate deeply with GitHub, GitLab, or Bitbucket to represent your code.
   
   
2. Security issues that require attention
   By integrating with tools like Snyk, Dependabot, and SonarQube, you can ensure that your code is secure. This makes it easier for developers to follow security standards and address non-compliance.
   
   
3. Runtime information
   After writing the code, you need to ensure it is running somewhere, using Kubernetes, AWS Lambda, ArgoCD or other services. This information about the running service is brought into the service catalog, so that each service can be understood in the context of where it is running.
   
   
4. Images
   Every running service uses images, so the service catalog brings in different images from ECR, GCR, and GitHub Packages, providing a complete view of the images in use.
   
   
5. Container security issues
   Just because your code is secure doesn’t mean that the image built from the code is secure. This is why the catalog integrates with tools like Trivy and Snyk to ensure the images are secure before they are deployed and monitor them afterwards.
   
   
6. Infrastructure security issues
   For example, if there’s a service running on a Kubernetes cluster, you want to ensure it is secure. The catalog integrates with infrastructure security tools like Trivy, Falco, and Kyverno to provide this assurance.
   
   
7. Continuous Integration (CI)
   To create an image, you need to see all the workflows and CI pipelines. Therefore, the catalog integrates with GitHub Actions, GitLab CI, and Jenkins, providing visibility into the image creation process.
   
   
8. Continuous Deployment (CD)
   To deploy the image, you need to integrate with CD tools such as ArgoCD, FluxCD, and GitHub Actions. The catalog gives visibility into deployment information such as status, environment, etc.
   
   
9. CI/CD pipeline security
   It’s also important to ensure that the CI/CD pipelines are secure. The catalog integrates with tools like SBOM Scanners and Trivy to validate the security of your pipelines.
   
   
10. Running service uses cloud resources
    The code that is deployed for the running service often relies on cloud resources. The catalog integrates with RDS, S3, and Kafka to visualize the connection between cloud resources and their workloads.
    
    
11. Cloud resource deployment
    To enable and deploy cloud resources, the service catalog within the portal integrates with Terraform, Pulumi, and Crossplane, meaning you can configure and customize the portal through code. By updating anything in the portal, you can be safe in the knowledge that it is all in the repository, making cloud resource management straightforward.
    
    
12. Cloud costs
    Cloud resources can be costly and challenging to track. The service catalog integrates with tools like OpenCost and Cast AI to provide a cost for each cloud resource. By leveraging graph technology, the catalog can calculate the total service cost and team expenditures, enabling better cost management and resolution.
    
    
13. Cloud resource security
    Ensuring that cloud resources themselves are secure is critical. The catalog integrates with security tools like Wiz and Prisma to maintain cloud resource security.
    
    
14. Feature flags
    Sometimes, you need to expose different features from your code for different users. This is where our integration with LaunchDarkly comes in, allowing for dynamic feature flag management.
    
    
15. Code changes
    When code changes are needed, you can manage them efficiently using Jira Issues and GitHub Pull Requests (PRs), all tracked within the service catalog.
    
    
16. Running service monitoring
    Monitoring the running service is crucial. Tools like Sentry and New Relic enable you to monitor the code in execution, while Datadog helps monitor the overall workload. You can pull in alerts, statuses and graphs from monitoring and observability tools.
    
    
17. Incident management
    For incident management, if you want to connect an incident to teams and services, the catalog integrates with tools like PagerDuty or OpsGenie, ensuring incidents are handled promptly and effectively.
    
    
18. Engineering metrics
    Finally, the catalog allows you to create and track different engineering metrics. For example, calculating MTTR using the PagerDuty integration, deployment frequency by connecting to ArgoCD, and lead time for changes can be tracked using Jira Issues. These integrations enable the calculation of critical engineering metrics, including those from popular frameworks such as DORA.

In essence, the service catalog is not just a glorified spreadsheet or an inventory; it is an essential tool that provides full context, value, and insights across the organization. By integrating with an increasing number of tools and processes throughout every stage of the software development lifecycle, it forms a foundation for a huge number of use cases.

The added context can benefit a number of different personas: developers, managers, SREs and engineering leaders in different ways, but ultimately it will make the SDLC more efficient.  

Further reading: How service catalogs are being used by engineering organizations today as part of their internal developer portals.