Skip to main content
This guide demonstrates how to model and register Backstage catalog entities and their relationships: Components, Groups, Users, Systems, Domains, and Resources. You will create example entities—shopping-cart, inventory, ecommerce group, user john, purchasing system, shopping-app domain, and inventory-db resource—and wire ownership and dependency relationships between them. What you’ll learn:
  • How to author entity descriptors (YAML) for common Backstage kinds
  • How to import entities into the Backstage catalog
  • How to express ownership, system membership, and dependency relationships
  • How to update app-config.yaml import rules when a kind is blocked

1. Create a Component (shopping-cart)

Create a simple website component descriptor named shopping-cart. Save this YAML into the repository you use for Backstage catalog imports (for example entity.yaml):
Commit and push the file:
Then open the repository on GitHub to confirm the entity file is present.
A screenshot of a GitHub repository page for "backstage-guest-user-domain-system" showing the main branch, a highlighted entity.yaml file, and a prompt to "Add a README."

2. Register the component in Backstage

In Backstage, go to Create → Register Existing Component and point to the GitHub repo URL (or your configured file location). If Backstage previously fetched the file and returned an error due to a transient issue (such as a typo you already fixed), wait a minute and try Analyze again.
Backstage may cache a location’s content for a short period. If you fixed a typo in your repository and the UI still shows the old error, wait a minute and click Analyze again before re-importing.
A Backstage web UI showing the "Create a new component" page with a left navigation menu and a central Templates area. The main card displays an "Example Node.js Template" with search and filter options on the left.
If the UI or backend returns an InputError indicating an unrecognized kind or apiVersion, it usually means a typo in the YAML or that the catalog import rules for that location don’t permit the kind. Example backend error (keep JSON inside a code block to avoid MDX parsing issues):
Once Analyze succeeds, click Import to add the component to the catalog.

3. Define and import a Group (e-commerce)

You can include multiple YAML entities in a single file separated by ---. Add a Group entity to the same file (or as a separate file) like this:
If importing the Group fails, it may be because your app-config.yaml import rules exclude Group. A default config might look like:
Add Group to the allowed list and restart Backstage:
Any changes to app-config.yaml require you to restart the Backstage dev server for the new rules to take effect.
After restarting, re-import the location. If you want faster iteration, unregister the location in the UI and register it again to force immediate processing.
A screenshot of the Backstage "My Company Catalog" web UI showing the "All Groups (1)" table with a single "guests" group. A green hand cursor points at the "guests" entry and a left navigation sidebar lists Home, APIs, Docs, and Create.
You can review configured locations in Backstage under Catalog → Locations:
A screenshot of the Backstage web UI titled "My Company Catalog," showing a left navigation sidebar and a green header. The main panel lists "All Locations (4)" with generated location entries, their types (file/url) and target paths.
When import completes, the Register wizard will list the discovered entities ready to import:
Screenshot of the Backstage "Register an existing component" page showing a multi-step wizard that found a repository and added entities (including "shopping-cart") to the catalog. The app's left navigation and instructions for linking a repository are visible.

4. Create a User (john)

Backstage supports a User kind. Add this user entry to your entities file:
If User is not allowed for the location, you will see a NotAllowedError. Example:
Add User (and any other required kinds like Domain) to app-config.yaml and restart Backstage:
Once the user is imported, you can open john’s profile to see relations such as memberOf: ecommerce and any ownership cards.
A screenshot of the Backstage web UI showing a user profile page for "john" with an overview panel. The page shows an "ecommerce" relation and an Ownership card displaying a WEBSITE component.

5. Set an owner to a User (owner reference format)

By default, owner values are interpreted as groups. To assign an individual user as owner, use a fully qualified entity reference such as user:default/john (or user:john if your location uses the default namespace). Example:
After updating and importing, shopping-cart will show john as owner.

6. Add another Component (inventory) and a dependency

Create an inventory component and make shopping-cart depend on it using spec.dependsOn. Place both components in the same file if convenient:
After importing, the shopping-cart component page will show a relation to the inventory component.
A Backstage web UI showing the "shopping-cart" component with an About panel on the left. On the right is a Relations graph linking the shopping-cart component to an inventory service.

7. Create a System and associate components

Systems group components delivering a bounded feature set. Example System descriptor:
Associate components with the purchasing system by setting system: purchasing in their spec:
Viewing the purchasing system in Backstage will list related components, APIs, and resources. See the Backstage docs for more descriptor examples:
A screenshot of the Backstage documentation page titled "Descriptor Format of Catalog Entities." It shows a left navigation menu, the main content and contents list in the center, and a right-hand sidebar with section details.

8. Create a Domain (shopping-app) and assign systems

Domains are a higher-level grouping for systems. Example Domain descriptor:
If Domain is blocked by import rules, add it to app-config.yaml (see earlier example), restart Backstage, and import. After importing, the shopping-app domain will list its systems (for example purchasing).
A Backstage web UI showing an "About" overview for an ecommerce domain/shopping-app, with a description that it handles the ecommerce portion of the business and a relations graph linking "ecommerce" to "shopping-app." The left sidebar shows navigation items like Home, APIs, and Docs.
To assign a system to a domain, set spec.domain on the system to the domain name (for example spec.domain: shopping-app). You can also use spec.subdomainOf in domains for hierarchical structuring.

9. Create a Resource (inventory-db) and connect it

A Resource models infrastructure or external services such as databases. Example Resource descriptor for an inventory database:
Make the inventory component depend on the resource by referencing it in spec.dependsOn:
Ensure Resource is permitted by your catalog rules. After importing, the inventory component will show a relation to inventory-db, and clicking it will open the resource overview.
A screenshot of the Backstage service catalog showing the "inventory-db" resource overview, with an About panel listing description, owner (ecommerce) and system, and a Relations graph on the right. The left sidebar shows navigation (Home, APIs, Docs, Create) and the top header displays the inventory-db title.

Reference: Common Backstage Entity Kinds


Summary & Best Practices

  • Backstage catalog supports first-class entity kinds: Components, Groups, Users, Systems, Domains, and Resources.
  • Use owner to indicate ownership; prefix with user: for individual owners (for example owner: user:john). Groups can be referenced by plain names (for example owner: ecommerce).
  • Use spec.system to associate a component with a system.
  • Use spec.dependsOn to model dependencies between components and resources (for example - component: inventory or - resource: inventory-db).
  • If you encounter NotAllowed errors when importing entities, review the catalog.import.rules in app-config.yaml, add the missing kinds, and restart Backstage.
  • For details and more descriptor examples, consult the Backstage documentation:
API entities and more advanced relationship modeling (custom relations, annotations, and entity refs across namespaces) are useful next topics to explore as you expand your catalog.

Watch Video

Practice Lab