From b74d028214a0dbe0cecb11fafd926363fd7f98ca Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Tue, 15 Aug 2023 16:47:36 +0200 Subject: [PATCH 1/3] Add docs about config option to auto clean up orphans Signed-off-by: Vladimir Masarik --- .changeset/rich-apes-mix.md | 5 +++++ docs/features/software-catalog/life-of-an-entity.md | 13 +++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 .changeset/rich-apes-mix.md diff --git a/.changeset/rich-apes-mix.md b/.changeset/rich-apes-mix.md new file mode 100644 index 0000000000..3ba092c282 --- /dev/null +++ b/.changeset/rich-apes-mix.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog': patch +--- + +Add docs about config option to auto clean up orphans diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 618923289e..583be7df20 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -222,7 +222,8 @@ either, it becomes _orphaned_. The end result is as follows: - The stitching process injects a `backstage.io/orphan: 'true'` annotation on the child entity. - The child entity is _not_ removed from the catalog, but stays around until - explicitly deleted via the catalog API, or "reclaimed" by the original parent + 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. - The catalog page in Backstage for the child entity detects the new annotation and informs users about the orphan status. @@ -259,9 +260,13 @@ 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. -It is possible to use the catalog API to build automated "reaper" systems that -finally delete entities that are orphaned. This is however not something that's -provided out of the box. +However, if you want to delete orphaned entities automatically anyway, you can +enable the automated clean up with the following app-config option. + +``` +catalog: + orphanStrategy: delete +``` ## Implicit Deletion From c1d383ad473874c46cf17982174e5cbb5065f4dc Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Mon, 21 Aug 2023 19:51:54 +0200 Subject: [PATCH 2/3] Remove useless changeset Signed-off-by: Vladimir Masarik --- .changeset/rich-apes-mix.md | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 .changeset/rich-apes-mix.md diff --git a/.changeset/rich-apes-mix.md b/.changeset/rich-apes-mix.md deleted file mode 100644 index 3ba092c282..0000000000 --- a/.changeset/rich-apes-mix.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-catalog': patch ---- - -Add docs about config option to auto clean up orphans From 683b3318a86962647c5b54da67a0baff0b6abe30 Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Mon, 21 Aug 2023 20:47:31 +0200 Subject: [PATCH 3/3] update configuration text as well Signed-off-by: Vladimir Masarik --- docs/features/software-catalog/configuration.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 5abd266099..2f5edc3696 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -123,3 +123,14 @@ source that should be mirrored into Backstage. To make Backstage a mirror of 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 + +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). + +However, if you do with to automatically remove the orphaned entities, you can use the following configuration, and everything with an orphaned entity tag will be eventually deleted. + +``` +catalog: + orphanStrategy: delete +```