backstage: $text substitutions in catalog descriptor files do not support local files

Expected Behavior

According to the documentation for $text, $json and $yaml, we should be able to use $text: <local file path> to substitute catalog-info.yaml. This is especially useful for spec.definition in API entities.

Example

kind: API
...
spec:
  type: openapi
  definition:
    $text: ./api-definition.yaml

Actual Behavior

Catalog throws an error when processing API entities where $test is either a relative local path or an absolute local path. It works only with URLs.

2022-10-28T12:16:01.069Z catalog warn Processor PlaceholderProcessor threw an error while preprocessing; caused by Error:
Placeholder $text could not form a URL out of /Users/himanshumishra/workspace/backstage/packages/catalog-
model/examples/apis/petstore-api.yaml and ./my-api-definition.yaml, Error: URL parsing failed. type=plugin entity=api:default/petstore

Steps to Reproduce

Update an API definition where $text points to a local file path

Context

Looking into the processor code, there is a comment saying the support for relative file is not there.

Your Environment

Browser Information:
Output of yarn backstage-cli info:

master branch of this repository

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 17 (8 by maintainers)

Most upvoted comments

Hey @JefferoNW - as @Rugvip said above, if the source of your catalog-info.yaml is a local file path (instead of a URL), then relative paths like ../api.yaml is not supported by the processor currently. So maybe try ingesting that catalog-info.yaml from a URL - I guess it will work. The latter is anyway what you would end up doing in a stable scenario.

OrkoHunter on Jan 11, 2023

@JefferoNW I can only tell that our Backstage instance hosted on Azure Kubernetes Service (AKS), scrawls for catalog-info.yamls in our project repositories on our self-hosted GitLab (via URL ofc) and is able to register API definitions that come from a “local” file, that is also part of the git version control (thus has also a URL).

doemEINS on Jan 11, 2023

@OrkoHunter interestingly, I just had success with registering an API/Service in Backstage with the following in catalog-info.yaml:

kind: API
[...]
spec:
  type: openapi
  definition:
    $text: ./src/main/resources/oas/swagger.yaml

doemEINS on Nov 10, 2022

Sorry for sending you down the wrong path @OrkoHunter. I wonder why the person on Discord said it worked for them 🤔

awanlin on Nov 1, 2022