KodeKloud Notes

In this lesson, we explore Backstage’s catalog capabilities by breaking down what an Entity is. In Backstage, an Entity centralizes metadata and relationships for software components, APIs, users/groups, resources (e.g., databases, infrastructure), and systems (collections of components).

The image is an overview diagram showing an "Entity" connected to five components: Software, API, Users/Groups, Resources, and System.

Defining a Backstage Entity via YAML

Backstage Entities are declared in catalog-info.yaml files using a common YAML schema—very similar to Kubernetes manifests. Each entity document comprises:

apiVersion: Schema version (e.g., backstage.io/v1alpha1).
kind: Entity type (e.g., Component, API, User).
metadata: Attributes such as name, description, labels, annotations, tags, and external links.
spec: Kind-specific configuration (e.g., type, lifecycle, owner, system).

Here’s a complete example of a Component entity:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
  labels:
    example.com/custom: custom_label_value
  annotations:
    example.com/service-discovery: artistweb
    circleci.com/project-slug: github/example-org/artist-website
  tags:
    - java
  links:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: public-websites

Where to Store `catalog-info.yaml`

It’s best practice to colocate your catalog-info.yaml with your source code. Typically you place it at the root of your project repository:

Note

Keeping catalog-info.yaml beside your code enables automatic scaffolding, version control, and seamless CI/CD integration.

Alternatively, you can centralize definitions in a dedicated repository or object storage (e.g., S3), then point Backstage at that location:

The image illustrates the storage of `catalog-info.yaml` files in two locations: GitHub and a bucket, each containing `app1.yaml`, `app2.yaml`, and `app3.yaml` files.

For the examples below, we assume one catalog-info.yaml per project, located at the repository root.

Registering Backstage Entities

After creating YAML definitions, configure Backstage to discover and register them. Common registration methods include:

Method	Description
Static Configuration	Declare each entity URL or file path in `app-config.yaml` under `catalog.locations`.
UI Registration	Use the Register Existing Component form in the Backstage catalog interface.
Scaffolder Templates	Generate and auto-register `catalog-info.yaml` when scaffolding new projects.
Entity Providers	Bulk-import entities by scanning GitHub repos, S3 buckets, or other sources.

1. Static Configuration

Add your entity locations to app-config.yaml:

catalog:
  locations:
    - type: url
      target: https://github.com/myorg/auth-component.yaml
    - type: file
      target: ./catalog-info.yaml

2. Registering via the Backstage UI

Backstage’s catalog UI offers a Register Existing Component flow. Paste the catalog-info.yaml URL, validate, and confirm:

The image shows a user interface for registering a component in a Scaffolded Backstage App, with steps for selecting a URL, analyzing it, and registering an existing component.

3. Using Scaffolder Templates

When you scaffold a project with Backstage Templates, catalog-info.yaml is created and registered automatically:

The image is a flowchart illustrating a process involving a template, GitHub with a catalog-info.yaml file, a new project, and a CI/CD pipeline.

4. Entity Providers

Entity Providers scan configured sources (e.g., GitHub, S3) for YAML definitions and import them in bulk. This method streamlines onboarding across multiple projects:

The image illustrates a diagram of entity providers, showing GitHub and a storage bucket as sources for YAML configuration files (app1.yaml, app2.yaml, app3.yaml).

Links and References

Watch Video

Watch video content