diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index eb541ce985..a789bf6d04 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -1,26 +1,29 @@ [id="rhdh-configuring-rhdh-plugins_{context}"] = Configuring dynamic plugins in {product} -// Ansible +// Ansible - no-change include::../modules/dynamic-plugins/con-ansible-plugin-admin.adoc[leveloffset=+1] -// Argo CD -include::../../artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc[leveloffset=+1] +// Argo CD - modularized +include::assembly-installing-configuring-argo-cd.adoc[leveloffset=+1] -//JFrog Artifactory -include::../../artifacts/rhdh-plugins-reference/jfrog-artifactory/jfrog-artifactory-plugin-admin.adoc[leveloffset=+1] +// JFrog Artifactory +include::assembly-enabling-configuring-jfrog.adoc[leveloffset=+1] -// Keycloak -include::../../artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc[leveloffset=+1] +// Keycloak - modularized +include::assembly-enabling-configuring-keycloak.adoc[leveloffset=+1] -// Nexus -include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-repository-manager-plugin-admin.adoc[leveloffset=+1] +// Nexus - modularized +include::assembly-enabling-configuring-nexus.adoc[leveloffset=+1] -// Tekton -include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-admin.adoc[leveloffset=+1] +// Tekton - modularized +include::../../modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc[leveloffset=+1] -// Topology -include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1] +// Topology - no-change +include::assembly-install-topology-plugin.adoc[leveloffset=+1] -// Overriding Core Backend Service Configuration -include::../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] +include::../assembly-using-servicenow.adoc[leveloffset=+1] + +include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] + +include::../../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-enabling-configuring-jfrog.adoc b/assemblies/dynamic-plugins/assembly-enabling-configuring-jfrog.adoc new file mode 100644 index 0000000000..5aabaec499 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-enabling-configuring-jfrog.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-enabling-configuring-the-jfrog-plugin_{context}"] += Enabling and configuring the JFrog plugin +:context: assembly-installing-configuring-jfrog + +JFrog Artifactory is a front-end plugin that displays the information about your container images stored in the JFrog Artifactory repository. The JFrog Artifactory plugin is preinstalled with {product-short} and disabled by default. To use it, you need to enable and configure it first. + +[IMPORTANT] +==== +The JFrog Artifactory plugin is a Technology Preview feature only. + +Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information on Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope]. + +Additional detail on how Red Hat provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page. +==== + +include::../modules/dynamic-plugins/proc-enabling-the-jfrog-plugin.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/proc-configuring-the-jfrog-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-enabling-configuring-keycloak.adoc b/assemblies/dynamic-plugins/assembly-enabling-configuring-keycloak.adoc new file mode 100644 index 0000000000..de7d1b6ec5 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-enabling-configuring-keycloak.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-enabling-configuring-the-keycloak-plugin_{context}"] += Enabling and configuring the Keycloak plugin +:context: assembly-installing-configuring-keycloak + +The Keycloak backend plugin, which integrates Keycloak into {product-short}, has the following capabilities: + +* Synchronization of Keycloak users in a realm. +* Synchronization of Keycloak groups and their users in a realm. + +[NOTE] +==== +The supported {rhbk-brand-name} ({rhbk}) version is `{keycloak-version}`. +==== + +include::../modules/dynamic-plugins/proc-enabling-the-keycloak-plugin.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/ref-configuring-the-keycloak-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-enabling-configuring-nexus.adoc b/assemblies/dynamic-plugins/assembly-enabling-configuring-nexus.adoc new file mode 100644 index 0000000000..9525728121 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-enabling-configuring-nexus.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-enabling-configuring-the-nexus-plugin_{context}"] += Enabling and configuring the Nexus Repository Manager plugin +:context: assembly-installing-configuring-nexus + +The Nexus Repository Manager plugin displays the information about your build artifacts in your {product-short} application. The build artifacts are available in the Nexus Repository Manager. + +[IMPORTANT] +==== +The Nexus Repository Manager plugin is a Technology Preview feature only. + +Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information on Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope]. + +Additional detail on how {company-name} provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page. +==== + +include::../modules/dynamic-plugins/proc-enabling-the-nexus-plugin.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/proc-configuring-the-nexus-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc index 578f2b6637..7e38a9fcc7 100644 --- a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc +++ b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc @@ -5,9 +5,4 @@ include::../modules/dynamic-plugins/proc-topology-install.adoc[leveloffset=+2] include::../assembly-topology-plugin-configure.adoc[leveloffset=+1] -include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] - - -include::../assembly-using-servicenow.adoc[leveloffset=+1] - -include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] +include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-installing-configuring-argo-cd.adoc b/assemblies/dynamic-plugins/assembly-installing-configuring-argo-cd.adoc new file mode 100644 index 0000000000..84649fa97d --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-installing-configuring-argo-cd.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-installing-configuring-argo-cd.adoc_{context}"] += Installing and configuring Argo CD +:context: assembly-installing-configuring-argo-cd + +You can use the Argo CD plugin to visualize the Continuous Delivery (CD) workflows in OpenShift GitOps. + +include::../modules/dynamic-plugins/proc-enabling-the-argo-cd-plugin.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/proc-enabling-argo-cd-rollouts.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc index 4d9d74eb90..50fbed6bd0 100644 --- a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc @@ -5,19 +5,20 @@ include::../modules/dynamic-plugins/con-ansible-plugin-user.adoc[leveloffset=+1] // Argo CD -include::../../artifacts/rhdh-plugins-reference/argocd/argocd-plugin-user.adoc[leveloffset=+1] +include::../../modules/dynamic-plugins/proc-using-argo-cd.adoc[leveloffset=+1] //JFrog Artifactory -include::../../artifacts/rhdh-plugins-reference/jfrog-artifactory/jfrog-artifactory-plugin-user.adoc[leveloffset=+1] +//include::../../artifacts/rhdh-plugins-reference/jfrog-artifactory/jfrog-artifactory-plugin-user.adoc[leveloffset=+1] +include::../../modules/dynamic-plugins/proc-using-jfrog-artifactory-plugin.adoc[leveloffset=+1] // Keycloak -include::../../artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.adoc[leveloffset=+1] +include::../../modules/dynamic-plugins/proc-using-keycloak.adoc[leveloffset=+1] // Nexus -include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-repository-manager-plugin-user.adoc[leveloffset=+1] +include::../../modules/dynamic-plugins/proc-using-nexus.adoc[leveloffset=+1] // Tekton -include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-user.adoc[leveloffset=+1] +include::../../modules/dynamic-plugins/proc-using-tekton.adoc[leveloffset=+1] // Topology include::../../assemblies/dynamic-plugins/assembly-using-topology-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-configuring-the-jfrog-plugin.adoc b/modules/dynamic-plugins/proc-configuring-the-jfrog-plugin.adoc new file mode 100644 index 0000000000..ec42a966f9 --- /dev/null +++ b/modules/dynamic-plugins/proc-configuring-the-jfrog-plugin.adoc @@ -0,0 +1,26 @@ +[id="proc-configuring-the-jfrog-plugin"] += Configuring the JFrog Artifactory plugin + +.Procedure +. Set the proxy to the desired JFrog Artifactory server in the {my-app-config-file} file as follows: ++ +[source,yaml] +---- +proxy: + endpoints: + ‘/jfrog-artifactory/api’: + target: http://:8082 # or https://.jfrog.io + headers: + # Authorization: 'Bearer ' + # Change to "false" in case of using a self-hosted Artifactory instance with a self-signed certificate + secure: true +---- + +. Add the following annotation to the entity’s `catalog-info.yaml` file to enable the JFrog Artifactory plugin features in {product-very-short} components: ++ +[source,yaml] +---- +metadata: + annotations: + 'jfrog-artifactory/image-name': '' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-configuring-the-nexus-plugin.adoc b/modules/dynamic-plugins/proc-configuring-the-nexus-plugin.adoc new file mode 100644 index 0000000000..9fe58a55a8 --- /dev/null +++ b/modules/dynamic-plugins/proc-configuring-the-nexus-plugin.adoc @@ -0,0 +1,47 @@ +:_mod-docs-content-type: PROCEDURE +[id="configuring-the-nexus-plugin_{context}"] += Configuring the Nexus Repository Manager plugin + +. Set the proxy to the desired Nexus Repository Manager server in the `{my-app-config-file}` file as follows: ++ +[source,yaml] +---- +proxy: + '/nexus-repository-manager': + target: 'https://' + headers: + X-Requested-With: 'XMLHttpRequest' + # Uncomment the following line to access a private Nexus Repository Manager using a token + # Authorization: 'Bearer ' + changeOrigin: true + # Change to "false" in case of using self hosted Nexus Repository Manager instance with a self-signed certificate + secure: true +---- + +. Optional: Change the base URL of Nexus Repository Manager proxy as follows: ++ +[source,yaml] +---- +nexusRepositoryManager: + # default path is `/nexus-repository-manager` + proxyPath: /custom-path +---- + +. Optional: Enable the following experimental annotations: ++ +[source,yaml] +---- +nexusRepositoryManager: + experimentalAnnotations: true +---- + +. Annotate your entity using the following annotations: ++ +[source,yaml] +---- +metadata: + annotations: + # insert the chosen annotations here + # example + nexus-repository-manager/docker.image-name: `/`, +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-argo-cd-rollouts.adoc b/modules/dynamic-plugins/proc-enabling-argo-cd-rollouts.adoc new file mode 100644 index 0000000000..d4ebf52683 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-argo-cd-rollouts.adoc @@ -0,0 +1,161 @@ +:_mod-docs-content-type: PROCEDURE +[id="enabling-argo-cd-rollouts_{context}"] += Enabling Argo CD Rollouts + +The optional Argo CD Rollouts feature enhances Kubernetes by providing advanced deployment strategies, such as blue-green and canary deployments, for your applications. When integrated into the backstage Kubernetes plugin, it allows developers and operations teams to visualize and manage Argo CD Rollouts seamlessly within the {product-custom-resource-type} interface. + +.Prerequisites + +* The Backstage Kubernetes plugin (`@backstage/plugin-kubernetes`) is installed and configured. + +** To install and configure Kubernetes plugin in Backstage, see link:https://backstage.io/docs/features/kubernetes/installation/[Installaltion] and link:https://backstage.io/docs/features/kubernetes/configuration/[Configuration] guide. + +* You have access to the Kubernetes cluster with the necessary permissions to create and manage custom resources and `ClusterRoles`. + +* The Kubernetes cluster has the `argoproj.io` group resources (for example, Rollouts and AnalysisRuns) installed. + +.Procedure + +. In the `{my-app-config-file}` file in your {product-custom-resource-type} instance, add the following `customResources` component under the `kubernetes` configuration to enable Argo Rollouts and AnalysisRuns: + ++ +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'argoproj.io' + apiVersion: 'v1alpha1' + plural: 'Rollouts' + - group: 'argoproj.io' + apiVersion: 'v1alpha1' + plural: 'analysisruns' +---- + +. Grant `ClusterRole` permissions for custom resources. + ++ +[NOTE] +==== + +* If the Backstage Kubernetes plugin is already configured, the `ClusterRole` permissions for Rollouts and AnalysisRuns might already be granted. + +* Use the link:https://raw.githubusercontent.com/backstage/community-plugins/main/workspaces/redhat-argocd/plugins/argocd/manifests/clusterrole.yaml[prepared manifest] to provide read-only `ClusterRole` access to both the Kubernetes and ArgoCD plugins. +==== + +.. If the `ClusterRole` permission is not granted, use the following YAML manifest to create the `ClusterRole`: + ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: backstage-read-only +rules: + - apiGroups: + - argoproj.io + resources: + - rollouts + - analysisruns + verbs: + - get + - list +---- + +.. Apply the manifest to the cluster using `kubectl`: ++ +[source,bash] +---- +kubectl apply -f .yaml +---- + +.. Ensure the `ServiceAccount` accessing the cluster has this `ClusterRole` assigned. + +. Add annotations to `catalog-info.yaml` to identify Kubernetes resources for {product-custom-resource-type}. + +.. For identifying resources by entity ID: ++ +[source,yaml] +---- +annotations: + ... + backstage.io/kubernetes-id: +---- + +.. (Optional) For identifying resources by namespace: ++ +[source,yaml] +---- +annotations: + ... + backstage.io/kubernetes-namespace: +---- + +.. For using custom label selectors, which override resource identification by entity ID or namespace: ++ +[source,yaml] +---- +annotations: + ... + backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end' +---- ++ +[NOTE] +==== +Ensure you specify the labels declared in `backstage.io/kubernetes-label-selector` on your Kubernetes resources. This annotation overrides entity-based or namespace-based identification annotations, such as `backstage.io/kubernetes-id` and `backstage.io/kubernetes-namespace`. +==== + +. Add label to Kubernetes resources to enable Backstage to find the appropriate Kubernetes resources. + +.. Backstage Kubernetes plugin label: Add this label to map resources to specific Backstage entities. ++ +[source,yaml] +---- +labels: + ... + backstage.io/kubernetes-id: +---- + +.. GitOps application mapping: Add this label to map Argo CD Rollouts to a specific GitOps application ++ +[source,yaml] +---- +labels: + ... + app.kubernetes.io/instance: +---- + ++ +[NOTE] +==== +If using the label selector annotation (backstage.io/kubernetes-label-selector), ensure the specified labels are present on the resources. The label selector will override other annotations like kubernetes-id or kubernetes-namespace. +==== + +.Verification + +. Push the updated configuration to your GitOps repository to trigger a rollout. + +. Open {product} interface and navigate to the entity you configured. + +. Select the *CD* tab and then select the *GitOps application*. The side panel opens. + +. In the *Resources* table of the side panel, verify that the following resources are displayed: + +* Rollouts + +* AnalysisRuns (optional) + +. Expand a rollout resource and review the following details: + +* The Revisions row displays traffic distribution details for different rollout versions. + +* The Analysis Runs row displays the status of analysis tasks that evaluate rollout success. + + +[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-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-plugins-book-url}[{installing-and-viewing-plugins-book-title}]. diff --git a/modules/dynamic-plugins/proc-enabling-the-argo-cd-plugin.adoc b/modules/dynamic-plugins/proc-enabling-the-argo-cd-plugin.adoc new file mode 100644 index 0000000000..412ee29a5a --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-argo-cd-plugin.adoc @@ -0,0 +1,76 @@ +:_mod-docs-content-type: PROCEDURE +[id="enabling-the-argo-cd-plugin_{context}"] += Enabling the Argo CD plugin + +The Argo CD plugin provides a visual overview of the application’s status, deployment details, commit message, author of the commit, container image promoted to environment and deployment history. + +.Prerequisites + +* Add Argo CD instance information to your `app-config.yaml` configmap as shown in the following example: + ++ +[source,yaml] +---- +argocd: + appLocatorMethods: + - type: 'config' + instances: + - name: argoInstance1 + url: https://argoInstance1.com + username: ${ARGOCD_USERNAME} + password: ${ARGOCD_PASSWORD} + - name: argoInstance2 + url: https://argoInstance2.com + username: ${ARGOCD_USERNAME} + password: ${ARGOCD_PASSWORD} +---- ++ +[NOTE] +Avoid using a trailing slash in the `url`, as it might cause unexpected behavior. + +* Add the following annotation to the entity’s `catalog-info.yaml` file to identify the Argo CD applications. + ++ +[source,yaml] +---- +annotations: + ... + # The label that Argo CD uses to fetch all the applications. The format to be used is label.key=label.value. For example, rht-gitops.com/janus-argocd=quarkus-app. + + argocd/app-selector: '${ARGOCD_LABEL_SELECTOR}' +---- + +* (Optional) Add the following annotation to the entity’s `catalog-info.yaml` file to switch between Argo CD instances as shown in the following example: + ++ +[source,yaml] +---- + annotations: + ... + # The Argo CD instance name used in `app-config.yaml`. + + argocd/instance-name: '${ARGOCD_INSTANCE}' +---- + ++ +[NOTE] +==== +If you do not set this annotation, the Argo CD plugin defaults to the first Argo CD instance configured in `app-config.yaml`. +==== + +.Procedure + +* Add the following to your dynamic-plugins ConfigMap to enable the Argo CD plugin. ++ +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd-backend-dynamic + disabled: false + - package: ./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd + disabled: false +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-jfrog-plugin.adoc b/modules/dynamic-plugins/proc-enabling-the-jfrog-plugin.adoc new file mode 100644 index 0000000000..2112003313 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-jfrog-plugin.adoc @@ -0,0 +1,16 @@ +[id="proc-enabling-the-jfrog-plugin"] += Enabling the JFrog Artifactory plugin + +.Procedure +. The JFrog Artifactory plugin is preinstalled in {product-short} with basic configuration properties. To enable it, set the disabled property to `false` as follows: ++ +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-community-plugin-jfrog-artifactory + disabled: false +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-keycloak-plugin.adoc b/modules/dynamic-plugins/proc-enabling-the-keycloak-plugin.adoc new file mode 100644 index 0000000000..360614a50b --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-keycloak-plugin.adoc @@ -0,0 +1,29 @@ +[id="proc-enabling-the-keycloak-plugin"] += Enabling the Keycloak plugin + +.Prerequisites +* To enable the Keycloak plugin, you must set the following environment variables: + +** `KEYCLOAK_BASE_URL` + +** `KEYCLOAK_LOGIN_REALM` + +** `KEYCLOAK_REALM` + +** `KEYCLOAK_CLIENT_ID` + +** `KEYCLOAK_CLIENT_SECRET` + +.Procedure +. The Keycloak plugin is pre-loaded in {product-short} with basic configuration properties. To enable it, set the `disabled` property to `false` as follows: ++ +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic + disabled: false +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-nexus-plugin.adoc b/modules/dynamic-plugins/proc-enabling-the-nexus-plugin.adoc new file mode 100644 index 0000000000..cdac523ef9 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-nexus-plugin.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: PROCEDURE +[id="enabling-the-nexus-plugin_{context}"] += Enabling the Nexus Repository Manager plugin + +The Nexus Repository Manager plugin is pre-loaded in {product-short} with basic configuration properties. To enable it, set the disabled property to `false` as follows: + +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-community-plugin-nexus-repository-manager + disabled: false +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc b/modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc new file mode 100644 index 0000000000..eb68db39a0 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc @@ -0,0 +1,140 @@ +[id="proc-enabling-the-tekton-plugin"] += Enabling the Tekton plugin + +You can use the Tekton plugin to visualize the results of CI/CD pipeline runs on your Kubernetes or OpenShift clusters. The plugin allows users to visually see high level status of all associated tasks in the pipeline for their applications. + +.Prerequisites +* You have installed and configured the `@backstage/plugin-kubernetes` and `@backstage/plugin-kubernetes-backend` dynamic plugins. +//For more information about installing dynamic plugins, see xref:rhdh-installing-dynamic-plugins[]. +//Cannot xref across titles. Convert xref to a link. + +* You have configured the Kubernetes plugin to connect to the cluster using a `ServiceAccount`. + +* The `ClusterRole` must be granted for custom resources (PipelineRuns and TaskRuns) to the `ServiceAccount` accessing the cluster. ++ +[NOTE] +If you have the {product-very-short} Kubernetes plugin configured, then the `ClusterRole` is already granted. + +* To view the pod logs, you have granted permissions for `pods/log`. + +* You can use the following code to grant the `ClusterRole` for custom resources and pod logs: ++ +-- +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'pipelineruns' + - group: 'tekton.dev' + apiVersion: 'v1' + + + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + - apiGroups: + - "" + resources: + - pods/log + verbs: + - get + - list + - watch + ... + - apiGroups: + - tekton.dev + resources: + - pipelineruns + - taskruns + verbs: + - get + - list +---- +-- ++ +You can use the prepared manifest for a read-only `ClusterRole`, which provides access for both Kubernetes plugin and Tekton plugin. + +* Add the following annotation to the entity's `catalog-info.yaml` file to identify whether an entity contains the Kubernetes resources: ++ +-- +[source,yaml] +---- +annotations: + ... + + backstage.io/kubernetes-id: +---- +-- + +* You can also add the `backstage.io/kubernetes-namespace` annotation to identify the Kubernetes resources using the defined namespace. ++ +-- +[source,yaml] +---- +annotations: + ... + + backstage.io/kubernetes-namespace: +---- +-- + +* Add the following annotation to the `catalog-info.yaml` file of the entity to enable the Tekton related features in {product-very-short}. The value of the annotation identifies the name of the {product-very-short} entity: ++ +-- +[source,yaml] +---- +annotations: + ... + + janus-idp.io/tekton : +---- +-- + +* Add a custom label selector, which {product-very-short} uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations. ++ +-- +[source,yaml] +---- +annotations: + ... + + backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end' +---- +-- + +* Add the following label to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: ++ +-- +[source,yaml] +---- +labels: + ... + + backstage.io/kubernetes-id: +---- +-- ++ +[NOTE] +When you use the label selector, the mentioned labels must be present on the resource. + +.Procedure +* The Tekton plugin is pre-loaded in {product-very-short} with basic configuration properties. To enable it, set the disabled property to false as follows: ++ +-- +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-community-plugin-tekton + disabled: false +---- +-- diff --git a/modules/dynamic-plugins/proc-using-argo-cd.adoc b/modules/dynamic-plugins/proc-using-argo-cd.adoc new file mode 100644 index 0000000000..2046c92527 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-argo-cd.adoc @@ -0,0 +1,34 @@ += Using the Argo CD plugin + +You can use the Argo CD plugin to visualize the Continuous Delivery (CD) workflows in OpenShift GitOps. This plugin provides a visual overview of the application’s status, deployment details, commit message, author of the commit, container image promoted to environment and deployment history. + +.Prerequisites + +* You have enabled the Argo CD plugin in {product} {product-very-short}. + +.Procedure + +. Select the *Catalog* tab and choose the component that you want to use. + +. Select the *CD* tab to view insights into deployments managed by Argo CD. + ++ +image::rhdh-plugins-reference/argocd.png[CD tab Argo CD] + +. Select an appropriate card to view the deployment details (for example, commit message, author name, and deployment history). + ++ +image::rhdh-plugins-reference/sidebar.png[Sidebar] + +.. Click the link icon (image:rhdh-plugins-reference/link.png[Link icon]) to open the deployment details in Argo CD. + +. Select the *Overview* tab and navigate to the Deployment summary section to review the summary of your application's deployment across namespaces. Additionally, select an appropriate Argo CD app to open the deployment details in Argo CD, or select a commit ID from the Revision column to review the changes in GitLab or GitHub. + ++ +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-plugins-book-url}[{installing-and-viewing-plugins-book-title}]. diff --git a/modules/dynamic-plugins/proc-using-jfrog-artifactory-plugin.adoc b/modules/dynamic-plugins/proc-using-jfrog-artifactory-plugin.adoc new file mode 100644 index 0000000000..9fbd956e16 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-jfrog-artifactory-plugin.adoc @@ -0,0 +1,31 @@ +[id="using-jfrog-artifactory_{context}"] += Using the JFrog Artifactory plugin + +The JFrog Artifactory plugin displays information about your container images within the Jfrog Artifactory registry. + +[IMPORTANT] +==== +The JFrog Artifactory plugin is a Technology Preview feature only. + +Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information on Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope]. + +Additional detail on how Red Hat provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page. +==== + +.Prerequisites + +* Your {product-short} application is installed and running. +* You have enabled the JFrog Artifactory plugin. + +.Procedure + +. Open your {product-short} application and select a component from the *Catalog* page. +. Go to the *Image Registry* tab. + ++ +The *Image Registry* tab contains a list of container images within your Jfrog Artifactory repository and related information, such as *Version*, *Repositories*, *Manifest*, *Modified*, and *Size*. + ++ +image::rhdh-plugins-reference/jfrog-artifactory.png[image-registry-tab-jfrog-artifactory] diff --git a/modules/dynamic-plugins/proc-using-keycloak.adoc b/modules/dynamic-plugins/proc-using-keycloak.adoc new file mode 100644 index 0000000000..5a427b6ae5 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-keycloak.adoc @@ -0,0 +1,25 @@ +[id="rhdh-keycloak_{context}"] += Using Keycloak + +The Keycloak backend plugin, which integrates Keycloak into {product-short}, has the following capabilities: + +* Synchronization of Keycloak users in a realm. +* Synchronization of Keycloak groups and their users in a realm. + +== Importing 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. +==== + +.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. diff --git a/modules/dynamic-plugins/proc-using-nexus.adoc b/modules/dynamic-plugins/proc-using-nexus.adoc new file mode 100644 index 0000000000..2b2443a683 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-nexus.adoc @@ -0,0 +1,33 @@ += Using the Nexus Repository Manager plugin + +The Nexus Repository Manager plugin displays the information about your build artifacts in your {product-short} application. The build artifacts are available in the Nexus Repository Manager. + +[IMPORTANT] +==== +The Nexus Repository Manager plugin is a Technology Preview feature only. + +Technology Preview features are not supported with {company-name} production service level agreements (SLAs), might not be functionally complete, and {company-name} does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information on {company-name} Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Scope]. + +Additional detail on how {company-name} provides support for bundled community dynamic plugins is available on the https://access.redhat.com/policy/developerhub-support-policy[{company-name} Developer Support Policy] page. +==== + +The Nexus Repository Manager is a front-end plugin that enables you to view the information about build artifacts. + +.Prerequisites + +- Your {product-short} application is installed and running. +- You have installed the Nexus Repository Manager plugin. +//For the installation process, see xref:installing-configuring-nexus-plugin[Installing and configuring the Nexus Repository Manager plugin]. + +.Procedure + +1. Open your {product-short} application and select a component from the *Catalog* page. +2. Go to the *BUILD ARTIFACTS* tab. ++ +-- +The *BUILD ARTIFACTS* tab contains a list of build artifacts and related information, such as *VERSION*, *REPOSITORY*, *REPOSITORY TYPE*, *MANIFEST*, *MODIFIED*, and *SIZE*. + +image::rhdh-plugins-reference/nexus-repository-manager.png[nexus-repository-manager-tab] +-- diff --git a/modules/dynamic-plugins/proc-using-tekton.adoc b/modules/dynamic-plugins/proc-using-tekton.adoc new file mode 100644 index 0000000000..93951912b2 --- /dev/null +++ b/modules/dynamic-plugins/proc-using-tekton.adoc @@ -0,0 +1,22 @@ +[[installation-and-configuration-tekton]] += Using the Tekton plugin + +You can use the Tekton plugin to visualize the results of CI/CD pipeline runs on your Kubernetes or OpenShift clusters. The plugin allows users to visually see high level status of all associated tasks in the pipeline for their applications. + +You can use the Tekton front-end plugin to view `PipelineRun` resources. + +.Prerequisites +* You have installed the {product} ({product-very-short}). +* You have installed the Tekton plugin. For the installation process, see xref:installation-and-configuration-tekton[Installing and configuring the Tekton plugin]. + +.Procedure +. Open your {product-very-short} application and select a component from the *Catalog* page. +. Go to the *CI* tab. ++ +The *CI* tab displays the list of PipelineRun resources associated with a Kubernetes cluster. The list contains pipeline run details, such as *NAME*, *VULNERABILITIES*, *STATUS*, *TASK STATUS*, *STARTED*, and *DURATION*. ++ +image::rhdh-plugins-reference/tekton-plugin-pipeline.png[ci-cd-tab-tekton] + +. Click the expand row button besides PipelineRun name in the list to view the PipelineRun visualization. The pipeline run resource includes tasks to complete. When you hover the mouse pointer on a task card, you can view the steps to complete that particular task. ++ +image::rhdh-plugins-reference/tekton-plugin-pipeline-expand.png[ci-cd-tab-tekton] diff --git a/modules/dynamic-plugins/ref-configuring-the-keycloak-plugin.adoc b/modules/dynamic-plugins/ref-configuring-the-keycloak-plugin.adoc new file mode 100644 index 0000000000..279cc75050 --- /dev/null +++ b/modules/dynamic-plugins/ref-configuring-the-keycloak-plugin.adoc @@ -0,0 +1,164 @@ +[id="proc-configuring-the-keycloak-plugin"] += Configuring the Keycloak plugin + +.Schedule configuration +You can configure a schedule in the `{my-app-config-file}` file, as follows: + +[source,yaml] +---- + catalog: + providers: + keycloakOrg: + default: + # ... + # highlight-add-start + schedule: # optional; same options as in TaskScheduleDefinition + # supports cron, ISO duration, "human duration" as used in code + frequency: { minutes: 1 } + # supports ISO duration, "human duration" as used in code + timeout: { minutes: 1 } + initialDelay: { seconds: 15 } + # highlight-add-end +---- + +[NOTE] +==== +If you have made any changes to the schedule in the `{my-app-config-file}` file, then restart to apply the changes. +==== + +.Keycloak query parameters + +You can override the default Keycloak query parameters in the `{my-app-config-file}` file, as follows: + +[source,yaml] +---- + catalog: + providers: + keycloakOrg: + default: + # ... + # highlight-add-start + userQuerySize: 500 # Optional + groupQuerySize: 250 # Optional + # highlight-add-end +---- + +Communication between {product-short} and Keycloak is enabled by using the Keycloak API. Username and password, or client credentials are supported authentication methods. + + +The following table describes the parameters that you can configure to enable the plugin under `catalog.providers.keycloakOrg.` object in the `{my-app-config-file}` file: + +|=== +| Name | Description | Default Value | Required + +| `baseUrl` +| Location of the Keycloak server, such as `pass:c[https://localhost:8443/auth]`. +| "" +| Yes + +| `realm` +| Realm to synchronize +| `master` +| No + +| `loginRealm` +| Realm used to authenticate +| `master` +| No + +| `username` +| Username to authenticate +| "" +| Yes if using password based authentication + +| `password` +| Password to authenticate +| "" +| Yes if using password based authentication + +| `clientId` +| Client ID to authenticate +| "" +| Yes if using client credentials based authentication + +| `clientSecret` +| Client Secret to authenticate +| "" +| Yes if using client credentials based authentication + +| `userQuerySize` +| Number of users to query at a time +| `100` +| No + +| `groupQuerySize` +| Number of groups to query at a time +| `100` +| No +|=== + +When using client credentials, the access type must be set to `confidential` and service accounts must be enabled. You must also add the following roles from the `realm-management` client role: + +* `query-groups` +* `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. +==== + +== 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}: + +`NODE_TLS_REJECT_UNAUTHORIZED=0` + +[NOTE] +==== +The solution of setting the environment variable is not recommended. +==== \ No newline at end of file