stevefeldman/backstage

Backstage Catalog Configuration

Overview

Generate catalog-info.yaml files that register services, APIs, and resources in Backstage's software catalog. This skill provides organization-specific patterns and required annotations.

When to Use

• Creating a new repository that needs Backstage registration
• Adding catalog-info.yaml to an existing repo
• Updating service metadata, dependencies, or ownership
• Connecting APIs, databases, or external resources

Quick Reference

| Component Type | spec.type | Use For | |----------------|-------------|---------| | Backend service | service | APIs, microservices | | Frontend app | website | MFEs, SPAs, web apps | | Shared code | library | npm packages, shared modules |

| Lifecycle | When to Use | |-----------|-------------| | experimental | In development, not production-ready | | production | Live, actively maintained | | deprecated | Being phased out |

Core Template

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: your-service-name
  description: Brief description of what this service does
  tags:
    - api  # or: oc, mfe, library
  annotations:
    # Required annotations
    backstage.io/kubernetes-id: your-service-name
    backstage.io/kubernetes-namespace: your-namespace
    sonarqube.org/project-key: your-service-name
    jenkins.io/job-full-name: digital:org/your-service-name
    backstage.io/techdocs-ref: dir:.
    opsgenie.com/component-selector: 'tag:"app:your-service-name"'
    opsgenie.com/team: 'Digital Developers'
    github.com/project-slug: org/your-service-name
  links:
    - title: QA Logs
      icon: ManageSearch
      url: https://splunk.example.com/en-US/app/search/search?q=search%20index%3D%22gke_staging_logs%22%20cluster_name%3A%3Astaging-digital%20namespace%3D%22YOUR_NAMESPACE%22%20pod%3D%22develop-YOUR_SERVICE-*%22
    - title: UAT Logs
      icon: ManageSearch
      url: https://splunk.example.com/en-US/app/search/search?q=search%20index%3D%22gke_staging_logs%22%20cluster_name%3A%3Astaging-digital%20namespace%3D%22YOUR_NAMESPACE%22%20pod%3D%22YOUR_SERVICE-*%22
    - title: Production Logs
      icon: ManageSearch
      url: https://splunk.example.com/en-US/app/search/search?q=search%20index%3D%22gke_logs%22%20cluster_name%3A%3Aproduction-digital%20namespace%3D%22YOUR_NAMESPACE%22%20pod%3D%22YOUR_SERVICE-*%22
    - title: Service Restart - QA
      icon: RestartAlt
      url: https://admin.staging.example.com/jenkins/job/org/job/job-deployment-restart/job/master/parambuild/?environment=Staging&namespace=YOUR_NAMESPACE&deploymentName=develop-YOUR_SERVICE&clusterType=mos
    - title: Service Restart - UAT
      icon: RestartAlt
      url: https://admin.staging.example.com/jenkins/job/org/job/job-deployment-restart/job/master/parambuild/?environment=Staging&namespace=YOUR_NAMESPACE&deploymentName=YOUR_SERVICE&clusterType=mos
    - title: Service Restart - Prod
      icon: RestartAlt
      url: https://admin.staging.example.com/jenkins/job/org/job/job-deployment-restart/job/master/parambuild/?environment=Production&namespace=YOUR_NAMESPACE&deploymentName=YOUR_SERVICE&clusterType=mos

spec:
  type: service  # or: website, library
  lifecycle: production
  owner: group:default/YOUR_TEAM

  # For services that provide APIs
  providesApis:
    - your-api-name

  # Dependencies on other components/resources
  dependsOn:
    - resource:default/your-database-resource
    - component:default/another-service

Adding an API Definition

For services that expose APIs, add a second document:

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: your-api-name
spec:
  type: openapi
  lifecycle: production
  owner: group:default/YOUR_TEAM
  definition:
    $text: https://api-internal.staging.example.com/YOUR_NAMESPACE/develop-YOUR_SERVICE/swagger-ui/swagger.json

Team Ownership

Format: group:default/team-name

Common teams:

• group:default/upfunnel - Product discovery, search, categories
• Check existing catalog for other team references

Common Annotations

| Annotation | Purpose | |------------|---------| | backstage.io/kubernetes-id | Links to K8s deployment | | backstage.io/kubernetes-namespace | K8s namespace | | sonarqube.org/project-key | SonarQube code quality | | jenkins.io/job-full-name | Jenkins pipeline path | | backstage.io/techdocs-ref | TechDocs location (usually dir:.) | | opsgenie.com/component-selector | OpsGenie alert routing | | opsgenie.com/team | OpsGenie team | | github.com/project-slug | GitHub repo reference | | backstage.io/source-location | Source code URL (for non-K8s components) |

Link Icons

| Icon | Use For | |------|---------| | ManageSearch | Log viewers (Splunk) | | RestartAlt | Service restart actions | | DataThresholding | Grafana dashboards | | OpenInBrowserIcon | External URLs, registries |

OpenComponent (OC) Pattern

For OpenComponent libraries (not deployed to K8s):

metadata:
  tags:
    - oc
  annotations:
    # NO kubernetes-id or kubernetes-namespace
    sonarqube.org/project-key: your-component
    backstage.io/source-location: url:https://github.com/org/your-component
  links:
    - title: QA OpenComponent Registry
      url: https://qa.example.com/registry/your-component/X.X.X/~info
      icon: OpenInBrowserIcon
spec:
  type: website
  # NO providesApis for OC components

MFE (Micro-Frontend) Pattern

metadata:
  annotations:
    backstage.io/kubernetes-id: your-mfe
    # Often NO kubernetes-namespace for MFEs
  links:
    - title: Production grafana mfe dashboard
      url: https://grafana.example.com/d/iquxNcS4k/mfe-dashboard?var-app=your-mfe
      icon: DataThresholding
spec:
  type: website
  dependsOn:
    - component:backend-service-it-calls

Common Mistakes

| Mistake | Fix | |---------|-----| | Missing owner | Always specify group:default/team-name | | Wrong spec.type | Use service for APIs, website for frontends | | Hardcoded URLs | Use URL-encoded parameters in Splunk links | | Missing namespace in links | QA uses develop-*, UAT/Prod use service name directly | | Duplicate links | Review for accidental copy-paste duplication |

Validation

Place catalog-info.yaml in repository root. Backstage will auto-discover and validate on commit.