From b0f286b83cee6dc513b56e0f069249874217988b Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Tue, 24 Nov 2020 16:02:44 +0100 Subject: [PATCH 1/3] Document Substitutions In The Descriptor Format --- .../software-catalog/descriptor-format.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 60f1901807..ff2f92beab 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -93,6 +93,41 @@ significance and have reserved purposes and distinct shapes. See below for details about these fields. +## Substitutions In The Descriptor Format + +The descriptor format supports substitutions using `$text`, `$json`, and +`$yaml`. + +Placeholders like `$json: https://example.com/entity.json` are substituded by +the content of the referenced file. Files can be referenced from any configured +integration similar to locations by passing an absolute URL. It's also possible +to reference relative files like `./referenced.yaml` from the same location. +There are three different types of placeholders: + +- `$text`: Interprets the content of the referenced file as plain text and embed + it as a string. +- `$json`: Interprets the content of the referenced file as JSON and embed the + parsed structure. +- `$yaml`: Interprets the content of the referenced file as YAML and embed the + parsed structure. + +For example, this can be used to load the definition of an API entity from a web +server and embed it into the entity: + +```yaml +apiVersion: backstage.io/v1alpha1 +kind: API +metadata: + name: petstore + description: The Petstore API +spec: + type: openapi + lifecycle: production + owner: petstore@example.com + definition: + $text: https://petstore.swagger.io/v2/swagger.json +``` + ## Common to All Kinds: The Envelope The root envelope object has the following structure. From 6579b08725d97309d3528f9d4159d120007ef0de Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Tue, 24 Nov 2020 16:06:30 +0100 Subject: [PATCH 2/3] Link to substitutions instead of duplicating the content --- .../software-catalog/descriptor-format.md | 2 +- .../well-known-annotations.md | 19 +++---------------- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index ff2f92beab..7171e0c7b8 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -98,7 +98,7 @@ See below for details about these fields. The descriptor format supports substitutions using `$text`, `$json`, and `$yaml`. -Placeholders like `$json: https://example.com/entity.json` are substituded by +Placeholders like `$json: https://example.com/entity.json` are substituted by the content of the referenced file. Files can be referenced from any configured integration similar to locations by passing an absolute URL. It's also possible to reference relative files like `./referenced.yaml` from the same location. diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 7d16427a3c..3627c74b9a 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -238,22 +238,9 @@ annotation, with the same value format. ### backstage.io/definition-at-location -This annotation allowed to load the API definition from another location. Now -placeholders can be used instead: - -``` -apiVersion: backstage.io/v1alpha1 -kind: API -metadata: - name: petstore - description: The Petstore API -spec: - type: openapi - lifecycle: production - owner: petstore@example.com - definition: - $text: https://petstore.swagger.io/v2/swagger.json -``` +This annotation allowed to load the API definition from another location. Use +[substitution](./descriptor-format.md#substitutions-in-the-descriptor-format) +instead. ## Links From 11e4a9cbe87677752c21cb37e5b9c587c21628d5 Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Tue, 24 Nov 2020 16:23:41 +0100 Subject: [PATCH 3/3] Integrate review comments --- .../features/software-catalog/descriptor-format.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 7171e0c7b8..f1d426f407 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -102,17 +102,19 @@ Placeholders like `$json: https://example.com/entity.json` are substituted by the content of the referenced file. Files can be referenced from any configured integration similar to locations by passing an absolute URL. It's also possible to reference relative files like `./referenced.yaml` from the same location. -There are three different types of placeholders: +Relative references are handled relative to the folder of the +`catalog-info.yaml` that contains the placeholder. There are three different +types of placeholders: -- `$text`: Interprets the content of the referenced file as plain text and embed - it as a string. -- `$json`: Interprets the content of the referenced file as JSON and embed the +- `$text`: Interprets the contents of the referenced file as plain text and + embeds it as a string. +- `$json`: Interprets the contents of the referenced file as JSON and embeds the parsed structure. -- `$yaml`: Interprets the content of the referenced file as YAML and embed the +- `$yaml`: Interprets the contents of the referenced file as YAML and embeds the parsed structure. For example, this can be used to load the definition of an API entity from a web -server and embed it into the entity: +server and embed it as a string in the field `spec.definition`: ```yaml apiVersion: backstage.io/v1alpha1