Skip to main content
Welcome back. This lesson explains how Backstage — an open-source CNCF‑incubating project — acts as a framework for building developer portals and centralizing developer experience. Backstage is widely adopted because it unifies scattered tools, documentation, and platform capabilities into a discoverable, extensible portal. Why this matters: developers spend a large portion of their time searching for information across fragmented systems. Backstage reduces context switching, lowers cognitive load, and increases platform adoption by making APIs, owners, runbooks, templates, and telemetry easy to find.
A presentation slide titled "Developer Portals in Platform Engineering" that outlines three modern development challenges: Service Discovery, Knowledge Spread, and Cognitive Load. Each challenge has a short note (e.g., hard to find APIs/owners/SLAs, docs scattered across tools, ~40% dev time spent searching).
Overview Backstage is designed as a “single pane of glass” for developer experience and platform capabilities. It combines:
  • A customizable front-end (React-based).
  • A pluggable back-end (services and APIs you can extend).
  • A central Software Catalog (component metadata and registry).
Typical deployments run on Kubernetes, but you can run Backstage locally via Docker for development and testing. Managed Backstage offerings are available from vendors; they are deployments of the same open-source project, not replacements for it.
A presentation slide titled "Backstage – CNCF Developer Portal Platform" showing a stacked black logo on the left and three numbered highlights on the right about CNCF recognition, Spotify development, and adoption by Netflix/American Airlines/Expedia. A gray footer reads "A single pane of glass for developer experience and platform capabilities."
Architecture — core components Backstage centers around these core ideas:
  • Software Catalog: a unified registry for components, teams, systems, and locations (stores metadata, ownership, lifecycle state, relationships).
  • Plugins: modular integrations that surface external tool data inside Backstage (CI, monitoring, security, etc.).
  • Scaffolding / Templates: reproducible project creation that enforces standards.
  • TechDocs: documentation-as-code integrated with the catalog and search.
Software Catalog (unified service registry) The Software Catalog is the authoritative source of truth for services and components. It captures metadata (owners, lifecycle, links to source, docs, and CI status) and enables discoverability, ownership assignment, and dependency analysis.
A slide titled "Software Catalog – Unified Service Registry" showing four colored cards labeled Components, Groups, Systems, and Locations with short descriptions of each (microservices, team organization, component collections, and external systems/data sources).
Example: a typical Component entity manifest that teams add to their repositories so Backstage can register services and metadata:
Key fields:
  • owner: who is responsible for the component.
  • lifecycle: experimental, production, deprecated, etc. — useful for dependency and risk analysis.
Benefits at a glance
A slide titled "Software Catalog – Unified Service Registry" that lists four platform engineering benefits—Discoverability, Ownership, Dependencies, and Lifecycle Management—each shown in a colored box with a short explanatory note.
Scaffolding and Software Templates Scaffolding (software templates) automates creating repositories, CI/CD pipelines, infra manifests (Terraform/Kubernetes), and observability wiring. Templates enforce standards across teams and reduce onboarding friction. Typical uses:
  • One-click project creation with repo + CI + monitoring.
  • Environment-specific templates (prod vs non-prod) that enforce security and policy differences.
  • Embedding security scans, secrets management, and deployment manifests.
A presentation slide titled "Software Templates – Scaffolding With Best Practices" showing four colored quadrants around a central circle: Service Creation, Repository Setup, Infrastructure, and Observability. Each quadrant contains brief notes about microservice scaffolding, automatic repo/CI setup, Terraform/Kubernetes manifests, and monitoring/alerting.
Example: a platform team can provide a template that provisions a repo, configures CI/CD with security scans, and wires up monitoring. Developers create production-grade services with a single flow in Backstage.
A presentation slide titled "Software Templates — Scaffolding With Best Practices" for the "Sparkle Pony Ranch Application." It lists features like one‑click microservice creation, CI/CD, monitoring, security scanning, and configuration to infra/ops standards.
TechDocs — documentation as code TechDocs brings documentation into the same lifecycle as code. Markdown in repos is automatically built and published to Backstage, making docs searchable and colocated with their component. Benefits:
  • Docs versioned with code.
  • Searchable, service-centric docs surfaced from the catalog.
  • GitOps-style documentation updates through normal PR workflows.
A slide titled "TechDocs – Documentation as Code" showing four colored feature boxes: Markdown-Based, Auto-Generated, Searchable, and Organized. Each box briefly describes benefits like writing docs alongside code, auto-building with changes, unified search, and service-based organization.
When engineers add API docs, runbooks, or infra guides in the repo, TechDocs auto-publishes on merge so documentation remains current and discoverable.
A presentation slide titled "TechDocs – Documentation as Code" showing "Team Implementation" with bullet points: Phuong writes API docs in Markdown in the code repo, docs auto-publish to Backstage on merge, and Alan's infra guides are visible alongside service documentation. The slide includes KodeKloud branding.
Plugin architecture and integrations Backstage plugins make it extensible: rather than replacing tools, Backstage integrates them into the portal. Community and custom plugins surface actionable data (build status, logs, dashboards, security findings) in the context of a component. Common integration categories: Links:
A presentation slide titled "Plugin Architecture — Extending With Platform Tools" showing four colored cards for Kubernetes, CI/CD, Monitoring, and Security with short examples (pod status, GitHub Actions/Jenkins, Grafana/PagerDuty, Snyk/SonarQube).
You can also build custom plugins to expose organization-specific tools and workflows. Any service with a REST or GraphQL API can be integrated, making Backstage an orchestration layer that complements — not replaces — your existing toolchain.
A presentation slide titled "Plugin Architecture – Extending With Platform Tools" with the subtitle "Sparkle Pony Ranch Integration." It lists three points: platform team integrates existing tools into Backstage, no need to replace monitoring/CI/CD/security tools, and developers get a unified experience without tool disruption.
Emerging trends: AI and mobile Expect Backstage to surface more AI-driven features (chat assistants, troubleshooting helpers, automated runbook suggestions) and richer mobile experiences for on-call workflows. Designing for mobile-friendly UIs and adding incident-focused plugins can accelerate response times for SRE and on-call teams. Start small and iterate: recommended rollout A low-risk rollout pattern:
  1. Choose a pilot team.
  2. Enable core features: Catalog + TechDocs + a couple of scaffolding templates.
  3. Measure adoption (catalog entries, template usage, time-to-create).
  4. Iterate: add plugins and custom templates driven by measured impact.
  5. Establish a champion program and plugin roadmap to scale.
A presentation slide titled "Backstage Pilot – Starting Small and Scaling" showing four colored blocks: Single Team, Core Features, Measure Success, and Iterate. Each block includes a short tip (e.g., begin with one dev team, start with a software catalog, track onboarding, gather feedback).
Start with a pilot: select one team, enable catalog + TechDocs + scaffolding templates, measure the impact, and expand incrementally.
Key takeaways
  1. Backstage is an open-source CNCF-incubating framework for developer portals that emphasizes extensibility and integration rather than a closed SaaS product.
  2. The Software Catalog is foundational: centralized metadata, ownership, and lifecycle information unlocks discoverability and downstream features.
  3. Scaffolding/templates enforce standards and accelerate onboarding by automating repo, CI/CD, security, and observability setup.
  4. TechDocs provides documentation-as-code: Markdown docs live with the code and auto-publish into Backstage.
  5. The plugin ecosystem lets you surface CI/CD, monitoring, security, and Kubernetes insights inside the service view — improving developer productivity and platform ROI.
A presentation slide titled "Key Takeaways: Backstage — Unifying Developer Experience at Scale" showing four colored, numbered panels summarizing: 01 Plugin Ecosystem, 02 Developer Experience, 03 Platform Adoption, and 04 ROI, each with a short explanatory line.
Next steps and references Further reading and resources Backstage turns dispersed tools and documentation into a single, searchable developer experience. By centralizing metadata, templates, docs, and integrations, it makes platform capabilities discoverable, usable, and maintainable at scale. We’ll cover additional platform engineering patterns and how they complement developer portals in follow-up lessons. Thanks for reading.

Watch Video