Skip to main content
In this lesson you’ll learn what an entity is in Backstage and how the catalog uses entities to model and track your software and organizational resources. An entity in Backstage is any item you want the catalog to manage and display. Entities provide structured metadata about software and related items so Backstage can discover, present, and operate on them. Common entity types include: Whenever you want Backstage to track something — a microservice, an API, a team, or a resource — model it as an entity.
A presentation slide titled "Entity – Overview" with a central rounded box labeled "Entity" above five colored boxes labeled Software, API, Users/Groups, Resources, and System. The slide includes a small "© Copyright KodeKloud" notice.
Entity YAML: format and key fields Entities are represented as YAML documents using a schema inspired by Kubernetes resources. This enables evolution through apiVersion values (for example v1alpha1 → v1beta1 → v1) while keeping a consistent top-level shape. Typical top-level fields:
  • apiVersion — schema version (e.g., backstage.io/v1alpha1)
  • kind — entity kind (e.g., Component, API, User, Resource, System)
  • metadata — identifier, name, description, labels, annotations, tags, and links
  • spec — domain-specific fields (type, lifecycle, owner, system, etc.)
A typical component entity looks like this:
Key notes:
  • kind determines how Backstage will interpret the entity and which built-in processors or templates apply.
  • metadata is used for display, filtering, and linking in the UI.
  • spec contains the attributes your organization uses to classify and operate the entity (standardize spec.type values across teams for consistent catalogs — e.g., website, service, package, library).
Where to store the entity YAML The recommended convention is to store your entity declarations (commonly named catalog-info.yaml) in the root of the repository they describe. This keeps metadata versioned with the code and simplifies discovery when scanning repositories.
  • Preferred: Put catalog-info.yaml at the repository root of the project it describes.
  • Alternatives: Store entity YAML in a central repo, cloud storage (S3), or any location Backstage can access. Choose whatever fits your organization’s workflow.
The image shows the GitHub logo linked to a project containing a highlighted catalog-info.yaml file and two file icons labeled catalog-info.yaml. On the right is a code editor file tree with folders (docs, node_modules, src) and files including .gitignore, catalog-info.yaml, package-lock.json, and package.json.
Placing catalog-info.yaml in the project root is recommended because it keeps entity metadata versioned alongside the code and simplifies automatic discovery through repository scans or templates.
A diagram titled "Storing catalog-info.yaml" comparing two storage options: GitHub (left) and an S3-style bucket (right), each showing three YAML files labeled app1.yaml, app2.yaml, and app3.yaml. The left side uses the GitHub logo and pink file icons, while the right shows a green bucket icon with green file icons.
How Backstage discovers and registers entities Backstage supports multiple ways to import and register entity YAML files into the catalog. Choose one or more approaches depending on scale and automation needs.
  1. Static configuration via app-config.yaml
    • Declare locations in your Backstage app configuration under catalog.locations. Each location can be a url (for raw GitHub files) or a file (local path relative to the backend process).
    • Example app-config.yaml entries:
  • Entities discovered via configured locations are imported on startup or when the location is refreshed. This is useful for centrally-managed lists of entities.
  1. Register via the Backstage UI
    • Use Create → Register Existing Component and provide a URL or repository path to an entity file. The UI analyzes the target and guides you through importing the entity.
A screenshot of a "Registering With UI" wizard for tracking a component in a Scaffolded Backstage App, showing a URL input field and an "ANALYZE" button. The right pane provides instructions for registering an existing component by linking to an entity file or repository.
  1. Templates
    • Backstage software templates scaffold new projects and can generate a catalog-info.yaml as part of the template. Templates can also include registration automation so a newly created project gets registered automatically in the catalog.
A simplified workflow diagram showing a Template on the left linked to a GitHub box containing a catalog-info.yaml file, which points to a "New project" and then down to a CI/CD pipeline. Icons and dashed connectors illustrate the flow from template to repository to project build.
  1. Entity providers
    • Use entity providers to automatically discover and register entities at scale. Providers are able to scan sources such as:
      • GitHub organizations or lists of repositories
      • Cloud storage (S3)
      • Custom inventory services
    • Entity providers are ideal for onboarding many repositories without manually declaring each location.
Summary: putting it all together
  • Define entity YAML files (catalog-info.yaml) for every resource you want Backstage to track.
  • Store them where they best fit your workflow (recommended: next to the code).
  • Choose discovery/registration strategies that match your scale: static app-config.yaml locations, UI registration, templates, or automated entity providers.
  • Standardize metadata fields and allowed spec.type values across teams to maintain a consistent, searchable, and actionable catalog.
Links and further reading

Watch Video