Catalog as code with catalog-info.yaml

For administrators, engineers 8 min read

Describe each service in a file in its repository. ELOS reads it on every sync, so the catalog changes through reviewed pull requests.

When source control is connected, every repository becomes a service in ELOS. A catalog-info.yaml file in the repository describes that service: its tier, lifecycle, owner, links and more. The file is the source of truth for every field it sets, and changes to it go through your normal pull-request review.

Add the file

1. Download the template or copy the example below.
2. Save it as catalog-info.yaml at the root of the repository. catalog-info.yml and .elos/catalog.yaml also work.
3. Fill in the fields you want ELOS to take from code. Leave out anything you'd rather manage in ELOS.
4. Merge the pull request. The next sync applies it.

apiVersion: elos/v1
kind: Service
metadata:
  description: Card payment authorisation and capture
  tags: [payments, pci]
  annotations:
    cost-center: CC-4020
spec:
  type: service
  tier: tier-1
  lifecycle: production
  system: Payments Platform
  domain: Payments
  language: Go
  frameworks: [grpc]
  owner: Payments
  providesApis: [payments.v1]
  consumesApis: [ledger.v1]
  links:
    - { kind: runbook, label: On-call runbook, url: https://wiki.example.com/payments/runbook }

Field reference

How ELOS applies it

• The file wins for the fields it sets. On every sync, a declared field replaces whatever is in ELOS. To edit a field in ELOS instead, remove it from the file.
• Fields the file doesn't set are yours. Anything you edit in ELOS that the file doesn't mention is kept.
• Owner. ELOS sets the owner from the file when the service has no owner yet; after that, ownership changes are made in ELOS so handovers stay recorded. A single word is read as a team (Payments); a name with a space as a person (Priya Raman).
• No file. ELOS falls back to the repository's CODEOWNERS (.github/CODEOWNERS, CODEOWNERS or docs/CODEOWNERS): the owner of the catch-all * rule, else the first rule. With neither, the service is flagged as an orphan.
• Docs. The repository's README.md, docs/README.md, docs/runbook.md or RUNBOOK.md is indexed as knowledge linked to the service, so Ask ELOS can cite it.
• What's skipped. Forks aren't services. Archived repositories are listed but their files aren't read.

Roll it out across many repositories

Adding the file is a normal change in each repository. To add a starter file everywhere at once, script it with your source-control CLI and open one pull request per repository for its owners to review and complete. Start with your tier-1 services.

Keep it current

Connecting runs the first sync. To re-read your repositories on a schedule, start a recurring sync through the API (default every hour). Each run records one Synced integration entry in the audit log, and a service is only updated when something actually changed.

curl -sS -X POST "$ELOS_API/v1/integrations/github/sync/schedule" \
  -H "Authorization: Bearer $ELOS_KEY" -H "Content-Type: application/json" \
  --data '{"intervalSeconds": 3600}'

Live repository events, so new repositories appear within seconds, are set up with our team.