Service Catalog: The Organization's Inventory
A Service Catalog is the centralized, authoritative registry of all services, components, and software resources in an organization. It represents the "map" of the company's technology landscape: who owns what, how services are interconnected, what SLAs are guaranteed, and what the health status of each component is.
Without a service catalog, growing organizations suffer from shadow IT: services nobody knows exist, undocumented dependencies, ambiguous ownership, and incidents that take hours to resolve because nobody knows who to contact. The service catalog solves these problems by providing a single source of truth for the entire software ecosystem.
What You'll Learn
- How to model a service catalog: entities, relationships, metadata
- Service ownership: teams, on-call, escalation paths
- SLA tracking: RTO, RPO, availability targets, and compliance
- CMDB (Configuration Management Database): configuration items and change tracking
- Dependency mapping: dependency graphs and impact analysis
- Auto-discovery: automated catalog population
Modeling the Service Catalog
An effective service catalog is built on a well-designed data model that captures essential information about every component in the ecosystem. The main entities are:
- Service: a microservice, application, or system performing a business function
- API: an interface exposed or consumed by a service (REST, gRPC, GraphQL, Kafka events)
- Resource: an infrastructure resource (database, cache, message queue, storage)
- Library: a shared library used by multiple services
- Team: the group responsible for maintaining and operating one or more services
# Service Catalog: data model for a service
service:
metadata:
name: checkout-service
display_name: "Checkout Service"
description: "Manages checkout flow and payments"
created_at: "2024-03-15"
last_updated: "2026-01-20"
classification:
type: microservice
tier: tier-1 # Business-critical
lifecycle: production # development | staging | production | deprecated
domain: e-commerce
subdomain: payments
ownership:
team: team-checkout
team_lead: "mario.rossi"
product_owner: "anna.bianchi"
on_call:
primary: "checkout-oncall-primary"
secondary: "checkout-oncall-secondary"
escalation: "engineering-manager"
slack_channel: "#team-checkout"
email: "team-checkout@company.io"
technical:
language: TypeScript
framework: NestJS
runtime: Node.js 20
repository: "github.com/company/checkout-service"
ci_cd: GitHub Actions
deployment: ArgoCD
container_image: "ghcr.io/company/checkout-service"
infrastructure:
kubernetes:
cluster: production-eu
namespace: checkout
replicas: 3
database:
type: PostgreSQL
instance: "checkout-db-prod"
version: "15.4"
cache:
type: Redis
instance: "checkout-redis-prod"
sla:
availability: "99.95%"
rto: "15 minutes" # Recovery Time Objective
rpo: "5 minutes" # Recovery Point Objective
response_time_p99: "200ms"
throughput: "1000 rps"
dependencies:
provides:
- api: checkout-api
type: REST
docs: "https://docs.company.io/checkout-api"
consumes:
- service: payment-gateway
api: payment-api
criticality: hard
- service: inventory-service
api: inventory-api
criticality: soft
- service: notification-service
api: notification-api
criticality: soft
Service Ownership and Accountability
Service ownership is one of the most important concepts in the service catalog. Every service must have a clearly identified team as its owner, with defined responsibilities for development, maintenance, on-call, and incident response.
The principles of effective ownership are:
- Clear ownership: every service has exactly one team owner. No service is "orphaned"
- Full lifecycle: the owner team is responsible from design to decommissioning
- On-call rotation: every team has a defined on-call rotation with clear escalation paths
- Knowledge sharing: documentation is up-to-date and accessible, reducing the bus factor
The Orphaned Services Problem
30-40% of services in medium-sized organizations do not have a clearly identified owner. These orphaned services are one of the main causes of prolonged incidents: when something goes wrong, nobody knows who to contact or how to intervene. The service catalog eliminates this problem by making ownership explicit and visible.
CMDB: Configuration Management Database
The CMDB (Configuration Management Database) is a service catalog component that tracks Configuration Items (CI): every resource, configuration, and relationship that makes up the IT infrastructure. While the service catalog focuses on business information (ownership, SLAs, dependencies), the CMDB provides a detailed view of technical configuration.
- Configuration Items: servers, containers, databases, load balancers, certificates, DNS records
- Relationships: "runs-on", "depends-on", "connected-to" between configuration items
- Change tracking: history of all changes to each CI, with who, when, and why
- Compliance: verification that CIs comply with organizational policies (versions, patches, configurations)
# CMDB: Configuration Items and relationships
configuration_items:
- id: ci-checkout-pod-01
type: kubernetes_pod
name: "checkout-service-7d8f9b6c4d-xk2mn"
status: running
properties:
image: "ghcr.io/company/checkout:v2.3.1"
cpu_request: "500m"
memory_request: "512Mi"
node: "worker-node-03"
relationships:
- type: runs-in
target: ci-checkout-namespace
- type: connects-to
target: ci-checkout-db
- type: connects-to
target: ci-checkout-redis
- id: ci-checkout-db
type: rds_instance
name: "checkout-db-prod"
status: available
properties:
engine: "postgres 15.4"
instance_class: "db.r6g.large"
storage: "50GB"
encrypted: true
multi_az: true
backup_retention: 30
relationships:
- type: used-by
target: ci-checkout-pod-01
- type: backed-up-to
target: ci-checkout-db-snapshots
- id: ci-checkout-redis
type: elasticache_cluster
name: "checkout-redis-prod"
status: available
properties:
engine: "redis 7.0"
node_type: "cache.r6g.large"
encryption_at_rest: true
encryption_in_transit: true
change_history:
- ci_id: ci-checkout-db
timestamp: "2026-01-15T14:30:00Z"
change_type: "configuration_update"
description: "Upgraded from db.r6g.medium to db.r6g.large"
performed_by: "platform-team"
ticket: "INFRA-4521"
approved_by: "tech-lead"
Dependency Mapping and Impact Analysis
One of the most valuable features of the service catalog is the ability to map dependencies between services and perform impact analysis. When a service has an issue, the dependency map allows immediately understanding which other services are impacted and notifying the responsible teams.
- Hard dependencies: the service cannot function without this dependency (e.g., database)
- Soft dependencies: the service operates in degraded mode without this dependency (e.g., notification service)
- Upstream dependencies: services I depend on
- Downstream dependencies: services that depend on me
Impact analysis is particularly useful during change windows: before performing maintenance on a component, the team can verify the impact across the entire ecosystem and plan the necessary notifications and rollbacks.
Auto-Discovery and Synchronization
A service catalog that requires manual updates quickly becomes obsolete. For this reason, modern IDPs implement auto-discovery mechanisms that automatically populate and update the catalog:
- Kubernetes discovery: scanning namespaces and deployments to identify active services
- GitHub/GitLab discovery: scanning repositories for catalog-info.yaml files
- Cloud provider discovery: querying cloud APIs to inventory resources (RDS, S3, Lambda)
- Network discovery: analyzing network traffic to identify undocumented dependencies
# Auto-discovery: Backstage entity provider configuration
catalog:
providers:
# GitHub discovery: search catalog-info.yaml in all repos
github:
company:
organization: "company"
catalogPath: "/catalog-info.yaml"
filters:
branch: "main"
repository: ".*" # All repositories
schedule:
frequency: { minutes: 30 }
timeout: { minutes: 3 }
# Kubernetes discovery: import workloads as entities
kubernetes:
production:
cluster: production-eu
processor:
namespaceOverride: false
defaultOwner: platform-team
schedule:
frequency: { minutes: 15 }
# AWS discovery: import cloud resources
awsS3:
production:
region: eu-west-1
schedule:
frequency: { hours: 1 }
rules:
- allow:
- Component
- API
- Resource
- System
- Domain
- Group
- User
Service Catalog Best Practice
The service catalog must be the single source of truth for all service information in the organization. Every tool (monitoring, incident management, CI/CD) should read information from the catalog instead of maintaining separate copies. This eliminates duplication and ensures data consistency.
Governance and Audit
The service catalog is a fundamental component for the organization's IT governance. It enables implementing:
- Compliance checks: verify all services comply with organizational policies (defined SLAs, assigned owner, documentation present)
- Security reviews: identify services with vulnerable dependencies, insecure configurations, or expiring certificates
- Cost allocation: associate infrastructure costs to teams and services for complete visibility
- Audit trails: maintain a complete history of all changes to services and configurations
A well-managed service catalog transforms governance from a bureaucratic, reactive process into an automated, proactive system that ensures continuous compliance without slowing down development.