Gnu Group Learning AcademyGnu Group ↗
Platform Engineering Fundamentals · Module 03 of 12

Software catalog, ownership and documentation

Use a software catalog to make services, owners, systems, APIs and documentation discoverable, and treat metadata quality as an operational control rather than decorative inventory.

Learning objectives

By the end of this module, you should be able to:

  • Explain the operational value of service ownership metadata.
  • Model a minimal catalog entity and relations.
  • Connect documentation and runbooks to the service lifecycle.

Catalogs answer operational questions

A catalog should help answer: what is this component, who owns it, what system is it part of, where is its documentation, and what does it depend on? Metadata that cannot support a decision is just inventory.

Ownership is a control

Alerts, vulnerabilities, costs and incidents are harder to act on when ownership is absent or stale. Ownership metadata should have a source of truth and a maintenance path.

Docs like code

Documentation should evolve with the service and be easy to discover from the same entity context. Backstage TechDocs is one implementation of this docs-like-code model.

Worked example

Minimal catalog entity

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
spec:
  type: service
  lifecycle: production
  owner: group:payments
  • Backstage uses catalog entities to model software and ownership.
  • A production platform should also define system/domain relationships and documentation where useful.
Core lab · account-free

Lab 03 — Audit catalog metadata

Goal: Detect missing ownership and documentation metadata in a synthetic catalog.

Before you start

  • No cloud account required.
  • Core lab uses bash/Python 3 and local files only.
STEP 1

Create catalog records

cat > /tmp/catalog.json <<'EOF'
[{"name":"orders-api","owner":"payments","docs":"docs/orders","tier":"1"},{"name":"legacy-worker","owner":"","docs":"","tier":"2"}]
EOF
STEP 2

Audit gaps

python3 - <<'PY2'
import json
rows=json.load(open('/tmp/catalog.json'))
for r in rows:
 gaps=[k for k in ('owner','docs') if not r.get(k)]
 print(r['name'], 'OK' if not gaps else 'MISSING '+','.join(gaps))
assert any(not r['owner'] for r in rows)
PY2
STEP 3

Define remediation

For each missing field, identify the team/process that should maintain it rather than patching it manually once.

Verify

  • The audit identifies the intentionally unowned component.
  • Remediation includes a source-of-truth/process owner.

Expected outcome

  • A small metadata quality report.

Diagnose / troubleshoot

  • If every record is “owned by platform,” challenge whether application ownership is being obscured.
  • If catalog data is duplicated manually, identify the authoritative source and ingestion path.
Real-world connection

Catalog metadata becomes valuable when it routes operational work to the right team and links developers to current documentation.

Real-tool practicum · optional but recommended

Optional tool lab — Backstage catalog concepts

Create a disposable catalog-info.yaml and inspect it before importing to any Backstage sandbox.

Prerequisites

  • Use a disposable local lab or organization-approved sandbox.
  • Pin tool versions in real platform automation; do not blindly depend on latest.

Cost / risk

  • Core learning is account-free. Optional external/sandbox tools may consume local CPU/RAM; do not use production credentials or billable cloud resources.

Warnings

  • Use a disposable Backstage sandbox for imports.
  • Catalog metadata is not authorization by itself; do not confuse discovery metadata with access control.
TOOL 1
cat > /tmp/catalog-info.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: demo-service
spec:
  type: service
  lifecycle: experimental
  owner: group:demo
EOF
cat /tmp/catalog-info.yaml
Avoid these traps

Common mistakes

  • Treating the catalog as a manually maintained spreadsheet.
  • Making the platform team owner of every application.
  • Publishing documentation without a lifecycle or ownership model.
Knowledge check

Can you connect the developer need to a platform contract?

Three concept checks plus one scenario check.

1What operational question should a catalog answer?

What is this component, who owns it, what is it related to and where is its documentation/evidence?

2Why is ownership metadata important?

It routes incidents, vulnerabilities, costs and change decisions to an accountable team.

3What does docs-as-code improve?

Documentation can evolve with reviewed service changes and remain discoverable with the component.

4Scenario: an alert fires for a service with no owner in the catalog. What is the platform issue?

Metadata quality/ownership governance has failed; the platform cannot reliably route operational responsibility.

My Learning

Record your progress for this module.

Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.

Not started

Attempt the core lab and knowledge checks before marking the module complete.