Internal Developer Platforms (IDPs) & Backstage

IDPs abstract infrastructure complexity from developers via golden paths. Backstage (CNCF) is the leading open-source IDP framework: software catalog, templates, plugins, TechDocs. Reduces cognitive load; accelerates onboarding.

Overview

Golden paths instead of deep expertise

An Internal Developer Platform (IDP) is a self-service layer built by platform engineering teams to reduce cognitive load on application developers. Developers no longer need to understand Kubernetes, Terraform, IAM and CI/CD pipelines in depth. The IDP presents golden paths: opinionated, pre-approved workflows for common operations.

Backstage

Backstage, open-sourced by Spotify and now a CNCF incubating project, is the leading framework for building IDPs.

Software Catalog — Central registry of all services, libraries, websites and data pipelines; each entity is defined by a catalog-info.yaml in its repo; tracks ownership, dependencies, API contracts, and links to runbooks and dashboards
Software Templates (Scaffolder) — Form-based templates that create new services along the golden path: language, framework, CI pipeline and Kubernetes manifests pre-configured
TechDocs — Docs-as-code: Markdown next to the code, rendered centrally with search
Plugins — The extension model: brings PagerDuty, GitHub Actions, ArgoCD, Grafana into one portal

A golden path in one click

> [!TIP] Running a template creates the repo, CI pipeline and initial deployment in one click.

Key concepts

Golden Path: The opinionated, platform-supported way to complete a common developer task. Removes decision fatigue and ensures consistency. Teams can deviate, but the golden path is what the platform team supports and optimizes.
Software Catalog: Backstage registry of all software entities. Each service has a catalog-info.yaml declaring its kind, owner, lifecycle, dependencies, and links. Enables discoverability and dependency mapping.
Scaffolder Templates: Parameterized project templates in Backstage that create new services via a form UI. Generates the repo, CI config, and Kubernetes manifests. Enforces consistency without copy-paste from existing repos.
Cognitive Load: The mental effort required for a developer to ship a feature. IDPs reduce intrinsic cognitive load (infrastructure concepts) and extraneous cognitive load (navigating multiple tools) so developers focus on the actual product problem.
Developer Portal: The developer-facing UI of an IDP. Backstage is the most common open-source framework. Commercial alternatives: Cortex, Port, OpsLevel.

When to use it

Platform engineering teams standardizing developer workflows across 10+ services
Onboarding new engineers who need to create production-ready services without deep infrastructure knowledge
Replacing scattered wikis with a searchable software catalog
Implementing CNCF platform engineering maturity model stage 2+

Interview questions

What is the difference between an IDP and a developer portal?
How does Backstage Software Catalog work?