diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 5b293cce1c..3ed027a0a4 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -181,28 +181,30 @@ this remote source, users cannot also register new entities with e.g. the [catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import) plugin. -## Clean up orphaned entities +## Automatic removal of orphaned entities -In short, entities can become orphaned through multiple means, such as when a catalog-info YAML file is moved from one place to another in the version control system without updating the registration in the catalog. For safety reasons, the default behavior is to just tag the orphaned entities, and keep them around. You can read more about orphaned entities [here](life-of-an-entity.md#orphaning). +Entities can become orphaned through multiple means, such as when a catalog-info YAML file is moved from one place to another in the version control system without updating the registration in the catalog. The default behavior is to automatically remove orphaned entities. You can read more about orphaned entities [here](life-of-an-entity.md#orphaning). -However, if you do wish to automatically remove the orphaned entities, you can use the following configuration, and everything with an orphaned entity tag will be eventually deleted. +However, if you wish to keep orphaned entities, you can use the following configuration, and automatic cleanup will be disabled. ```yaml catalog: - orphanStrategy: delete + orphanStrategy: keep ``` -## Clean up entities from orphaned entity providers +## Automatic removal of entities from orphaned entity providers -By default, if an entity provider which has provided entities to the catalog, is no longer configured, then the entities remain in the catalog until they are manually unregistered. +By default, if an entity provider which has provided entities to the catalog is no longer configured, then the entities it provided will be automatically removed. -To remove these entities automatically, you can use the following configuration. +To keep these entities instead, you can use the following configuration. ```yaml catalog: - orphanProviderStrategy: delete + orphanProviderStrategy: keep ``` +If you have had providers installed in the past that ingested entities into the catalog that you want to keep, the recommendation is to add the provider back to the catalog. If you don’t want the provider to run, you can schedule it with a very large interval. + ## Processing Interval The [processing loop](./life-of-an-entity.md#processing) is diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index c16fb8d523..ca4de99734 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -254,8 +254,8 @@ either, it becomes _orphaned_. The end result is as follows: the child entity. - The child entity is _not_ removed from the catalog, but stays around until explicitly deleted via the catalog API, implicitly if `orphanStrategy: delete` - configuration is set, or until it is "reclaimed" by the original parent - or another parent starting to reference it. + configuration is set (the default), or until it is "reclaimed" by the original + parent or another parent starting to reference it. - The catalog page in Backstage for the child entity detects the new annotation and informs users about the orphan status. @@ -282,21 +282,13 @@ Orphaning can occur in several different scenarios. > to inform the owner that something is wrong. But processing and other > behaviors continue as usual. -The reason that the orphaning mechanism exists instead of having an eager -deletion triggered, is safety. Scenarios like these can happen purely by -accident, due to the asynchronous nature of the system and the fallible nature -of humans. In particular when external systems start consuming and relying on -the catalog, there could be substantial consequences to suddenly dropping -entities without explicit owner consent. The catalog therefore takes the stance -that entities that often were added by direct user action should also be deleted -only by direct user action. - -However, if you want to delete orphaned entities automatically anyway, you can -enable the automated clean up with the following app-config option. +The default behavior of the catalog is to automatically remove orphaned +entities. However, if you want to keep them instead, you can disable the +automated cleanup with the following app-config option. ``` catalog: - orphanStrategy: delete + orphanStrategy: keep ``` ## Implicit Deletion