The Atom of Backstage: A Complete Dissection of ‘Entity’ – Unifying Everything from Services to Teams!

Jul 3, 2026

—

Welcome to the world of platform engineering! 🌟 If you’re new to Backstage, you’ll quickly realize that everything revolves around the ‘catalog’. But do you know what the smallest building block, the fundamental unit, that makes up this catalog is?

Today, we’re going to thoroughly dissect the ‘Entity’, which forms the foundation of Backstage. After reading this article, you’ll understand how your complex infrastructure transforms into a single, consistent data model!

1. What is an Entity? 🧱

In Backstage, an Entity is a standardized fundamental unit that describes every individual component within a software ecosystem.

It doesn’t just mean ‘services’ that contain source code. All organic entities that make up your system can become entities.

Service (Component): Actual running microservices or web apps
API: Interfaces that services provide or consume
Team (Group) & Developer (User): Information about who creates and manages them
Infrastructure Resource: DB, S3 bucket, Kubernetes cluster, etc.

2. What does an Entity look like? (YAML Structure) 📝

Entities are usually defined in a file called catalog-info.yaml. This file has a structure very similar to Kubernetes resource definitions, so you might be familiar with it. Every entity consists of three main parts:

YAML

apiVersion: backstage.io/v1alpha1
kind: Component # Type of entity
metadata:
  name: my-awesome-service # Name of the entity
  description: 우리 팀의 메인 API 서비스입니다.
  tags: ["java", "spring-boot"]
  annotations:
    backstage.io/managed-by-location: url:https://github.com/...
spec:
  type: service
  owner: team-alpha # Owning team (relationship with other entities)
  lifecycle: production

apiVersion & kind: Defines what this entity is (e.g., a component, a group).
metadata: Contains information for search and identification, such as name, description, and tags.
spec: Defines detailed information specific to that Kind and relationships with other entities.

3. Why Entities are Powerful: Relationships 🕸️

The reason entities exert powerful force beyond being simple “descriptions” is because of the connections between them.

For example, the moment you write the name of a specific Group entity in the spec.owner field of a Component entity, Backstage automatically links the two.

“Who manages this service?” 👉 Linked to a Group entity
“What DB does this service use?” 👉 Linked to a Resource entity
“Which APIs did this team develop?” 👉 Can be queried in reverse

These relationships combine to form a massive Software Graph.

4. Exploring Key Entity Kinds 🧐

Backstage provides the following core Kinds by default:

Kind	Description	Example
Component	A piece of software made of code	Service, Website, Library
API	Interface contract between services	REST API, GraphQL, gRPC
Resource	Infrastructure required for software to operate	PostgreSQL, S3, RDS
Group	A team or department within an organization	Platform Team, Payment Department
User	Individual developer	John Doe, Jane Smith
System	A large abstract group of related entities	Payment System, User Management System

—

5. Benefits of Entities for Developers 💡

Consistency: All teams describe their services in the same format.
Discoverability: “APIs whose creators are unknown” disappear. All information can be found with a single entity search in the catalog.
Foundation for Automation: Based on entity information, deployment status checks and security vulnerability scan results can be automatically linked. 🤖

🏁 Conclusion

The Entity, the foundation of the Backstage catalog, is not just a piece of data; it’s like a coordinate for drawing your organization’s complex software map. The better you define and connect entities, the more developers can focus on actual “development” instead of unnecessary communication.

Why not create a catalog-info.yaml in your project root right now and define your first entity? 🚀