Catalog Configuration
Processors
The catalog has a concept of processors to perform catalog ingestion tasks,
such as reading raw entity data from a remote source, parsing it, transforming
it, and validating it. These processors are configured under the
catalog.processors
configuration key.
Static Location Configuration
The simplest configuration for the catalog, as shown in the default
@backstage/create-app
template, is to declaratively add locations pointing to
YAML files with static configuration.
Locations are added to the catalog under the catalog.locations
key:
catalog:
locations:
- type: url
target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml
The url
type locations are handled by a standard processor included with the
catalog (UrlReaderProcessor
), so no processor configuration is needed. This
processor does however need an integration to
understand how to retrieve a given URL. For the example above, you would need to
configure the GitHub integration to
read files from github.com.
The locations added through static configuration cannot be removed through the catalog locations API. To remove these locations, you must remove them from the configuration.
Syntax errors or other types of errors present in catalog-info.yaml
files will
be logged for investigation. Errors do not cause processing to abort.
When multiple catalog-info.yaml
files with the same metadata.name
property
are discovered, one will be processed and all others will be skipped. This
action is logged for further investigation.
Local File (type: file
) Configurations
In addition to url locations, you can use the file
location type to bring in content from the local file system. You should only use this for local development, test setups, and example data, not for production data.
You are also not able to use placeholders in them like $text
. You can however reference other files relative to the current file. See the full catalog example data set here for an extensive example.
Here is an example pulling in the all.yaml
file from the examples folder. Note the use of ../../
to go up two levels from the current execution path of the backend. This is typically packages/backend/
.
catalog:
locations:
- type: file
target: ../../examples/all.yaml
Integration Processors
Integrations may simply provide a mechanism to handle url
location type for an
external provider or they may also include additional processors out of the
box, such as the GitHub discovery
processor that scans a GitHub organization for
entity descriptor files.
Check the integrations documentation to see what is offered by each integration.