Backstage Core Concepts
After grasping the big picture in the Backstage Overview, this document explains the core concepts developers should share as common knowledge before operating or extending Backstage.
1. Software Catalog
The Software Catalog is the heart of Backstage. It centrally manages all software in the organization (services, APIs, libraries, infrastructure, owners) in units called Entities.
Ingestion flow into the catalog
The catalog ingests data starting from a catalog-info.yaml placed in each repository.
- Entity Provider — defines where entities are fetched from (a specific GitHub org, static files, etc.).
- Processor — validates ingested entities, resolves
annotations, and builds relationships between entities. - Ingestion re-runs periodically, reflecting changes to
catalog-info.yaml.
2. Entity model (Kind)
Every entity has a kind. The main kinds are:
| Kind | Meaning | Examples |
|---|---|---|
| Component | A deployable/runnable unit of software | Microservice, web app, library |
| API | An interface a Component provides/consumes | REST, gRPC, GraphQL |
| Resource | Infrastructure a Component depends on | Database, storage, queue |
| System | A grouping of related Components / APIs / Resources | "Payment system" |
| Domain | A higher-level business area grouping Systems | "E-commerce business" |
| Group | A team / organizational unit | "Payments team" |
| User | An individual | Developer account |
| Location | A special kind pointing to the source of other entities | Where catalog-info.yaml lives |
Relationships between entities
Entities relate to one another, letting you visualize dependencies and ownership as a graph.
Key relations: ownerOf / ownedBy, partOf / hasPart, dependsOn / dependencyOf, providesApi / consumesApi.
3. Writing catalog-info.yaml
catalog-info.yaml is the file that defines an entity; place it at the root of each repository.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-api
namespace: default
description: Microservice responsible for payment processing
tags:
- dotnet
- payments
annotations:
github.com/project-slug: my-org/payment-api
backstage.io/techdocs-ref: dir:.
backstage.io/kubernetes-id: payment-api
links:
- url: https://dashboards.example.com/payment
title: Operations dashboard
spec:
type: service
lifecycle: production
owner: group:payment-team
system: payment-system
providesApis:
- payment-rest-api
dependsOn:
- resource:payments-db
Key fields
| Field | Role |
|---|---|
metadata.name | Unique name of the entity (required) |
metadata.namespace | Namespace; defaults to default |
metadata.annotations | Keys for external integrations (GitHub, TechDocs, Kubernetes, etc.) |
metadata.tags | Tags for search / filtering |
spec.type | Component type (service / website / library, etc.) |
spec.lifecycle | Lifecycle (experimental / production / deprecated) |
spec.owner | Owner (Group or User) — the crux of ownership |
annotations are the keys each plugin uses to link to external systems. For example, adding backstage.io/kubernetes-id lets the Kubernetes plugin show the relevant pods. See Using Plugins for details.
4. TechDocs (docs-as-code)
TechDocs is a docs-as-code mechanism that manages documentation in the same repo as the code.
- Based on MkDocs, it generates a static site from Markdown.
- Place
mkdocs.ymland adocs/directory in the repo, and link them via thebackstage.io/techdocs-refannotation incatalog-info.yaml. - The generated HTML is stored in object storage such as S3 / Azure Blob and served from Backstage (recommended for production).
Because docs are updated in the same place and review flow as code, they are less likely to go stale.
5. Search
Search searches across catalog, TechDocs, and other plugin content.
| Search backend | Use case |
|---|---|
| Lucene (in-memory) | Development / small scale. No config, but lost on restart |
| PostgreSQL | Medium scale. Reuses your existing DB |
| Elasticsearch / OpenSearch | Large scale / feature-rich. Recommended for production |
Search targets are indexed by Collators and refreshed periodically.
6. Authentication, authorization, permissions
Authentication
Backstage authenticates users via an external IdP.
- Example providers: OIDC, GitHub, GitLab, Google, Microsoft Entra ID, etc.
- The authenticated identity is mapped to User / Group entities in the catalog and used for ownership display, etc.
Related: OAuth / OpenID Connect, Bearer authentication.
Authorization (Permission Framework)
The Permission Framework lets you define access control as policies — "who can edit which entity," "who can run which template," etc.
- Policies are written as code (TypeScript).
- Role-based control is possible (e.g., only owners can edit).
7. Data persistence
| Environment | Database | Notes |
|---|---|---|
| Development | SQLite (in-memory possible) | No config; lost on restart |
| Production | PostgreSQL | Required. Holds catalog, permissions, and per-plugin data |
Backup targets are PostgreSQL and TechDocs storage. For operational details, see Operating Backstage.
Best Practices
- Entity naming conventions / namespace design — decide naming conventions up front to avoid collisions and confusion.
- Mandatory ownership — adopt a rule that disallows entities without
spec.owner, ensuring catalog quality. - Standardize annotations — auto-apply integration annotations via templates to prevent omissions (see Software Templates).