Merge branch 'main' into RHIPD-8629

Author: deerskindoll

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/authentication/snip-enabling-user-authentication-with-rhbk-common-first-steps.adoc

@@ -51,7 +51,7 @@ This plugin imports {rhbk} users and groups to the {product-short} software cata
 [source,yaml]
 ----
 plugins:
-  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-keycloak-dynamic'
+  - package: './dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic'
     disabled: false
 ----
 

modules/dynamic-plugins/proc-extensions-enabling-plugins-installation-rhdh-local.adoc

@@ -23,20 +23,23 @@ plugins:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-marketplace:
+            translationResources:
+              - importName: marketplaceTranslations
+                ref: marketplaceTranslationRef
+                module: Alpha
             appIcons:
-              - name: marketplace
-                importName: MarketplaceIcon
+              - name: pluginsIcon
+                importName: PluginsIcon
             dynamicRoutes:
-              - path: /extensions/catalog
+              - path: /extensions
                 importName: DynamicMarketplacePluginRouter
-            mountPoints:
-               - mountPoint: application/provider
-                 importName: InstallationContextProvider
-              - mountPoint: internal.plugins/tab
-                importName: DynamicMarketplacePluginContent
-                config:
-                  path: marketplace
-                  title: Catalog
+                menuItem:
+                  icon: pluginsIcon
+                  text: Extensions
+                  textKey: menuItem.extensions
+            menuItems:
+              extensions:
+                parent: default.admin
   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
     disabled: false
     pluginConfig:
@@ -46,6 +49,10 @@ plugins:
           saveToSingleFile:
             file: /opt/app-root/src/configs/dynamic-plugins/dynamic-plugins.override.yaml
 ----
+where:
+
+`translationResources`:: Sets the extension point for localization.
+
 . Update your `compose.yaml` file:
 +
 [source,yaml]

modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc

@@ -27,21 +27,23 @@ plugins:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-marketplace:
+            translationResources:
+              - importName: marketplaceTranslations
+                ref: marketplaceTranslationRef
+                module: Alpha
             appIcons:
-              - name: marketplace
-                importName: MarketplaceIcon
+              - name: pluginsIcon
+                importName: PluginsIcon
             dynamicRoutes:
-              - path: /extensions/catalog
+              - path: /extensions
                 importName: DynamicMarketplacePluginRouter
-            mountPoints:
-              - mountPoint: application/provider
-                importName: InstallationContextProvider
-              - mountPoint: internal.plugins/tab
-                importName: DynamicMarketplacePluginContent
-                config:
-                  path: marketplace
-                  title: Catalog
-                  icon: CatalogTabIcon
+                menuItem:
+                  icon: pluginsIcon
+                  text: Extensions
+                  textKey: menuItem.extensions
+            menuItems:
+              extensions:
+                parent: default.admin
   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
     disabled: false
     pluginConfig:
@@ -51,6 +53,9 @@ plugins:
           saveToSingleFile:
             file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml
 ----
+where:
+`translationResources`:: Sets the extension point for localization.
+
 . Copy the file to your cluster by running the following commands:
 +
 [source,yaml]

modules/observe/proc-admin-enabling-metrics-ocp-helm.adoc

@@ -3,7 +3,7 @@
 [id="proc-admin-enabling-metrics-ocp-helm_{context}"]
 = Enabling metrics monitoring in a Helm chart installation on an {ocp-short} cluster
 
-You can enable and view metrics for a {product} Helm deployment from the *Developer* perspective of the {ocp-short} web console.
+You can enable and view metrics for a {product} Helm deployment from the {ocp-short} web console. Metrics monitoring is enabled through configuration during a chart upgrade. After the upgrade, the Helm release generates the necessary `ServiceMonitor` resource.
 
 .Prerequisites
 
@@ -12,7 +12,7 @@ You can enable and view metrics for a {product} Helm deployment from the *Develo
 
 .Procedure
 
-. From the *Developer* perspective in the {ocp-short} web console, select the *Topology* view.
+. From the {ocp-short} web console, select the *Topology* view.
 . Click the overflow menu of the {product} Helm chart, and select *Upgrade*.
 +
 image::rhdh/helm-upgrade.png[]
@@ -37,5 +37,5 @@ image::rhdh/upgrade-helm-metrics.png[]
 
 .Verification
 
-. From the *Developer* perspective in the {ocp-short} web console, select the *Observe* view.
+. From the {ocp-short} web console, select the *Observe* view.
 . Click the *Metrics* tab to view metrics for {product} pods.

modules/observe/proc-admin-enabling-metrics-ocp-operator.adoc

@@ -3,7 +3,9 @@
 [id="proc-admin-enabling-metrics-ocp-operator_{context}"]
 = Enabling metrics monitoring in a {product} Operator installation on an {ocp-short} cluster
 
-You can enable and view metrics for an Operator-installed {product} instance from the *Developer* perspective of the {ocp-short} web console.
+You can enable and view metrics for an Operator-installed {product} instance from the {ocp-short} web console. Metrics are exposed through an HTTP service endpoint under the `/metrics` canonical name.
+
+By setting the `spec.monitoring.enabled` field to `true` in your {product} custom resource (CR), you instruct the Operator to automatically create and manage the necessary `ServiceMonitor` to scrape metrics from the service endpoint.
 
 .Prerequisites
 
@@ -13,53 +15,29 @@ You can enable and view metrics for an Operator-installed {product} instance fro
 
 .Procedure
 
-Currently, the {product} Operator does not support creating a `ServiceMonitor` custom resource (CR) by default. You must complete the following steps to create a `ServiceMonitor` CR to scrape metrics from the endpoint.
-
-. Create the `ServiceMonitor` CR as a YAML file:
+. Use the *OpenShift CLI* (`oc`) to edit your existing {product} CR.
++
+[source,bash]
+----
+oc edit Backstage <instance-name>
+----
+. In the CR, locate the `spec` field and add the `monitoring` configuration block.
 +
-[source,yaml,subs="+attributes,+quotes"]
+[source,yaml]
 ----
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: _<developer_hub_service_monitor_name>_ <1>
-  namespace: _<rhdh_namespace_name>_ <2>
-  labels:
-    app.kubernetes.io/instance: _<rhdh_cr_name>_ <3>
-    app.kubernetes.io/name: {product-custom-resource-type}
 spec:
-  namespaceSelector:
-    matchNames:
-      - _<rhdh_namespace_name>_ <4>
-  selector:
-    matchLabels:
-      app.kubernetes.io/instance: _<deployment_name>_ <5>
-      app.kubernetes.io/name: _<rhdh_cr_type>_ <6>
-  endpoints:
-  - port: http-metrics
-    path: '/metrics'
+  monitoring:
+    enabled: true
 ----
-<1> The name of your `ServiceMonitor` resource, for example, `developer_hub_service_monitor`.
-<2> The namespace where your `ServiceMonitor` will live, for example, `{my-product-namespace}`.
-<3> The label name identifying the `ServiceMonitor` CR instance, for example, `{my-product-cr-name}`.
-<4> The namespace where your {product-very-short} instance is installed, for example, `{my-product-namespace}`.
-<5> The name of your {product-very-short} deployment, for example, `developer-hub`.
-<6> The name of your {product-very-short} application, for example, `backstage`.
+. Save the {product-very-short} CR. The {product-very-short} Operator detects the configuration and automatically creates the corresponding `ServiceMonitor` custom resource (CR).
 +
 [NOTE]
 ====
-`spec.selector.matchLabels` configuration must match the labels of your {product-very-short} installation.
+The Operator automatically configures the `ServiceMonitor` with the correct labels (`app.kubernetes.io/instance` and `app.kubernetes.io/name`) that match your Backstage CR. The `ServiceMonitor` will be named `metrics-<cr-name>`. No additional label configuration is required.
 ====
 
-. Apply the `ServiceMonitor` CR by running the following command:
-+
-[source,terminal]
-----
-oc apply -f <filename>
-----
-
 .Verification
 
-. From the *Developer* perspective in the {ocp-short} web console, select the *Observe* view.
+. From the {ocp-short} web console, select the *Observe* view.
 . Click the *Metrics* tab to view metrics for {product} pods.
-. From the Developer perspective in the {ocp-short} web console, click **Project > Services** and verify the labels for `backstage-developer-hub`.
+. From the {ocp-short} web console, click **Project > Services** and verify the labels for `backstage-developer-hub`.

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]