From 6018263df03eeee07446fc1416451e8775ca1ecf Mon Sep 17 00:00:00 2001 From: Crevil Date: Fri, 26 Mar 2021 20:46:55 +0100 Subject: [PATCH] Add documentation for readonly catalog This change contains documentation for the readonly configuration of the catalog (80e92b8f48843e079743944af6c20b3eaf42e3d9 #5034). Signed-off-by: Crevil --- .../software-catalog/configuration.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index fb5d664f16..1afdff418a 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -91,3 +91,28 @@ the catalog: catalog: rules: [] ``` + +## Readonly mode + +Processors provides a good way to automate ingestion of entities when combined +with [Static Location Configuration](#static-location-configuration) or a +discovery processor like +[GitHub Discovery](../../integrations/github/discovery.md). To enforce usage of +processors to locate entities we can configure the catalog into `readonly` mode. +This configuration disables the mutating backend catalog APIs and disallows +users from registering new entities at run-time. + +```yaml +catalog: + readonly: true +``` + +> **Note that any plugin relying on the catalog API for creating, updating and +> deleting entities will not work in this mode.** + +A common use case for this configuration is when organizations have a remote +source that should be mirrored into backstage. If we want backstage to be a +mirror of this remote source we cannot allow users to also register entities +with e.g. +[catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import) +plugin.