From 89a7cf73e131e41dc7e45d5dacf7d2639a6289be Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Fri, 31 Oct 2025 13:35:20 +0530 Subject: [PATCH 1/9] Templates lifecycle management --- .../assembly-configuring-templates.adoc | 1 + ...-origin-and-software-template-version.adoc | 12 +++++ ...ance-and-software-template-versioning.adoc | 49 +++++++++++++++++++ ...iewing-software-template-dependencies.adoc | 12 +++++ titles/customizing/master.adoc | 3 ++ 5 files changed, 77 insertions(+) create mode 100644 assemblies/assembly-tracking-component-origin-and-software-template-version.adoc create mode 100644 modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc create mode 100644 modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc diff --git a/assemblies/assembly-configuring-templates.adoc b/assemblies/assembly-configuring-templates.adoc index 6acafde1a2..0c3c4440f7 100644 --- a/assemblies/assembly-configuring-templates.adoc +++ b/assemblies/assembly-configuring-templates.adoc @@ -20,6 +20,7 @@ include::modules/customizing-templates/proc-searching-and-filtering-software-tem include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1] include::modules/customizing-templates/proc-versioning-software-templates.adoc[leveloffset=+1] include::modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc[leveloffset=+1] +include::assembly-tracking-component-origin-and-software-template-version.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources diff --git a/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc b/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc new file mode 100644 index 0000000000..6471f8f8ed --- /dev/null +++ b/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="tracking-component-origin-and-software-template-version"] += Tracking Component origin and Software Template version + +Platform engineers use custom actions within the Software Template scaffolding process to establish and track the dependency link between a generated entity (Component or Resource) and its source template. This relationship is called scaffolding provenance. + +Platform administrators use the existing custom actions `catalog:scaffolded-from` and `catalog:template:version` in the scaffolder backend module. These actions track the template version and the corresponding entity version, which simplifies lifecycle management. + +include::modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc[leveloffset=+1] + +include::modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc new file mode 100644 index 0000000000..02bb6e52a1 --- /dev/null +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -0,0 +1,49 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-configuring-provenance-and-software-template-versioning_{context}"] += Configuring provenance and Software Template versioning {product} + +As a platform engineer, you must modify the Software Template YAML definition to ensure the required provenance information is added during the scaffolding process. + +.Prerequisites + +* You have administrator rights to {product}. + +.Procedure + +. Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the `catalog:scaffolded-from` action. This action links the resulting catalog entity back to the source template. +. Optional: To track the template version (for example, v1.0 versus v1.5), include the `catalog:template:version` action in the `steps` section. ++ +[NOTE] +==== +This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. +==== ++ +[source,yaml] +---- +# Example: Adding the versioning action to the steps section +steps: + - id: create-version-annotation + name: Create Template Version Annotation + action: catalog:template:version + input: + templateVersion: ${{ parameters.version }} # Reads the version parameter + - ... other steps ... +---- + +. Modify the `catalog.rules` and `catalog.locations` sections in your `{product} app-config.yaml` file to register and import the updated Software Template into your {product-very-short} instance. + +.Verification + +After creating a component with the updated template, verify the provenance annotations in the resulting Catalog Entity YAML. + +. In the {product} navigation menu, go to *Catalog* and locate the newly created catalog component. +. To view the underlying data that links the entity to the template, select the **INSPECT ENTITY** option. +. To verify provenance annotations, complete the following steps: +.. Select the *YAML Raw* or *JSON Raw* view and verify the presence of the data item for the `scaffoldedFrom` link. +.. Optional: If versioning was included, verify the presence of the `backstage.io/template-version` annotation. ++ +[NOTE] +==== +If you publish the catalog component to an external repository (such as Git), the component file in that repository must also contain the `backstage.io/template-version` annotation. +==== \ No newline at end of file diff --git a/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc b/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc new file mode 100644 index 0000000000..75a261591b --- /dev/null +++ b/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-viewing-software-template-dependencies_{context}"] += Viewing Software Template dependencies + +As a developer, you can track which entities were created from a specific Software Template. When a platform engineer configures provenance on a template, you can quickly identify the complete dependency and impact map of that template by viewing all linked components and resources in the Catalog. + +.Procedure +To view all components created from a specific template, complete the following steps: + +. In the {product} navigation menu, click *Catalog*, use the filters to find and select the Software Template you wish to inspect. +. In the Software Template detail page, click the *Dependencies* tab. This view lists all catalog entities (components, resources, systems, etc.) that reference this template, including any version information if configured. \ No newline at end of file diff --git a/titles/customizing/master.adoc b/titles/customizing/master.adoc index d5c480b50e..fcb657cda0 100644 --- a/titles/customizing/master.adoc +++ b/titles/customizing/master.adoc @@ -25,11 +25,13 @@ include::assemblies/assembly-about-software-catalogs.adoc[leveloffset=+1] include::assemblies/assembly-customizing-the-learning-paths.adoc[leveloffset=+1] + include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1] include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1] + include::assemblies/assembly-configuring-the-quickstarts.adoc[leveloffset=+1] @@ -44,4 +46,5 @@ include::assemblies/assembly-customizing-the-homepage.adoc[leveloffset=+1] include::assemblies/assembly-customizing-the-quick-access-card.adoc[leveloffset=+1] + include::modules/customizing/proc-customizing-rhdh-metadata-card.adoc[leveloffset=+1] From 404431e6d26dbfbda681ce2ccacb4cda5a368db9 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 10:16:53 +0530 Subject: [PATCH 2/9] Added the specific catalog rules --- ...ance-and-software-template-versioning.adoc | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index 02bb6e52a1..b5288ed496 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -31,7 +31,24 @@ steps: - ... other steps ... ---- -. Modify the `catalog.rules` and `catalog.locations` sections in your `{product} app-config.yaml` file to register and import the updated Software Template into your {product-very-short} instance. +. In your `{product} app-config.yaml` file, modify the `catalog.rules` section to include a rule for Software Templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example: ++ +[source,yaml] +---- +# ... +catalog: + rules: + - allow: [Template] + locations: + - type: url + target: https:///example-template.yaml +# ... +---- +where: + +`catalog.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. +`catalog.locations.type`:: If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type. +`catalog.locations.target`:: Specify the URL for the template. .Verification From 4267c4df532046ba1e8ed409ab8c138b91b0e30c Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 19:45:13 +0530 Subject: [PATCH 3/9] Incorporated Frank's comment --- ...iguring-provenance-and-software-template-versioning.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index b5288ed496..b2eacfe407 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -37,11 +37,11 @@ steps: ---- # ... catalog: - rules: - - allow: [Template] locations: - type: url - target: https:///example-template.yaml + target: https:///example-template.yaml + rules: + - allow: [Template] # ... ---- where: From 2756bd4509429688b652bdcadf3626a95c168527 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 20:01:35 +0530 Subject: [PATCH 4/9] Minor change --- ...ance-and-software-template-versioning.adoc | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index b2eacfe407..b9c492f454 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -14,11 +14,6 @@ As a platform engineer, you must modify the Software Template YAML definition to . Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the `catalog:scaffolded-from` action. This action links the resulting catalog entity back to the source template. . Optional: To track the template version (for example, v1.0 versus v1.5), include the `catalog:template:version` action in the `steps` section. + -[NOTE] -==== -This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. -==== -+ [source,yaml] ---- # Example: Adding the versioning action to the steps section @@ -30,8 +25,13 @@ steps: templateVersion: ${{ parameters.version }} # Reads the version parameter - ... other steps ... ---- ++ +[NOTE] +==== +This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. +==== -. In your `{product} app-config.yaml` file, modify the `catalog.rules` section to include a rule for Software Templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example: +. In your `{product} {my-app-config-file}` file, modify the `catalog.rules` section to include a rule for Software Templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example: + [source,yaml] ---- @@ -46,9 +46,15 @@ catalog: ---- where: -`catalog.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. `catalog.locations.type`:: If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type. `catalog.locations.target`:: Specify the URL for the template. +`catalog.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. ++ +[NOTE] +==== +If Software Templates do not appear in the Catalog after this configuration, you must include the `Template` entity type in your application global `catalog.rules.allow` list, alongside any other existing catalog entity types. +==== + .Verification From 6d7a81ec4e16e07d01fe246c22a703ef5fa5dc52 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 20:03:57 +0530 Subject: [PATCH 5/9] Minor change --- ...configuring-provenance-and-software-template-versioning.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index b9c492f454..8deb32a043 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -31,7 +31,7 @@ steps: This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. ==== -. In your `{product} {my-app-config-file}` file, modify the `catalog.rules` section to include a rule for Software Templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example: +. In your `{product} {my-app-config-file}` file, configure the `catalog.locations` section to point to the Software Template that you want to add and add a granular rule to the location to allow for Software Templates, as shown in the following example:: + [source,yaml] ---- From f2b33db4618180581c8b18b4c3a8b00d0c3d9bbe Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 20:21:21 +0530 Subject: [PATCH 6/9] Minor change --- ...uring-provenance-and-software-template-versioning.adoc | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index 8deb32a043..b634a22c57 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -31,7 +31,7 @@ steps: This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. ==== -. In your `{product} {my-app-config-file}` file, configure the `catalog.locations` section to point to the Software Template that you want to add and add a granular rule to the location to allow for Software Templates, as shown in the following example:: +. In your `{product} {my-app-config-file}` file, configure the `catalog.locations` section to point to the Software Template that you want to add. You might need to add `Template` to the global `catalog.rules.allow` list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example:: + [source,yaml] ---- @@ -49,12 +49,6 @@ where: `catalog.locations.type`:: If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type. `catalog.locations.target`:: Specify the URL for the template. `catalog.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. -+ -[NOTE] -==== -If Software Templates do not appear in the Catalog after this configuration, you must include the `Template` entity type in your application global `catalog.rules.allow` list, alongside any other existing catalog entity types. -==== - .Verification From 92f9902cba29af739385d535d61ffd7ef5c93b80 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 20:28:19 +0530 Subject: [PATCH 7/9] typo --- ...configuring-provenance-and-software-template-versioning.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index b634a22c57..8d5df32ec8 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -48,7 +48,7 @@ where: `catalog.locations.type`:: If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type. `catalog.locations.target`:: Specify the URL for the template. -`catalog.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. +`catalog.locations.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. .Verification From 8302957a8e0e59ea079f830bc204e7fb27811342 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 3 Nov 2025 20:40:17 +0530 Subject: [PATCH 8/9] Minor comment --- ...onfiguring-provenance-and-software-template-versioning.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index 8d5df32ec8..e223407a08 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -18,6 +18,9 @@ As a platform engineer, you must modify the Software Template YAML definition to ---- # Example: Adding the versioning action to the steps section steps: + - id: create-provenance-annotation + name: Append the entityRef of this template to the entityRef + action: catalog:scaffolded-from - id: create-version-annotation name: Create Template Version Annotation action: catalog:template:version From 490b1ab437ae71e7eae050718ba784723f971a8a Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Tue, 4 Nov 2025 00:01:49 +0530 Subject: [PATCH 9/9] Incorporated Judy's comments --- ...-origin-and-software-template-version.adoc | 2 +- ...ance-and-software-template-versioning.adoc | 20 +++++++++++-------- ...iewing-software-template-dependencies.adoc | 2 +- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc b/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc index 6471f8f8ed..2385446470 100644 --- a/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc +++ b/assemblies/assembly-tracking-component-origin-and-software-template-version.adoc @@ -5,7 +5,7 @@ Platform engineers use custom actions within the Software Template scaffolding process to establish and track the dependency link between a generated entity (Component or Resource) and its source template. This relationship is called scaffolding provenance. -Platform administrators use the existing custom actions `catalog:scaffolded-from` and `catalog:template:version` in the scaffolder backend module. These actions track the template version and the corresponding entity version, which simplifies lifecycle management. +Platform administrators use custom actions such as `catalog:scaffolded-from` and `catalog:template:version` in the scaffolder backend module to track the template version and the corresponding entity version, which simplifies lifecycle management. include::modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc[leveloffset=+1] diff --git a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc index e223407a08..cb4feb09be 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc @@ -12,11 +12,10 @@ As a platform engineer, you must modify the Software Template YAML definition to .Procedure . Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the `catalog:scaffolded-from` action. This action links the resulting catalog entity back to the source template. -. Optional: To track the template version (for example, v1.0 versus v1.5), include the `catalog:template:version` action in the `steps` section. +. Optional: To track the template version (for example, v1.0 versus v1.5), include the `catalog:template:version` action in the `steps` section. The following code block is an example to adding versioning action to the `steps` section: + [source,yaml] ---- -# Example: Adding the versioning action to the steps section steps: - id: create-provenance-annotation name: Append the entityRef of this template to the entityRef @@ -25,16 +24,20 @@ steps: name: Create Template Version Annotation action: catalog:template:version input: - templateVersion: ${{ parameters.version }} # Reads the version parameter + templateVersion: ${{ parameters.version }} - ... other steps ... ---- + +where: + +`steps:input:templateVersion`:: Reads the version parameter ++ [NOTE] ==== -This action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. +The `catalog:template:version` action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity. ==== -. In your `{product} {my-app-config-file}` file, configure the `catalog.locations` section to point to the Software Template that you want to add. You might need to add `Template` to the global `catalog.rules.allow` list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example:: +. In your {product} `{my-app-config-file}` file, configure the `catalog.locations` section to point to the Software Template that you want to add. You might need to add `Template` to the global `catalog.rules.allow` list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example: + [source,yaml] ---- @@ -47,11 +50,12 @@ catalog: - allow: [Template] # ... ---- ++ where: -`catalog.locations.type`:: If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type. -`catalog.locations.target`:: Specify the URL for the template. -`catalog.locations.rules.allow`:: To allow new Software Templates to be added to the catalog, you must add a `Template` rule. +`catalog.locations.type`:: Enter the `url` type if you are importing templates from a repository, such as GitHub or GitLab. +`catalog.locations.target`:: Enter the URL for the template. +`catalog.locations.rules.allow`:: Enter the `Template` rule to allow new Software Templates to be added to the catalog. .Verification diff --git a/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc b/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc index 75a261591b..9087e5421a 100644 --- a/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc +++ b/modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc @@ -9,4 +9,4 @@ As a developer, you can track which entities were created from a specific Softwa To view all components created from a specific template, complete the following steps: . In the {product} navigation menu, click *Catalog*, use the filters to find and select the Software Template you wish to inspect. -. In the Software Template detail page, click the *Dependencies* tab. This view lists all catalog entities (components, resources, systems, etc.) that reference this template, including any version information if configured. \ No newline at end of file +. In the Software Template detail page, click the *Dependencies* tab. This view lists all catalog entities such as components, resources, and systems that reference this template, including any version information if configured. \ No newline at end of file