A Shah

Building an Internal

Developer Platform (IDP) with Backstage

Introduction to Internal Developer Platforms

In modern software organizations, the complexity of cloud-native architectures, microservices, and diverse tooling can overwhelm development teams. Developers are often burdened with cognitive load, spending valuable time navigating infrastructure, security, and deployment pipelines instead of writing code. The solution to this growing problem is the Internal Developer Platform (IDP).

An IDP provides a curated, self-service experience for developers, offering a “paved road” that abstracts away the underlying complexity. It codifies best practices and provides developers with the tools and guardrails they need to build, ship, and run software efficiently and securely. This post explores how to build a powerful IDP using Backstage, the open-source framework created and donated by Spotify.

What is Backstage?

Backstage is an open-source framework for building Internal Developer Platforms. It provides a unified, extensible frontend for all your infrastructure tools, services, and documentation. Think of it as a single pane of glass that gives your developers a consistent and discoverable view of your entire software ecosystem.

The core philosophy of Backstage is to enable autonomy while maintaining standards. It achieves this through three key features:

  1. The Software Catalog: A centralized system that tracks ownership and metadata for all your software (microservices, libraries, websites, ML models, etc.).
  2. Software Templates (Scaffolder): A tool for creating new projects and components with best practices and boilerplate code built-in.
  3. TechDocs: A “docs-like-code” solution that renders technical documentation from Markdown files stored alongside the code in your Git repositories.

Why Backstage is a Game-Changer for Platform Engineering

Building a platform from scratch is a massive undertaking. Backstage provides a solid foundation with a rich, extensible plugin architecture, allowing platform teams to focus on integrating their specific tools and workflows rather than building the core platform itself.

The Software Catalog: Your Single Source of Truth

The heart of Backstage is the Software Catalog. It ingests metadata from catalog-info.yaml files stored in your Git repositories. This allows you to create a comprehensive, searchable inventory of your entire software ecosystem.

A typical catalog-info.yaml file looks like this:

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: The microservice responsible for processing orders.
  annotations:
    github.com/project-slug: 'my-org/order-service'
spec:
  type: service
  lifecycle: production
  owner: team-alpha
  system: e-commerce-platform
  providesApis: [orders-api]

By defining ownership (owner: team-alpha) and system relationships (system: e-commerce-platform), the catalog builds a powerful graph of your architecture, making it easy to understand dependencies and identify service owners.

Software Templates: Standardizing Project Creation

The Backstage Scaffolder allows you to create standardized templates for new projects. This ensures that every new microservice, library, or website is created with the correct boilerplate, CI/CD pipeline, security configurations, and monitoring dashboards from day one.

A template is defined by a template.yaml file:

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-microservice-template
  title: Spring Boot Microservice
  description: Creates a new Spring Boot microservice with best practices.
spec:
  owner: team-platform
  type: service
  parameters:
    - title: Fill in some steps
      required:
        - component_id
        - owner
      properties:
        component_id:
          title: Name
          type: string
          description: Unique name of the component
        owner:
          title: Owner
          type: string
          description: Owner of the component
  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./skeleton
        values:
          component_id: ${{ parameters.component_id }}
          owner: ${{ parameters.owner }}
    # ... more steps to create a repo, register in catalog, etc.

When a developer uses this template, they are guided through a simple form, and the Scaffolder automates the entire process of creating a new, production-ready service.

TechDocs: Docs-Like-Code for a Maintainable Knowledge Base

TechDocs solves the problem of outdated documentation by treating docs as code. It discovers and renders Markdown files from your source code repositories, ensuring that documentation lives with the code it describes. This makes it easier for developers to keep documentation up-to-date and accessible.

Getting Started with Backstage

You can get a local Backstage instance running in minutes. All you need is Node.js, Yarn, Docker, and Git.

  1. Create a new Backstage app:

    npx @backstage/create-app

    This command will prompt you for the name of your app and create a new directory with the Backstage frontend and backend packages.

  2. Start the application:

    cd my-backstage-app
yarn dev

    This will start the Backstage frontend (usually on port 3000) and the backend (on port 7007). Open your browser to http://localhost:3000 to see your new IDP.

  3. Register an existing component:

    To add one of your existing services to the catalog, create a catalog-info.yaml file in the root of its Git repository. Then, register it in Backstage by adding the URL to your app-config.yaml:

    # app-config.yaml
catalog:
  locations:
    - type: url
      target: https://github.com/my-org/my-service/blob/main/catalog-info.yaml

    Restart Backstage, and your service will appear in the catalog.

Conclusion

Building an Internal Developer Platform is a strategic investment in developer experience and productivity. By providing a paved road, you empower your teams to deliver value faster and more reliably. Backstage provides an extensible, open-source foundation that accelerates your journey to building a world-class IDP. It effectively tackles the challenges of discoverability, standardization, and documentation in a complex software ecosystem. If you are serious about improving your engineering effectiveness, it’s time to start building your IDP with Backstage.

Further Reading

For those who wish to dive deeper into Backstage, the official documentation and Spotify’s engineering blog are invaluable resources:

See Also

Comments