From f546bb3862893d85a7f3cfdf84005d2fd603065e Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Mon, 31 Aug 2020 01:05:54 +0200
Subject: [PATCH] docs: added catalog configuration docs

---
 .../software-catalog/configuration.md         | 60 +++++++++++++++++++
 docs/features/software-catalog/index.md       | 16 +++++
 mkdocs.yml                                    |  1 +
 3 files changed, 77 insertions(+)
 create mode 100644 docs/features/software-catalog/configuration.md

diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md
new file mode 100644
index 0000000000..77b630d347
--- /dev/null
+++ b/docs/features/software-catalog/configuration.md
@@ -0,0 +1,60 @@
+---
+id: software-catalog-configuration
+title: Catalog Configuration
+---
+
+## Static Location Configuration
+
+To enable declarative catalog setups, it is possible to add locations to the
+catalog via [static configuration](../../conf/index.md). Locations are added to
+the catalog under the `catalog.locations` key, for example:
+
+```yaml
+catalog:
+  locations:
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+```
+
+The locations added through static configuration can not be removed through the
+catalog locations API. To remove the locations, you have to remove them from the
+configuration.
+
+## Catalog Rules
+
+By default the catalog will only allow ingestion of entities with the kind
+`Component` and `API`. In order to allow entities of other kinds to be added,
+you need to add rules to the catalog. Rules are added either in a separate
+`catalog.rules` key, or added to statically configured locations.
+
+For example, given the following configuration:
+
+```yaml
+catalog:
+  rules:
+    - allow: [Component, API]
+    - allow: [System]
+      locations:
+        type: github
+
+  locations:
+    - type: github
+      target: https://github.com/org/example/blob/master/org-data.yaml
+      allow: [Group]
+```
+
+We are able to add entities of kind `Component` or `API` from any location,
+entities of kind `System` from any `github` location, and `Group` entities from
+the `org-data.yaml`, which will also be read as statically configured location.
+
+Note that if the `catalog.rules` key is present it will replace the default
+value, meaning that you need to add rules for `Component` and `API` kinds if you
+want those to be allowed.
+
+The following configuration will reject any kind of entities from being added to
+the catalog:
+
+```yaml
+catalog:
+  rules: []
+```
diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md
index db8c183390..bfc3d53d4d 100644
--- a/docs/features/software-catalog/index.md
+++ b/docs/features/software-catalog/index.md
@@ -79,6 +79,22 @@ All software created through the
 [Backstage Software Templates](../software-templates/index.md) are automatically
 registered in the catalog.
 
+### Static catalog configuration
+
+In addition to manually registering components, it is also possible to register
+components though [static configuration](../../conf/index.md). For example, the
+above example can be added using the following configuration:
+
+```yaml
+catalog:
+  locations:
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+```
+
+More information about catalog configuration can be found
+[here](configuration.md).
+
 ### Updating component metadata
 
 Teams owning the components are responsible for maintaining the metadata about
diff --git a/mkdocs.yml b/mkdocs.yml
index 637e45c0f0..b12c8f81c7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
           - Overview: 'features/software-catalog/index.md'
           - System model: 'features/software-catalog/system-model.md'
           - YAML File Format: 'features/software-catalog/descriptor-format.md'
+          - Configuration: 'features/software-catalog/configuration.md'
           - Extending the model: 'features/software-catalog/extending-the-model.md'
           - External integrations: 'features/software-catalog/external-integrations.md'
           - API: 'features/software-catalog/api.md'