> ## 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.

# Entity Overlays

> Apply reversible metadata overlays to Software Catalog entities, adding labels, annotations, tags, and updating ownership without modifying the source.

## 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](./data-experience/overview), 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,](https://backstage.io/docs/features/software-catalog/descriptor-format/#labels-optional)
[annotations,](https://backstage.io/docs/features/software-catalog/descriptor-format/#annotations-optional) and
[tags](https://backstage.io/docs/features/software-catalog/descriptor-format/#tags-optional) and updating the
[owner](https://backstage.io/docs/features/software-catalog/descriptor-format/#specowner-required) and the
[lifecycle](https://backstage.io/docs/features/software-catalog/descriptor-format/#speclifecycle-required).

## 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](./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](./rbac#using-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.

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/FZ08uNumGsfd2d93/portal/assets/entity-overlays/entity-overlays-location.jpg?fit=max&auto=format&n=FZ08uNumGsfd2d93&q=85&s=9f16cf64cd4b132d47424c02f694c3a4"
    alt="Overlay
location"
    width="2506"
    height="398"
    data-path="portal/assets/entity-overlays/entity-overlays-location.jpg"
  />
</Frame>

The option `Edit entity overlay` will open the overlays form.

<Frame>
  <img src="https://mintcdn.com/spotify-89f50c35/FZ08uNumGsfd2d93/portal/assets/entity-overlays/entity-overlays-menu.jpg?fit=max&auto=format&n=FZ08uNumGsfd2d93&q=85&s=ce3d06e74ea91915d38d597ec6acb4f9" alt="Overlay menu" width="596" height="650" data-path="portal/assets/entity-overlays/entity-overlays-menu.jpg" />
</Frame>

Here one can update any and all supported metadata. For tags, click `Add` after each tag addition.

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/FZ08uNumGsfd2d93/portal/assets/entity-overlays/entity-overlays-empty-form.jpg?fit=max&auto=format&n=FZ08uNumGsfd2d93&q=85&s=ca1789fc46c975963d719a05d8778b0c"
    alt="Overlay empty
form"
    width="1996"
    height="1526"
    data-path="portal/assets/entity-overlays/entity-overlays-empty-form.jpg"
  />
</Frame>

When all overlays are added, hit `Save` and a confirmation will pop up.

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/FZ08uNumGsfd2d93/portal/assets/entity-overlays/entity-overlays-filled-form.jpg?fit=max&auto=format&n=FZ08uNumGsfd2d93&q=85&s=9bca0c34013565622cdf501145a86870"
    alt="Overlay filled
form"
    width="1986"
    height="1588"
    data-path="portal/assets/entity-overlays/entity-overlays-filled-form.jpg"
  />
</Frame>

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.