Skip to content

Commit 9f7dd3e

Browse files
pabel-rhpabel-rh
authored
RHIDP-8627: Templates lifecycle management (#1470)
* Templates lifecycle management * Added the specific catalog rules * Incorporated Frank's comment * Minor change * Minor change * Minor change * typo * Minor comment * Incorporated Judy's comments
1 parent d7a8193 commit 9f7dd3e

File tree

5 files changed

+101
-0
lines changed

5 files changed

+101
-0
lines changed

‎assemblies/assembly-configuring-templates.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ include::modules/customizing-templates/proc-searching-and-filtering-software-tem
2020
include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1]
2121
include::modules/customizing-templates/proc-versioning-software-templates.adoc[leveloffset=+1]
2222
include::modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc[leveloffset=+1]
23+
include::assembly-tracking-component-origin-and-software-template-version.adoc[leveloffset=+1]
2324

2425
[role="_additional-resources"]
2526
.Additional resources

‎assemblies/assembly-tracking-component-origin-and-software-template-version.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="tracking-component-origin-and-software-template-version"]
4+
= Tracking Component origin and Software Template version
5+
6+
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.
7+
8+
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.
9+
10+
include::modules/tracking-component-origin-and-software-template-version/proc-configuring-provenance-and-software-template-versioning.adoc[leveloffset=+1]
11+
12+
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‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-configuring-provenance-and-software-template-versioning_{context}"]
4+
= Configuring provenance and Software Template versioning {product}
5+
6+
As a platform engineer, you must modify the Software Template YAML definition to ensure the required provenance information is added during the scaffolding process.
7+
8+
.Prerequisites
9+
10+
* You have administrator rights to {product}.
11+
12+
.Procedure
13+
14+
. 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.
15+
. 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:
16+
+
17+
[source,yaml]
18+
----
19+
steps:
20+
- id: create-provenance-annotation
21+
name: Append the entityRef of this template to the entityRef
22+
action: catalog:scaffolded-from
23+
- id: create-version-annotation
24+
name: Create Template Version Annotation
25+
action: catalog:template:version
26+
input:
27+
templateVersion: ${{ parameters.version }}
28+
- ... other steps ...
29+
----
30+
+
31+
where:
32+
33+
`steps:input:templateVersion`:: Reads the version parameter
34+
+
35+
[NOTE]
36+
====
37+
The `catalog:template:version` action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity.
38+
====
39+
40+
. 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:
41+
+
42+
[source,yaml]
43+
----
44+
# ...
45+
catalog:
46+
locations:
47+
- type: url
48+
target: https://<repository_url>/example-template.yaml
49+
rules:
50+
- allow: [Template]
51+
# ...
52+
----
53+
+
54+
where:
55+
56+
`catalog.locations.type`:: Enter the `url` type if you are importing templates from a repository, such as GitHub or GitLab.
57+
`catalog.locations.target`:: Enter the URL for the template.
58+
`catalog.locations.rules.allow`:: Enter the `Template` rule to allow new Software Templates to be added to the catalog.
59+
60+
.Verification
61+
62+
After creating a component with the updated template, verify the provenance annotations in the resulting Catalog Entity YAML.
63+
64+
. In the {product} navigation menu, go to *Catalog* and locate the newly created catalog component.
65+
. To view the underlying data that links the entity to the template, select the **INSPECT ENTITY** option.
66+
. To verify provenance annotations, complete the following steps:
67+
.. Select the *YAML Raw* or *JSON Raw* view and verify the presence of the data item for the `scaffoldedFrom` link.
68+
.. Optional: If versioning was included, verify the presence of the `backstage.io/template-version` annotation.
69+
+
70+
[NOTE]
71+
====
72+
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.
73+
====

‎modules/tracking-component-origin-and-software-template-version/proc-viewing-software-template-dependencies.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="proc-viewing-software-template-dependencies_{context}"]
4+
= Viewing Software Template dependencies
5+
6+
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.
7+
8+
.Procedure
9+
To view all components created from a specific template, complete the following steps:
10+
11+
. In the {product} navigation menu, click *Catalog*, use the filters to find and select the Software Template you wish to inspect.
12+
. 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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,13 @@ include::assemblies/assembly-about-software-catalogs.adoc[leveloffset=+1]
2525

2626
include::assemblies/assembly-customizing-the-learning-paths.adoc[leveloffset=+1]
2727

28+
2829
include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1]
2930

3031

3132
include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1]
3233

34+
3335
include::assemblies/assembly-configuring-the-quickstarts.adoc[leveloffset=+1]
3436

3537

@@ -44,4 +46,5 @@ include::assemblies/assembly-customizing-the-homepage.adoc[leveloffset=+1]
4446

4547
include::assemblies/assembly-customizing-the-quick-access-card.adoc[leveloffset=+1]
4648

49+
4750
include::modules/customizing/proc-customizing-rhdh-metadata-card.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)