Platform Engineering with Backstage: Building Developer Portals for Microservices Governance

The Complexity Challenge in Microservices Architectures

When a company decides to adopt microservices, the initial promise is autonomy and speed. Instead of a massive monolithic system where everyone touches the same codebase, the application is split into dozens or hundreds of smaller, independent services. In practice, this means each team can choose their tools, update dependencies, and deploy code without blocking the rest of the company. However, this freedom brings a hidden and severe cost: the fragmentation of knowledge.

As months go by, the number of repositories grows exponentially. Nobody knows exactly who owns which service, where the API documentation lives, or which security standards were applied. Developers spend more time hunting for information and setting up local development environments than writing useful business code. It is precisely in this scenario of operational chaos that the urgent need for platform engineering arises.

The Role of Platform Engineering and the Rise of Backstage

Platform engineering is not just a market buzzword, but a discipline dedicated to building internal products that empower developers to deliver software autonomously and safely. Instead of letting every team reinvent the wheel when setting up continuous delivery pipelines or provisioning cloud servers, a specialized team builds standardized tools. The goal is to make the developer experience seamless, where the easiest path is also the correct and secure one.

Originally created by Spotify and now maintained under the Cloud Native Computing Foundation (CNCF), Backstage has established itself as the market standard for building these developer portals. In practice, it acts as a unified control center for all company engineering. Through an extensible web interface, Backstage brings together service catalogs, technical documentation, monitoring dashboards, and self-service tools, eliminating tool dispersion.

Backstage Architecture and the Software Catalog

The heart of any Backstage implementation is its Software Catalog. This is a centralized database that tracks all software components in the organization, whether they are microservices, libraries, data pipelines, or infrastructure resources. Each component is described by a simple metadata file in YAML format, versioned directly in the service's own code repository. This means documentation and component registration live right alongside the source code, making updates frictionless.

These files follow a conceptual model based on Kinds, where we define entities such as Component, API, Resource, and User. A 'Component' represents the microservice itself, while an 'API' describes the communication contract it exposes to the world. Backstage reads these files automatically through periodic repository scans, ensuring the catalog is always up to date without requiring manual labor from engineers.

Standardizing Project Creation with Scaffolder

Another major bottleneck in companies is the ritual of initializing a new project. Setting up linters, test structures, continuous integration tools, and security rules consumes days of work and frequently results in inconsistencies. Backstage solves this through a module called Scaffolder, which acts as an automated template engine for creating new services across the organization.

In practice, the developer fills out a simple form in the Backstage web interface, choosing the type of service they want to create (for example, a Node.js API or a Java microservice). Backstage executes a set of pre-configured steps that generate the repository on GitHub or GitLab, inject the structured base code, set up initial credentials, and register the new service in the corporate catalog. Initialization time drops from days to mere minutes, ensuring 100% of new projects are born compliant with company security guidelines.

Implementing the Catalog with a Configuration File

To illustrate how Backstage discovers and catalogs organizational microservices, here is a practical example of a metadata file, commonly named 'catalog-info.yaml', which must be placed at the root of every service repository.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-authentication-service
  description: Microservice responsible for user authentication and session management.
  annotations:
    github.com/project-slug: my-company/user-auth
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: security-team
  dependsOn:
    - resource: users-database

This small YAML file is enough for Backstage to understand who owns the service, what dependencies it has (such as a database), and where the automatically generated technical documentation from TechDocs is located. From then on, any engineer in the company can access the portal and view the health status, alerts, and owners of that specific component.

Governance, Extensibility, and Final Considerations

Governance in a distributed architecture is often seen as a bureaucratic and punitive process. With Backstage, we shift this perspective to governance through enablement. Because the portal centralizes quality metrics, known security vulnerabilities, and architecture standard compliance, teams can transparently view their own technical debt. Community plugins allow extending the platform to integrate tools like Kubernetes, SonarQube, PagerDuty, and Grafana, creating a truly unified experience.

In short, adopting Backstage combined with a solid platform engineering strategy transforms how software development is experienced in companies. It reduces engineers' cognitive load, eliminates wasted time on internal bureaucracy, and establishes a scalable, auditable foundation for sustainable microservices growth.