Service catalog - define entity kinds and annotation standards

[miacycle]

Before we populate the catalog, we need to agree on what kinds we'll use and what annotations are mandatory.

Proposed entity kinds:

• Component - deployable services and libraries
• API - machine-readable API specs (OpenAPI, AsyncAPI, gRPC)
• Resource - managed infrastructure (RDS, S3, queues)
• System - logical grouping of related components
• Domain - business domain grouping
• User / Group - team structure

Mandatory annotations for Component:

metadata:
  annotations:
    github.com/project-slug: org/repo
    backstage.io/techdocs-ref: dir:.
    tcs.io/team: platform
    tcs.io/tier: 'tier-1'  # tier-1, tier-2, tier-3
    tcs.io/language: typescript

Looking for input on the tier system and any missing required annotations.

[arjunmehta-git]

The tier annotation is important - tier-1 services need SLOs and on-call, tier-2 are best-effort, tier-3 are deprecated. Let's add tcs.io/lifecycle: production | development | deprecated | experimental to capture that more explicitly.

[pontusringblom]

For APIs: should the API entity include the actual spec inline or just a reference? Inline bloats the catalog YAML. A backstage.io/definition-at annotation pointing to the OpenAPI file in the repo seems cleaner.

[winkletinkle]

Agreed on reference not inline. Also - tcs.io/oncall annotation pointing to a PD schedule or OpsGenie team slug would let the catalog be the single source of truth for who's on call without needing the plugin per se.