s0sta
EN NL عربي
Filters
How to search
  • Plain words find names, texts and examples.
  • "two words" finds the exact phrase.
  • --name or -x finds an option.
  • #word looks only inside commands.
  • @grep finds lessons and labs that use grep.
  • Filters: cat:network · in:labs · in:notes · level:rhcsa · ch:8 · root:yes. Put ! before a word to leave it out. OR between words means one of them.
  • ↑ ↓ to move · Enter to open · Esc to close · / to search

Platform engineeringPlatform series

Anatomy of a Backstage catalog-info.yaml

A catalog-info.yaml is a short YAML file, and it decides whether a service exists to everyone outside its repo. Backstage reads it, indexes it and shows it on a page. A missing field fails at processing, not at build.

Quick reference

text
apiVersion kind metadata.name spec.type spec.owner spec.lifecycle
PartNameWhat it means
apiVersionThe schemabackstage.io/v1alpha1 is the current version for catalog entities.
kindThe entity typeComponent for a service or website. Also API, System, Domain, Resource.
metadata.nameThe unique nameUnique for its kind. Other entities use it to reference this one.
spec.typeThe typeservice, website or library. A custom type is a taxonomy decision.
spec.ownerThe ownerPrefer a group, for example group:default/platform.
spec.lifecycleThe lifecycleproduction, experimental or deprecated. It drives scorecards.

Explained

The six fields

apiVersion. backstage.io/v1alpha1 is the current version for catalog entities. It is not v1; the alpha is part of the string. kind. Component for a service, website or library. The same schema covers API, System, Domain and Resource. metadata.name. The unique name of the entity within its kind. Other entities use it to reference this one, so renaming it breaks those references. spec.type. service, website or library. The catalog accepts any string, but a custom type is a taxonomy decision. spec.owner. The owning group, for example group:default/platform. Prefer a group to a person; groups outlive staff changes. spec.lifecycle. production, experimental or deprecated. It tells readers whether the service is safe to depend on.

What goes wrong

An owner that does not resolve shows up as an orphan, and a missing required field keeps the entity out of the catalog. Both pass the commit and surface when Backstage processes the entity.

The honest caveat: Backstage validates the entity when it processes it, not when you push. A typo in an owner can sit in Git for weeks.

The lesson: the catalog is only as true as the owner and lifecycle you put in it.

In one line

A file is not a service. The catalog only works when owner and lifecycle are true.

Lint the file

yamllint catalog-info.yaml

More notes: Platform engineering

Open in the notes app: search, filters, copy This note on GitHub