Skip to main content

Catalog

The Catalog integration is installed by default and exposes information from Backstage's Software Catalog as facts to Soundcheck.

This enables the creation of checks against an entity's metadata, to ensure that it is in compliance with your organizations standards and best practices.

It supports the collection of the following fact:

  • entity_descriptor - contains information about Backstage's Software Catalog entity.

Prerequisites​

Configure Software Catalog in Backstage​

Software Catalog is configured at the root level of app-config.yaml. Here's an example configuration for Software Catalog:

catalog:
  locations:
    - type: url
      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml

Consult the Software Catalog Configuration documentation for additional details on setting up the Software Catalog.

Catalog Fact Collector Configuration​

The collection of Catalog facts is driven by configuration. To learn more about the configuration, consult the Defining Catalog Fact Collectors section.

Catalog Fact Collector can be configured via YAML or No-Code UI. If you configure it via both YAML and No-Code UI, the configurations will be merged. It's preferable to choose a single source for the Fact Collectors configuration (either No-Code UI or YAML) to avoid confusing merge results.

No-Code UI Configuration Option​

  1. Make sure the prerequisite Configure Software Catalog in Backstage is completed.

  2. To enable the Catalog Integration, go to Soundcheck > Integrations > Software Catalog and click the Configure button. To learn more about the No-Code UI config, see the Configuring a fact collector (integration) via the no-code UI.

Catalog Integration

YAML Configuration Option​

Add a soundcheck.collectors.catalog.collects field to the app-config.yaml. A simple example Catalog fact collector is listed below.

# app-config.yaml
soundcheck:
  collectors:
    catalog:
      collects:
        type: 'entity_descriptor'
        filter:
          kind: component
        exclude:
          spec.type: documentation
        cache: false

Defining Catalog Fact Collectors​

This section describes the data shape and semantics of Catalog Fact Collectors.

Shape Of A Catalog Fact Collector​

The following is an example of a Catalog Fact Collector YAML configuration:

soundcheck:
  collectors:
    catalog:
      collects:
        type: 'entity_descriptor'
        filter:
          kind: component
        exclude:
          spec.type: documentation
        cache: false

Below are the details for each field.

type [required]​

The type of the collector: entity_descriptor.

frequency [optional]​

The frequency at which the fact collection should be executed. Possible values are either a cron expression { cron: ... } or HumanDuration. If not provided, the fact will only be collected on demand.

Example:

frequency:
  minutes: 10

initialDelay [optional]​

The amount of time that should pass before the first invocation happens. Possible values are either a cron expression { cron: ... } or HumanDuration.

Example:

initialDelay:
  seconds: 30

batchSize [optional]​

The number of entities to collect facts for at once. Optional, the default value is 1.

Example:

batchSize: 100

filter [optional]​

A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. If not provided, the fact will be collected for all entities.

exclude [optional]​

Entities matching this filter will be skipped during the fact collection process. Can be used in combination with filter. Matches the filter format used by the Catalog API.

filter:
  - kind: component
exclude:
  - spec.type: documentation

cache [optional]​

If the collected facts should be cached, and if so for how long. Possible values are either true or false or a nested { duration: HumanDuration } field. If not provided, the fact will not be cached.

Example:

cache:
  duration:
    hours: 24

Shape of A Catalog Fact​

The shape of a Catalog Fact is based on the Fact Schema.

The following is an example of the collected Catalog fact:

factRef: catalog:default/entity_descriptor
entityRef: component:default/artist-web
data:
  apiVersion: backstage.io/v1alpha1
  kind: Component
  metadata:
    name: artist-web
    description: The place to be, for great artists
    labels:
      example.com/custom: custom_label_value
    annotations:
      example.com/service-discovery: artistweb
      circleci.com/project-slug: github/example-org/artist-website
    tags:
      - java
    links:
      - url: https://admin.example-org.com
        title: Admin Dashboard
        icon: dashboard
        type: admin-dashboard
  spec:
    type: website
    lifecycle: production
    owner: artist-relations-team
    system: public-websites
timestamp: 2023-02-20T13:50:35Z

See Software Catalog's descriptor format documentation for more details about the shape of an entity.

Shape of A Catalog Fact Check​

The shape of a Catalog Fact Check matches the Shape of a Fact Check.

The following is an example of the Catalog fact check:

- id: has_required_tags
  rule:
    any:
      - factRef: catalog:default/entity_descriptor
        path: $.metadata.tags
        operator: contains
        value: java
      - factRef: catalog:default/entity_descriptor
        path: $.metadata.tags
        operator: contains
        value: data
  schedule:
    frequency:
      cron: '* * * * *'
    filter:
      kind: 'Component'
  passedMessage: |
    Tag found, check passed.
  failedMessage: |
    No `java` or `data` tag found, check failed.