Catalogs and portals

An internal developer portal is the interface layer of a platform. It is a place to find services, start a template, see who owns what, and open the runbook, the CI pipeline, the logs and the deploys from one page. Backstage, which started at Spotify and is now a CNCF project, is the most common open-source shape for one. The portal is not the platform itself. Without real paved roads behind it, a portal is a well-decorated directory of problems.

A service catalog is the part that answers the questions people ask during an incident. What exists? Who owns it? Where is the code? How is production doing? How do I reach someone at 3 a.m.?

The big idea

Think of a building directory in a large office. It shows which floor each team is on and who to call. The directory is useful only if it is up to date. A directory that someone has to update by hand falls behind within a month. The catalog stays current when registering a service is part of creating it.

Walking through it

Start small. Ownership, the repository and the on-call schedule answer most urgent questions. Add more fields when people search for them:

• Lifecycle: experimental, production or deprecated.
• Tier: how critical the service is.
• SLO link and dependency list.
• API spec, and a link to the dashboard.

Ownership metadata works best as a file in the repository, such as catalog-info.yaml, or an OWNERS file. Compulsory metadata beats wiki pages that rot. Ownership is the difference between "someone should fix the pager" and "team X gets the page".

Common mistakes

• Building a portal before the paved roads. A beautiful portal with nothing behind it gets ignored.
• Keeping ownership in a wiki. It goes stale. Put it next to the code.
• Adding fields no one searches for. Each field is a maintenance cost.

Check yourself

1. During an incident, which catalog fact matters most? Ownership and the on-call route. They tell you who gets the page, which is the first question.
2. Why register the catalog entry from the template? So every new service is registered without anyone remembering to do it.

Key takeaways

• The portal is the interface. The catalog is the ownership and discovery data behind it.
• Start with owner, repository and on-call, and expand as people search for more.
• Make registration automatic, through the template.

Further learning

Spotify's KubeCon talk covers the move from spreadsheets to a catalog and portal, and how adoption was handled.

The Backstage documentation explains what the portal is for.

Backstage documentation, what is BackstageWhat is Backstage? | Backstage Software Catalog and Developer Platformbackstage.io