Merge branch 'main' into RHIDP-5733-info-about-custom-config-in-the-Installation-guides

Author: Gerry-Forde

.github/pull_request_template.md

@@ -2,11 +2,14 @@
 
 <!--- If your changes apply to the latest released and/or in-development version of RHDH, open your PR against the `main` branch and cherrypick your PR to any released branches that you want to apply your changes to. --->
 
+<!--- Add the relevant labels to the Pull Request. Update the labels, as needed, to reflect the current status of the PR. --->
+
+
 **IMPORTANT: Do Not Merge - To be merged by Docs Team Only**
 
 **Version(s):**
 <!--- Specify the version(s) of RHDH that your PR applies to. -->
-Add the relevant labels to the Pull Request.
 **Issue:**
 <!--- Add a link to the Jira issue. --->
-
+**Preview:**
+<!--- Add a link to the preview of the changed file(s). --->

.vscode/settings.json

@@ -1 +1,5 @@
-{}
+{
+    "cSpell.words": [
+        "preconfigured"
+    ]
+}

artifacts/attributes.adoc

@@ -2,18 +2,21 @@
 :imagesdir: images
 :idseparator: -
 
-// Company names
+// Company name
 :company-name: Red Hat
 
 // Products
 :product-author: CCS
 :product: Red Hat Developer Hub
 :product-short: Developer Hub
 :product-very-short: RHDH
-:product-version: 1.5
-:product-bundle-version: 1.5.0
-:product-chart-version: 1.5.0
-:product-backstage-version: 1.35.0
+:product-local: Red Hat Developer Hub Local
+:product-local-very-short: RHDH Local
+:product-version: 1.7
+:product-bundle-version: 1.7.0
+:product-chart-version: 1.7.0
+:product-backstage-version: 1.39.1
+:product-version-next: 1.7
 :product-custom-resource-type: Backstage
 :rhdeveloper-name: Red Hat Developer
 :rhel: Red Hat Enterprise Linux
@@ -47,12 +50,11 @@
 :rhsso: RHSSO
 :rhbk-brand-name: Red Hat Build of Keycloak
 :rhbk: RHBK
-:keycloak-version: 24.0
+:keycloak-version: 26.0
 
-// RHTAP information
-:rhtap-version: 1.3
-:rhtap-brand-name: Red Hat Trusted Application Pipeline
-:rhtap-very-short: RHTAP
+// RHADS information
+:rhads-brand-name: Red Hat Advanced Developer Suite - secure supply chain
+:rhads-very-short: RHADS - ssc
 
 // TAS information
 :rhtas-brand-name: Red Hat Trusted Artifact Signer
@@ -85,75 +87,69 @@
 :gcp-brand-name: Google Cloud Platform
 :gcp-short: GCP
 
-// Release Notes
-:rn-product-title: Release notes for Red Hat Developer Hub
-
-// Red Hat Developer Hub administration guide
-:ag-product-title: Administration guide for Red Hat Developer Hub
-
-// Red Hat Developer Hub getting started guide
-:gs-product-title: Getting started with Red Hat Developer Hub
-
-// Backstage Plugins for Red Hat Developer Hub
-//:bs-product-title: Backstage Plugins for Red Hat Developer Hub
-
-//  User Guide
-:ug-product-title: Red Hat Developer Hub User Guide
 
 // Links
 
 
-:LinkPluginsGuide: https://access.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/configuring_plugins_in_red_hat_developer_hub/index
-:NameOfPluginsGuide: Configuring plugins in {product}
-
-:release-notes-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/release_notes/index
-:release-notes-title: Release notes
-
-:installing-and-viewing-dynamic-plugins-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_dynamic_plugins/index
-:installing-and-viewing-dynamic-plugins-title: Installing and viewing dynamic plugins
-
-:authentication-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authentication/index
-:authentication-book-title: Authentication
-
-:authorization-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authorization/index
-:authorization-book-title: Authorization
-
-:configuring-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/configuring/index
-:configuring-book-title: Configuring
+:discover-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Discover
+:about-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/about_red_hat_developer_hub/index
+:about-book-title: About {product}
 
-:customizing-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/customizing/index
-:customizing-book-title: Customizing
+:release-notes-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Release Notes
+:release-notes-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/red_hat_developer_hub_release_notes/index
+:release-notes-book-title: {product} release notes
 
-:installing-on-osd-on-gcp-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_openshift_dedicated_on_google_cloud_platform/index
-:installing-on-osd-on-gcp-book-title: Installing {product} on {gcp-brand-name} on {gcp-brand-name}
-
-:installing-on-ocp-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_openshift_container_platform/index
+:install-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Install
 :installing-on-ocp-book-title: Installing {product} on {ocp-short}
-
-:installing-on-gke-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_google_kubernetes_engine/index
-:installing-on-gke-book-title: Installing {product} on {gke-brand-name}
-
-:installing-on-eks-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_amazon_elastic_kubernetes_service/index
+:installing-on-ocp-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_openshift_container_platform/index
 :installing-on-eks-book-title: Installing {product} on {eks-brand-name}
-
-:installing-on-aks-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_microsoft_azure_kubernetes_service/index
+:installing-on-eks-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_amazon_elastic_kubernetes_service/index
 :installing-on-aks-book-title: Installing {product} on {aks-brand-name}
-
-:installing-in-air-gap-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_in_an_air-gapped_environment/index
+:installing-on-aks-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_microsoft_azure_kubernetes_service/index
+:installing-on-osd-on-gcp-book-title: Installing {product} on {gcp-brand-name} on {gcp-brand-name}
+:installing-on-osd-on-gcp-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_openshift_dedicated_on_google_cloud_platform/index
+:installing-on-gke-book-title: Installing {product} on {gke-brand-name}
+:installing-on-gke-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_on_google_kubernetes_engine/index
 :installing-in-air-gap-book-title: Installing {product} in an air-gapped environment
+:installing-in-air-gap-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_red_hat_developer_hub_in_an_air-gapped_environment/index
 
+:upgrade-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Upgrade
 :upgrading-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/upgrading_red_hat_developer_hub/index
 :upgrading-book-title: Upgrading {product}
 
+:configure-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Configure
+:configuring-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/configuring_red_hat_developer_hub/index
+:configuring-book-title: Configuring {product}
+:customizing-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/customizing_red_hat_developer_hub/index
+:customizing-book-title: Customizing {product}
+:techdocs-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/techdocs_for_red_hat_developer_hub/index
+:techdocs-book-title: TechDocs for {product}
+
+:control-access-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Control access
+:authentication-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authentication_in_red_hat_developer_hub/index
+:authentication-book-title: Authentication in {product}
+:authorization-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authorization_in_red_hat_developer_hub/index
+:authorization-book-title: Authorization in {product}
+
+:observability-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Observability
+:audit-log-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/audit_logs_in_red_hat_developer_hub/index
+:audit-log-book-title: Audit logs in {product}
+:monitoring-and-logging-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/monitoring_and_logging/index
+:monitoring-and-logging-book-title: Monitoring and logging
 :telemetry-data-collection-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/telemetry_data_collection/index
 :telemetry-data-collection-book-title: Telemetry data collection
 
-:audit-log-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/audit_log/index
-:audit-log-book-title: Audit log
+:extend-category-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/#Extend
+:introduction-to-plugins-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/introduction_to_plugins/index
+:introduction-to-plugins-book-title: Introduction to plugins
+:configuring-dynamic-plugins-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/configuring_dynamic_plugins/index
+:configuring-dynamic-plugins-book-title: Configuring dynamic plugins
+:installing-and-viewing-plugins-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index
+:installing-and-viewing-plugins-book-title: Installing and viewing plugins in {product}
+:using-dynamic-plugins-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index
+:using-dynamic-plugins-book-title: Using dynamic plugins
+:dynamic-plugins-reference-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/dynamic_plugins_reference/index
+:dynamic-plugins-reference-book-title: Dynamic plugins reference
 
-:monitoring-and-logging-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/monitoring_and_logging/index
-:monitoring-and-logging-book-title: Monitoring and logging
 
-:plugins-configure-book-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/configuring_dynamic_plugins/index
-:plugins-configure-book-title: Configuring dynamic plugins
 

artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc

@@ -226,6 +226,6 @@ If using the label selector annotation (backstage.io/kubernetes-label-selector),
 [role="_additional-resources"]
 .Additional resources
 
-* The package path, scope, and name of the {company-name} ArgoCD plugin has changed since 1.2. For more information, see link:{release-notes-url}#removed-functionality-rhidp-4293[Breaking Changes] in the _{rn-product-title}_. 
+* The package path, scope, and name of the {company-name} ArgoCD plugin has changed since 1.2. For more information, see link:{release-notes-book-url}#removed-functionality-rhidp-4293[Breaking Changes] in the _{release-notes-book-title}_.
 
-* For more information on installing dynamic plugins, see link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}].
+* For more information on installing dynamic plugins, see link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}].

artifacts/rhdh-plugins-reference/argocd/argocd-plugin-readme.adoc

@@ -33,4 +33,4 @@ image::rhdh-plugins-reference/deployment_summary.png[Deployment summary]
 [role="_additional-resources"]
 .Additional resources
 
-* For more information on installing dynamic plugins, see link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}].
+* For more information on installing dynamic plugins, see link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}].

artifacts/rhdh-plugins-reference/argocd/argocd-plugin-user.adoc

@@ -31,4 +31,4 @@ image::rhdh-plugins-reference/deployment_summary.png[Deployment summary]
 [role="_additional-resources"]
 .Additional resources
 
-* For more information on installing dynamic plugins, see link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}].
+* For more information on installing dynamic plugins, see link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}].

artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc

@@ -143,6 +143,64 @@ When using client credentials, the access type must be set to `confidential` and
 * `query-users`
 * `view-users`
 
+== Metrics
+
+The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetry] metrics that you can use to monitor fetch operations and diagnose potential issues.
+
+=== Available Counters
+
+.Keycloak metrics
+[cols="60%,40%", frame="all", options="header"]
+|===
+|Metric Name
+|Description
+| `backend_keycloak_fetch_task_failure_count_total`       | Counts fetch task failures where no data was returned due to an error.
+| `backend_keycloak_fetch_data_batch_failure_count_total` | Counts partial data batch failures. Even if some batches fail, the plugin continues fetching others.
+|===
+
+=== Labels
+
+All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. You can use this label to trace failures back to individual task executions. 
+
+Users can enter queries in the Prometheus UI or Grafana to explore and manipulate metric data. 
+
+In the following examples, a Prometheus Query Language (PromQL) expression returns the number of backend failures.
+
+.Example to get the number of backend failures associated with a `taskInstanceId` 
+[source,subs="+attributes,+quotes"]
+----
+backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1
+----
+
+.Example to get the number of backend failures during the last hour
+
+[source,subs="+attributes,+quotes"]
+----
+sum(backend_keycloak_fetch_data_batch_failure_count_total) - sum(backend_keycloak_fetch_data_batch_failure_count_total offset 1h)
+----
+
+[NOTE]
+====
+PromQL supports arithmetic operations, comparison operators, logical/set operations, aggregation, and various functions. Users can combine these features to analyze time-series data effectively.
+
+Additionally, the results can be visualized using Grafana.
+====
+
+// === Use Case Example
+
+// Imagine your Keycloak instance is under-provisioned (e.g., low CPU/RAM limits), and the plugin is configured to send many parallel API requests.  
+// This could cause request timeouts or throttling. The metrics described above can help detect such behavior early, allowing administrators to:
+
+// - Tune the plugin configuration (e.g., reduce parallelism)
+// - Increase resources on the Keycloak server
+// - Investigate network or permission issues
+
+=== Exporting Metrics
+
+You can export metrics using any OpenTelemetry-compatible backend, such as *Prometheus*.
+
+See the link:https://backstage.io/docs/tutorials/setup-opentelemetry[Backstage OpenTelemetry setup guide] for integration instructions.
+
 == Limitations
 
 If you have self-signed or corporate certificate issues, you can set the following environment variable before starting {product-short}:

artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-readme.adoc

@@ -6,9 +6,7 @@ The Keycloak backend plugin, which integrates Keycloak into {product-short}, has
 * Synchronization of Keycloak users in a realm.
 * Synchronization of Keycloak groups and their users in a realm.
 
-== For administrators
-
-=== Installation
+== Installation
 
 The Keycloak plugin is pre-loaded in {product-short} with basic configuration properties. To enable it, set the `disabled` property to `false` as follows:
 
@@ -23,7 +21,7 @@ global:
         disabled: false
 ----
 
-=== Basic configuration
+== Basic configuration
 To enable the Keycloak plugin, you must set the following environment variables:
 
 * `KEYCLOAK_BASE_URL`
@@ -36,7 +34,7 @@ To enable the Keycloak plugin, you must set the following environment variables:
 
 * `KEYCLOAK_CLIENT_SECRET`
 
-=== Advanced configuration
+== Advanced configuration
 
 .Schedule configuration
 You can configure a schedule in the `app-config.yaml` file, as follows:
@@ -140,7 +138,7 @@ When using client credentials, the access type must be set to `confidential` and
 * `query-users`
 * `view-users`
 
-=== Limitations
+== Limitations
 
 If you have self-signed or corporate certificate issues, you can set the following environment variable before starting {product-short}:
 
@@ -152,29 +150,3 @@ If you have self-signed or corporate certificate issues, you can set the followi
 The solution of setting the environment variable is not recommended.
 ====
 
-== For users
-
-=== Import of users and groups in {product-short} using the Keycloak plugin
-
-After configuring the plugin successfully, the plugin imports the users and groups each time when started.
-
-[NOTE]
-====
-If you set up a schedule, users and groups will also be imported.
-====
-
-After the first import is complete, you can select *User* to list the users from the catalog page:
-
-image::rhdh-plugins-reference/users.jpg[catalog-list]
-
-You can see the list of users on the page:
-
-image::rhdh-plugins-reference/user-list.jpg[user-list]
-
-When you select a user, you can see the information imported from Keycloak:
-
-image::rhdh-plugins-reference/user2.jpg[user-profile]
-
-You can also select a group, view the list, and select or view the information imported from Keycloak for a group:
-
-image::rhdh-plugins-reference/group1.jpg[group-profile]

artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.adoc

@@ -15,18 +15,11 @@ After configuring the plugin successfully, the plugin imports the users and grou
 If you set up a schedule, users and groups will also be imported.
 ====
 
-After the first import is complete, you can select *User* to list the users from the catalog page:
-
-image::rhdh-plugins-reference/users.jpg[catalog-list]
-
-You can see the list of users on the page:
-
-image::rhdh-plugins-reference/user-list.jpg[user-list]
-
-When you select a user, you can see the information imported from Keycloak:
-
-image::rhdh-plugins-reference/user2.jpg[user-profile]
-
-You can also select a group, view the list, and select or view the information imported from Keycloak for a group:
-
-image::rhdh-plugins-reference/group1.jpg[group-profile]
+.Procedure
+. in {product}, go to the *Catalog* page.
+. Select *User* from the entity type filter to display the list of imported users.
+. Browse the list of users displayed on the page.
+. Select a user to view detailed information imported from Keycloak.
+. To view groups, select *Group* from the entity type filter.
+. Browse the list of groups shown on the page.
+. From the list of groups, select a group to view the information imported from Keycloak.