Service Catalog on Backstage: Automate & Implement

Note: when a company operates more than 20 services, a quiet catastrophe begins: no one knows the microservice owner, where its documentation is, which services it connects to, or the deployment status. A new developer spends their first week just trying to understand what's deployed in the cluster. We implement Service Catalog to stop this chaos. Our experience shows: within 1–2 weeks you can have a working catalog that pays off by reducing incident time by 30% and accelerating newcomer onboarding to 2 days. The savings from implementation reach tens of thousands of dollars annually.

Service Catalog is a registry of all internal services, components, APIs, libraries, and teams with machine-readable metadata and live state data. Instead of keeping the cluster architecture in engineers' heads, you get a single source of truth that updates automatically. We use Backstage — the only mature open-source option for enterprise service catalogs, actively supported by CNCF.

Why does the crisis hit without a catalog?

In companies without a catalog, infrastructure knowledge is scattered chaotically: someone remembers service X because they wrote it three years ago. Someone knows a specific library version is used in production because they were involved in an incident. A new DevOps engineer can't answer "how many services use Redis?" without manually grepping repositories. In an incident, this becomes critical: payments-service goes down, you need to determine on-call, dependencies, and runbook. Without a unified registry, response time increases — people frantically ping colleagues in Slack. Our Service Catalog cuts this down to a few clicks.

How Backstage solves the "knowledge in heads" problem?

Backstage is written in TypeScript, has a huge plugin ecosystem, and deploys 5x faster than homemade solutions. The central entity is catalog-info.yaml next to the service code. Backstage scans repositories and builds a dependency graph from these files:

Backstage reads this file, registers the service, and automatically builds a dependency graph. On the order-service page you see: owner, on-call, Kubernetes status (pods running/failed), latest commits from GitLab, Grafana dashboard, documentation.

What do we actually build in the catalog?

Component inventory. Every service, library, database, queue — everything becomes an entity with a type (service, library, database, queue, api). For existing repositories, we use Backstage entity providers — GitHub Discovery, GitLab Discovery automatically scan groups and create records.

Dependency graph. Backstage builds a visual dependency graph based on dependsOn and consumesApis/providesApis. This is the first tool showing blast radius: if inventory-service goes down, which services are affected.

Ownership and teams. Backstage supports Group and User entities, syncing from LDAP, Okta, GitHub Teams. Each component has an owner — a team or engineer. During an incident, you immediately see who is responsible.

API catalog. For REST APIs — OpenAPI spec directly in Backstage with a UI for browsing. Developers find needed APIs without trudging through Confluence. Backstage supports OpenAPI, AsyncAPI (for Kafka/event-driven), GraphQL schema.

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api-v2
  description: REST API for order management
spec:
  type: openapi
  lifecycle: production
  owner: group:order-team
  definition:
    $text: https://gitlab.company.com/backend/order-service/-/raw/main/openapi.yaml
---

TechDocs: documentation next to code

Backstage TechDocs — MkDocs built into the catalog. Developers write docs/ next to the code, Backstage renders them on the component page. Documentation is versioned with code and always up to date.

---
# mkdocs.yml in repository root
site_name: Order Service
nav:
  - Overview: index.md
  - Architecture: architecture.md
  - API: api.md
  - Runbook: runbook.md
  - ADR: adr/
---

This solves the problem of outdated Confluence documentation: if code changes, the developer updates docs in the same PR.

Step-by-step Service Catalog implementation plan

We perform the work in several stages, guaranteeing results within a week:

1. Installation and integration. We set up Backstage, authentication (Okta/GitHub SSO), connect GitLab/GitHub for automatic repository scanning. First week.
2. Key plugins. We add Kubernetes (pod status), Grafana (dashboards), PagerDuty (on-call). The team gets immediate value. Second week.
3. Catalog population. We add catalog-info.yaml to existing repositories. Create Group and User entities. Describe the dependency graph, add API entities. Third to fourth week.
4. CI validation. We check catalog-info.yaml in the pipeline via Backstage CLI — if the file is invalid, the PR is not merged. This prevents catalog degradation.

# .gitlab-ci.yml — catalog-info.yaml validation
validate-catalog:
  image: node:18
  script:
    - npx @backstage/cli catalog validate --config catalog-info.yaml
  only:
    changes:
      - catalog-info.yaml

What's included in the work?

• Deploy Backstage on Kubernetes (Helm chart) with redundancy.
• Integrate with GitLab/GitHub, PagerDuty, Grafana, Prometheus.
• Create templates for catalog-info.yaml and ADR documentation.
• Train the team (1–2 workshops) and write a runbook.
• Support during the population phase: help with metadata filling.

Solution comparison: Backstage vs homemade catalog

Backstage outperforms homemade solutions by 5x in deployment speed and has a ready ecosystem for managing APIs, documentation, and dependencies.

Why catalogs degrade and how to prevent it?

Without two things, a Service Catalog turns into a "YAML graveyard": a platform owner ensuring freshness, and a requirement to register new services before deployment. We embed a quality gate in CI: if a component is not registered in Backstage, deployment to staging is blocked. Strict but effective. Additionally, we set up automatic checks for outdated metadata and run regular audits.

For over 5 years, we have been implementing DevOps solutions, completing 50+ infrastructure management projects. Our certified engineers guarantee that the catalog will be a living tool, not a static showcase. Contact us to get a consultation on catalog implementation. We will assess your project in 1 day — just specify the number of services and current tools, and we will propose an implementation plan.