diff --git a/.changeset/quiet-islands-learn.md b/.changeset/quiet-islands-learn.md new file mode 100644 index 0000000000..7e2ad6bdf1 --- /dev/null +++ b/.changeset/quiet-islands-learn.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Add configuration parameters for deferred stitcher diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 78643420df..2d86811b14 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -165,7 +165,7 @@ catalog: ## Processing Interval -The [processing loop](https://backstage.io/docs/features/software-catalog/life-of-an-entity) is +The [processing loop](./life-of-an-entity.md#processing) 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. @@ -192,13 +192,43 @@ 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. +## Stitching strategy + +[Stitching](./life-of-an-entity.md#stitching) finalizes the entity. It can be run in +two modes: + +- `immediate` - performs stitching in-band immediately when needed +- `deferred` - performs the stitching asynchronously + +It can be configured with the `stitchingStrategy` app-config parameter. + +```yaml title="app-config.yaml" +catalog: + stitchingStrategy: immediate +``` + +For the `deferred` mode you can set up additional parameters to further tune the process, +by setting the following parameters: + +- `pollingInterval` - the interval between polling for entities that need stitching +- `stitchTimeout` - the maximum time to wait for an entity to be stitched + +These parameters accept a duration object, similar to the `processingInterval` parameter. + +```yaml title="app-config.yaml" +catalog: + stitchingStrategy: deferred + pollingInterval: { seconds: 1 } + stitchTimeout: { minutes: 1 }; +``` + ## Subscribing to Catalog Errors Catalog errors are published to the [events plugin](https://github.com/backstage/backstage/tree/master/plugins/events-node): `@backstage/plugin-events-node`. You can subscribe to events and respond to errors, for example you may wish to log them. The first step is to add the events backend plugin to your Backstage application. Navigate to your Backstage application directory and add the plugin package. -```ts title="From your Backstage root directory" +```bash title="From your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-events-backend ``` @@ -214,7 +244,7 @@ If you want to log catalog errors you can install the `@backstage/plugin-catalog Install the catalog logs module. -```ts title="From your Backstage root directory" +```bash title="From your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs ``` diff --git a/plugins/catalog-backend/config.d.ts b/plugins/catalog-backend/config.d.ts index 265d78b496..8bab83d4b4 100644 --- a/plugins/catalog-backend/config.d.ts +++ b/plugins/catalog-backend/config.d.ts @@ -156,6 +156,10 @@ export interface Config { | { /** Defer stitching to be performed asynchronously */ mode: 'deferred'; + /** Polling interval for tasks in seconds */ + pollingInterval?: HumanDuration; + /** How long to wait for a stitch to complete before giving up in seconds */ + stitchTimeout?: HumanDuration; }; /** diff --git a/plugins/catalog-backend/src/stitching/types.ts b/plugins/catalog-backend/src/stitching/types.ts index 9f7a5652dd..7064dd1a1c 100644 --- a/plugins/catalog-backend/src/stitching/types.ts +++ b/plugins/catalog-backend/src/stitching/types.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { Config } from '@backstage/config'; +import { Config, readDurationFromConfig } from '@backstage/config'; import { HumanDuration } from '@backstage/types'; /** @@ -66,11 +66,23 @@ export function stitchingStrategyFromConfig(config: Config): StitchingStrategy { mode: 'immediate', }; } else if (strategyMode === 'deferred') { - // TODO(freben): Make parameters configurable + const pollingIntervalKey = 'catalog.stitchingStrategy.pollingInterval'; + const stitchTimeoutKey = 'catalog.stitchingStrategy.stitchTimeout'; + + const pollingInterval = config.has(pollingIntervalKey) + ? readDurationFromConfig(config, { + key: pollingIntervalKey, + }) + : { seconds: 1 }; + const stitchTimeout = config.has(stitchTimeoutKey) + ? readDurationFromConfig(config, { + key: stitchTimeoutKey, + }) + : { seconds: 60 }; return { mode: 'deferred', - pollingInterval: { seconds: 1 }, - stitchTimeout: { seconds: 60 }, + pollingInterval: pollingInterval, + stitchTimeout: stitchTimeout, }; }