Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Entity overlays is a process originally created to handle use cases of updating metadata of entities ingested into the Software Catalog directly from external sources instead of through manual entity creation, such as those in the data registry, but can be applied to any entity in the Catalog. Applying an overlay does not change the metadata at the source or in the Catalog but decorates the entity in an reversible manner for simpler entity management through Portal’s UI. Overlays currently supports adding labels, annotations, and tags and updating the owner and the lifecycle.

​
Use Cases

Any scenario where there is a need or want for different metadata to exist in Portal than the original source of the entity, including but not limited to:
  • Decorating an entity with extra metadata only needed in the Software Catalog and not the source
  • Adding tags to make an entity more easily searchable in the Catalog
  • Defining a relationship between entities just in Portal with labels
  • Add annotations that are required for other plugins to show on the entity

​
Permissions

There is a default RBAC policy in place to protect entities from being unexpectedly updated. These rules are:
  1. Portal admins can always update an entity (Entity overlays admin role)
  2. The owner of an entity can update their entity (Entity overlays user role)
  3. If an entity has no owner defined in the catalog, any user can update this entity (Entity overlays user role)
This policy can be loosened or tightened by publishing your own policy. If you’ve already published a non-default policy, check to see if these roles are included, and add whatever policy is desired via the entity-overlays.overlay.update permission.

​
How To

On a given entity page needing an update, go to the ellipses menu in the top right corner.
Overlay location
The option Edit entity overlay will open the overlays form.
Overlay menu
Here one can update any and all supported metadata. For tags, click Add after each tag addition.
Overlay empty form
When all overlays are added, hit Save and a confirmation will pop up.
Overlay filled form
The updating of the entity is a background process that usually happens quickly but can take up to a couple of minutes and requires a page refresh to display. To remove an overlay, you can remove the metadata from the form - saving this update will remove in the same timeframe as adding.