[release-1.8] RHIDP-8627: Templates lifecycle management

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

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 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]
+
+include::modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc[leveloffset=+1]

modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc

@@ -0,0 +1,73 @@
+:_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. The following code block is an example to adding versioning action to the `steps` section:
++
+[source,yaml]
+----
+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
+    input:
+      templateVersion: ${{ parameters.version }}
+  - ... other steps ...
+----
++
+where:
+
+`steps:input:templateVersion`:: Reads the version parameter
++
+[NOTE]
+====
+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:
++
+[source,yaml]
+----
+# ...
+catalog:
+  locations:
+    - type: url 
+      target: https://<repository_url>/example-template.yaml
+      rules:
+        - allow: [Template]
+# ...
+----
++
+where:
+
+`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
+
+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.
+====

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 such as components, resources, and systems that reference this template, including any version information if configured.

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]