Merge branch 'master' of https://github.com/backstage/backstage into feat/reference-external-docs

docs/backend-system/core-services/01-index.md

@@ -373,7 +373,7 @@ createBackendPlugin({
         discovery: coreServices.discovery,
       },
       async init({ discovery }) {
-        const url = await discoverty.getBaseUrl('derp'); // can also use discovery.getBaseUrl to retrieve external URL
+        const url = await discovery.getBaseUrl('derp'); // can also use discovery.getExternalBaseUrl to retrieve external URL
         const response = await fetch(`${url}/hello`);
       },
     });

docs/features/software-catalog/api.md

@@ -279,7 +279,65 @@ where the `items` array has _the same length_ and _the same order_ as the input
 
 ## Locations
 
-TODO
+### `GET /locations`
+
+Lists locations.
+
+Response type is JSON, on the form
+
+```json
+[
+  {
+    "data": {
+      "id": "b9784c38-7118-472f-9e22-5638fc73bab0",
+      "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",
+      "type": "url"
+    }
+  }
+]
+```
+
+### `POST /locations`
+
+Adds a location to be ingested by the catalog.
+
+If successful the response code will be `HTTP/1.1 201 Created` and a JSON on the form
+
+```json
+{
+  "entities": [],
+  "location": {
+    "id": "b9784c38-7118-472f-9e22-5638fc73bab0",
+    "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",
+    "type": "url"
+  }
+}
+```
+
+If the location already exists the response will be `HTTP/1.1 409 Conflict` and a JSON on the form
+
+```json
+{
+  "error": {
+    "message": "Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists",
+    "name": "ConflictError",
+    "stack": "ConflictError: Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists\n..."
+  },
+  "request": {
+    "method": "POST",
+    "url": "/locations"
+  },
+  "response": {
+    "statusCode": 409
+  }
+}
+```
+
+Supports the `?dryRun=true` query parameter, which will perform validation and not write anything to the database. In the event of successfully passing validation, the `entities` field of the response JSON will be populated with entities present in the location.
+
+### `DELETE /locations/<uid>`
+
+Delete a location by its id. On success response code will be `HTTP/1.1 204 No Content`.
 
 ## Other
 

docs/features/software-catalog/configuration.md

@@ -130,7 +130,36 @@ In short entities can become orphaned through multiple means, such as when a cat
 
 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.
 
-```
+```yaml
 catalog:
   orphanStrategy: delete
 ```
+
+## Processing Interval
+
+The [processing loop](https://backstage.io/docs/features/software-catalog/life-of-an-entity) is
+responsible for running your registered processors on all entities, on a certain
+interval. That interval can be configured with the `processingInterval`
+app-config parameter.
+
+```yaml
+catalog:
+  processingInterval: { minutes: 45 }
+```
+
+The value is a duration object, that has one or more of the fields `years`,
+`months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, and `milliseconds`.
+You can combine them, for example as `{ hours: 1, minutes: 15 }` which
+essentially means that you want the processing loop to visit entities roughly
+once every 75 minutes.
+
+Note that this is only a suggested minimum, and the actual interval may be
+longer. Internally, the catalog will scale up this number by a small factor and
+choose random numbers in that range to spread out the load. If the catalog is
+overloaded and cannot process all entities during the interval, the time taken
+between processing runs of any given entity may also be longer than specified
+here.
+
+Setting this value too low risks exhausting rate limits on external systems that
+are queried by processors, such as version control systems housing catalog-info
+files.

docs/features/techdocs/configuration.md

@@ -167,6 +167,12 @@ techdocs:
       # (Required) Azure Blob Storage Container Name
       containerName: 'techdocs-storage'
 
+      # (Optional) Azure blob storage connection string.
+      # Can be useful for local testing through azurite
+      # Defaults to undefined
+      # if provided, takes higher priority, 'techdocs.publisher.azureBlobStorage.credentials' will become irrelevant
+      connectionString: ''
+
       # (Required) An account name is required to write to a storage blob container.
       # https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
       credentials: