Specific design and ingestion tasks for the Backstage Software Catalog: the descriptor format, the system model, ownership, entity providers and processors, orphan handling and running a large catalog.
The fields every catalog-info.yaml needs and the ones teams get wrong: apiVersion, kind, metadata.name uniqueness, lifecycle values, owner references, multiple entities per file and validating files before registering them.
Choosing how far to model: when a group of components deserves a System, when Systems belong in a Domain, how Resources capture databases and buckets, and which relations the model generates for the catalog graph.
Making spec.owner meaningful: Group and User entities from an org data provider, team hierarchies with spec.parent, ownership references in the signed-in identity, and what to do with entities whose owner has left.
Choosing how entities enter the catalog: registered and static locations versus discovery entity providers, how each handles deletion, which suits a few repositories and which suits thousands.
When no built-in provider fits: writing an entity provider for an internal inventory or API, full versus delta mutations, scheduling, and how removed source records lead to entity deletion.
Using processors to enforce naming rules, add annotations or emit relations: processing order and priority, why processors cannot delete entities, and when an entity provider is the better place for the logic.
Why entities become orphans, the orphan annotation, the default delete strategy versus keep, orphanProviderStrategy for removed providers, and why deleting a still-maintained entity does not stick.
Ingesting very large sources without long full refreshes: the incremental ingestion module, Microsoft Graph incremental ingestion for large tenants, burst and rest cycles, and monitoring ingestion progress.
Balancing catalog freshness against GitHub, GitLab and Bitbucket API limits: processingInterval as a minimum, webhook-driven updates instead of polling, provider schedules and signs that limits are being hit.
When to add a kind and when a Component or Resource type is enough: allowing the kind in catalog rules, validation through processors, and the cost of custom kinds for plugins and upgrades.
Making Git the only way to change the catalog: catalog.readonly, static locations and providers, what stops working for plugins that write to the catalog, and how teams register new components.
The annotations that switch on plugin features for an entity, from techdocs-ref and source-location to GitHub, Jenkins, SonarQube and Vault keys, plus deprecated annotations to clean up.
Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.