diff --git a/.github/workflows/generate-supported-plugins-pr.yml b/.github/workflows/generate-supported-plugins-pr.yml new file mode 100644 index 0000000000..ed936b679c --- /dev/null +++ b/.github/workflows/generate-supported-plugins-pr.yml @@ -0,0 +1,45 @@ +name: Generate update PR for the Dynamic Plugins tables + +on: + workflow_dispatch: + inputs: + branch: + description: "Branch to run the script from" + required: true + default: "main" + +jobs: + run-script: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: ${{ github.event.inputs.branch }} + fetch-depth: 0 + + - name: Install PIP `yq` + run: | + python3 -m pip install --upgrade pip + pip install yq + echo "Installed `yq` version: $(yq --version)" + + - name: Set up Git user + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "github-actions[bot]@users.noreply.github.com" + + - name: Generate timestamp + run: echo "TIMESTAMP=$(date +'%Y%m%d-%H%M%S' -u)" >> $GITHUB_ENV + + - name: Run the script on branch + run: bash modules/dynamic-plugins/rhdh-supported-plugins.sh -b ${{ github.event.inputs.branch }} + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + commit-message: "chore: automated update of supported plugins list" + title: "Automated update of supported plugins list for ${{ github.event.inputs.branch }}" + body: "This PR was automatically generated by running rhdh-supported-plugins.sh." + branch: "update-${{ github.event.inputs.branch }}-${{ env.TIMESTAMP }}" + base: ${{ github.event.inputs.branch }} diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index db23e741df..a9697cb176 100644 --- a/artifacts/attributes.adoc +++ b/artifacts/attributes.adoc @@ -10,10 +10,12 @@ :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.6 +:product-bundle-version: 1.6.0 +:product-chart-version: 1.6.0 +:product-backstage-version: 1.36.1 :product-custom-resource-type: Backstage :rhdeveloper-name: Red Hat Developer :rhel: Red Hat Enterprise Linux @@ -47,7 +49,7 @@ :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 @@ -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/introduction_to_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 diff --git a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc index 41e5294fd0..f683c8bb2c 100644 --- a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-admin.adoc @@ -70,9 +70,162 @@ global: disabled: false ---- +== 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 Backstage 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 `app-config.yaml` file in your Backstage 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 Backstage. + +.. 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-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}]. diff --git a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-readme.adoc b/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-readme.adoc index 681434ddc2..306101bfc2 100644 --- a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-readme.adoc +++ b/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}]. diff --git a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-user.adoc b/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-user.adoc index 2b7b1d4139..c82da2d9f4 100644 --- a/artifacts/rhdh-plugins-reference/argocd/argocd-plugin-user.adoc +++ b/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}]. diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-readme.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-readme.adoc index 263061178e..754855509a 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-readme.adoc +++ b/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] diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.adoc index cf91a17ba0..5a427b6ae5 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.adoc +++ b/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. diff --git a/artifacts/snip-developer-preview.adoc b/artifacts/snip-developer-preview.adoc new file mode 100644 index 0000000000..11360d5257 --- /dev/null +++ b/artifacts/snip-developer-preview.adoc @@ -0,0 +1,6 @@ +[IMPORTANT] +==== +This section describes Developer Preview features in the Adoption Insights plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== diff --git a/artifacts/snip-rhdh-install-operator-next-steps.adoc b/artifacts/snip-rhdh-install-operator-next-steps.adoc new file mode 100644 index 0000000000..95d34e048b --- /dev/null +++ b/artifacts/snip-rhdh-install-operator-next-steps.adoc @@ -0,0 +1,9 @@ +[id='snip-rhdh-install-operator-next-steps_{context}'] + +.Next steps +* Use the Operator to create a {product} instance on a supported platform. For more information, see the following documentation for the platform that you want to use: +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_container_platform/assembly-install-rhdh-ocp-operator[Installing {product} on {ocp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_amazon_elastic_kubernetes_service/proc-rhdh-deploy-eks-operator_title-install-rhdh-eks[Installing {product-short} on {eks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_microsoft_azure_kubernetes_service/proc-rhdh-deploy-aks-operator_title-install-rhdh-aks[Installing {product-short} on {aks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_dedicated_on_google_cloud_platform/proc-install-rhdh-osd-gcp-operator_title-install-rhdh-osd-gcp[Installing {product-short} on {gcp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_google_kubernetes_engine/proc-rhdh-deploy-gke-operator.adoc_title-install-rhdh-gke#proc-deploy-rhdh-instance-gke.adoc_title-install-rhdh-gke[Deploying {product-short} on {gke-short} with the Operator] diff --git a/assemblies/assembly-adoption-insights.adoc b/assemblies/assembly-adoption-insights.adoc new file mode 100644 index 0000000000..e0763e592d --- /dev/null +++ b/assemblies/assembly-adoption-insights.adoc @@ -0,0 +1,31 @@ +[id="assembly-adoption-insights"] += Adoption Insights + +include::../artifacts/snip-developer-preview.adoc[] + +//about adoption insights +include::modules/observe/adoption-insights/con-about-adoption-insights.adoc[leveloffset=+1] + +//installing adoption insights +include::modules/observe/adoption-insights/proc-install-adoption-insights.adoc[leveloffset=+1] + +//configuring adoption insights +include::modules/observe/adoption-insights/proc-configure-adoption-insights.adoc[leveloffset=+1] + +//using adoption insights +include::modules/observe/adoption-insights/proc-using-adoption-insights.adoc[leveloffset=+1] + +//setting data metrics +include::modules/observe/adoption-insights/proc-setting-duration-of-data-metrics.adoc[leveloffset=+2] + +//viewing cards +include::modules/observe/adoption-insights/proc-viewing-adoption-insights-card.adoc[leveloffset=+1] + +//modify number of displayed records +include::modules/observe/adoption-insights/proc-modify-number-of-displayed-records.adoc[leveloffset=+1] + +//filter records +include::modules/observe/adoption-insights/proc-filter-records-to-display-spec.adoc[leveloffset=+1] + +//viewing searches +include::modules/observe/adoption-insights/proc-viewing-searches.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-audit-log.adoc b/assemblies/assembly-audit-log.adoc index b6940d3f7b..baeb4476f0 100644 --- a/assemblies/assembly-audit-log.adoc +++ b/assemblies/assembly-audit-log.adoc @@ -30,17 +30,9 @@ Audit logs are not forwarded to the internal log store by default because this d .Additional resources * For more information about logging in {ocp-short}, see link:https://docs.openshift.com/container-platform/latest/observability/logging/cluster-logging.html[About Logging] -* For a complete list of fields that a {product-short} audit log can include, see xref:ref-audit-log-fields.adoc_{context}[] -* For a list of scaffolder events that a {product-short} audit log can include, see xref:ref-audit-log-scaffolder-events.adoc_{context}[] include::modules/observe/con-audit-log-config.adoc[] include::modules/observe/proc-forward-audit-log-splunk.adoc[leveloffset=+2] -include::modules/observe/proc-audit-log-view.adoc[] - -include::modules/observe/ref-audit-log-fields.adoc[leveloffset=+2] - -include::modules/observe/ref-audit-log-scaffolder-events.adoc[leveloffset=+2] - -include::modules/observe/ref-audit-log-catalog-events.adoc[leveloffset=+2] +include::modules/observe/proc-audit-log-view.adoc[] \ No newline at end of file diff --git a/assemblies/assembly-authenticating-with-rhbk.adoc b/assemblies/assembly-authenticating-with-rhbk.adoc index fd2439dbda..6b124ba27d 100644 --- a/assemblies/assembly-authenticating-with-rhbk.adoc +++ b/assemblies/assembly-authenticating-with-rhbk.adoc @@ -1,11 +1,6 @@ [id="assembly-authenticating-with-rhbk"] = Authenticating with {rhbk-brand-name} ({rhbk}) -[NOTE] -==== -{rhsso} 7.6 is deprecated as an authentication provider. You can continue using {rhsso} until the end of its maintenance support. For more information, see link:https://access.redhat.com/support/policy/updates/jboss_notes#p_sso[{rhsso} lifecycle dates]. As an alternative, consider migrating to {rhbk-brand-name} ({rhbk}). -==== - To authenticate users with {rhbk-brand-name} ({rhbk}): . xref:enabling-authentication-with-rhbk[Enable the OpenID Connect (OIDC) authentication provider in RHDH]. diff --git a/assemblies/assembly-configuring-a-floating-action-button.adoc b/assemblies/assembly-configuring-a-floating-action-button.adoc new file mode 100644 index 0000000000..95d6156ee7 --- /dev/null +++ b/assemblies/assembly-configuring-a-floating-action-button.adoc @@ -0,0 +1,8 @@ +:_mod-docs-content-type: ASSEMBLY +:context: configuring-a-floating-action-button +[id="{context}"] += Configuring a floating action button in {product} + +You can use the floating action button plugin to configure any action as a floating button in the {product-short} instance. The floating action button plugin is enabled by default. You can also configure floating action buttons to display as submenu options within the main floating action button by assigning the floating action buttons to the same `slot` field of your `dynamic-plugins.yaml` file. + +include::modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-configuring-authorization-in-rhdh.adoc b/assemblies/assembly-configuring-authorization-in-rhdh.adoc index 73e4daada3..37d9b8f708 100644 --- a/assemblies/assembly-configuring-authorization-in-rhdh.adoc +++ b/assemblies/assembly-configuring-authorization-in-rhdh.adoc @@ -1,26 +1,18 @@ [id='configuring-authorization-in-rhdh'] = Configuring authorization in {product} -In link:{authorization-book-url}[{authentication-book-title}], you learnt how to authenticate users to {product}. -{product-short} knowns who the users are. +Administrators can authorize users to perform actions and define what users can do in {product-short}. -In this book, learn how to authorize users to perform actions in {product-short}. -Define what users can do in {product-short}. +Role-based access control (RBAC) is a security concept that defines how to control access to resources in a system by specifying a mapping between users of the system and the actions that those users can perform on resources in the system. +You can use RBAC to define roles with specific permissions and then assign the roles to users and groups. -Role-Based Access Control (RBAC) is a security concept that controls access to resources in a system, and specifies a mapping between users of the system, and the actions they can perform on resources in the system. -You define roles with specific permissions, and then assign the roles to users and groups. +RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code. Rather than defining policies in code, you can use the {product-short} RBAC feature to define policies in a declarative fashion by using a simple CSV based format. You can define the policies by using {product-short} web interface or REST API instead of editing the CSV directly. -RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code. -Rather than defining policies in code, -the {product-short} RBAC feature allows you -to define policies in a declarative fashion using a simple CSV based format. -You can define the policies by using {product-short} web interface or REST API, rather than editing the CSV directly. +An administrator can define authorizations in {product-short} by taking the following steps: -To define authorizations in {product-short}: +. Enable the RBAC feature and give authorized users access to the feature. -. The {product-short} administrator enables and gives access to the RBAC feature. - -. You define your roles and policies by combining the following methods: +. Define roles and policies by combining the following methods: * The {product-short} policy administrator uses the {product-short} web interface or REST API. * The {product-short} administrator edits the main {product-short} configuration file. @@ -41,6 +33,10 @@ include::assembly-managing-authorizations-by-using-the-rest-api.adoc[leveloffset include::assembly-managing-authorizations-by-using-external-files.adoc[leveloffset=+1] +include::assembly-configuring-guest-access-with-rbac-ui.adoc[leveloffset=+1] + +include::modules/authorization/proc-delegating-rbac-access.adoc[leveloffset=+1] + include::modules/authorization/ref-rbac-permission-policies.adoc[leveloffset=+1] @@ -54,4 +50,3 @@ include::modules/authorization/con-user-stats-rhdh.adoc[leveloffset=+1] include::modules/authorization/proc-download-user-stats-rhdh.adoc[leveloffset=+2] - diff --git a/assemblies/assembly-configuring-default-secret-pvc-mounts.adoc b/assemblies/assembly-configuring-default-secret-pvc-mounts.adoc new file mode 100644 index 0000000000..af8710113c --- /dev/null +++ b/assemblies/assembly-configuring-default-secret-pvc-mounts.adoc @@ -0,0 +1,9 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-configuring-default-secret-pvc-mounts_{context}"] += Configuring default mounts for Secrets and PVCs + +You can configure Persistent Volume Claims (PVCs) and Secrets mount in your {product} deployment. Use annotations to define the custom mount paths and specify the containers to mount them to. + +include::modules/configuring-external-databases/proc-configuring-mount-paths.adoc[leveloffset=+1] + +include::modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-configuring-guest-access-with-rbac-ui.adoc b/assemblies/assembly-configuring-guest-access-with-rbac-ui.adoc new file mode 100644 index 0000000000..ed01bbe3b0 --- /dev/null +++ b/assemblies/assembly-configuring-guest-access-with-rbac-ui.adoc @@ -0,0 +1,13 @@ +[id="configuring-guest-access-with-rbac-ui_{context}"] += Configuring guest access with RBAC UI + +Use guest access with the role-based access control (RBAC) front-end plugin to allow a user to test role and policy creation without the need to set up and configure an authentication provider. + +[NOTE] +==== +Guest access is not recommended for production. +==== + +include::modules/authorization/proc-configuring-the-RBAC-backend-plugin.adoc[leveloffset=+1] + +include::modules/authorization/proc-setting-up-the-guest-authentication-provider.adoc[leveloffset=+1] diff --git a/assemblies/assembly-configuring-high-availability.adoc b/assemblies/assembly-configuring-high-availability.adoc new file mode 100644 index 0000000000..0326720f35 --- /dev/null +++ b/assemblies/assembly-configuring-high-availability.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +:context: HighAvailability +[id="{context}"] += Configuring high availability in {product} + + +High availability (HA) is a system design approach that ensures a service remains continuously accessible, even during failures of individual components, by eliminating single points of failure. It introduces redundancy and failover mechanisms to minimize downtime and maintain operational continuity. + +{product} supports HA deployments on {ocp-brand-name} and {aks-name}. The HA deployments enable more resilient and reliable service availability across supported environments. + +In a single instance deployment, if a failure occurs, whether due to software crashes, hardware issues, or other unexpected disruptions, it would make the entire service unavailable, interrupting development workflows and access to key resources. + +With HA enabled, you can scale the number of backend replicas to introduce redundancy. This setup ensures that if one pod or component fails, others continue to serve requests without disruption. The built-in load balancer manages ingress traffic and distributes the load across the available pods. Meanwhile, the {product-very-short} backend manages concurrent requests and resolves resource-level conflicts effectively. + +As an administrator, you can configure high availability by adjusting replica values in your configuration file: + +* If you installed using the Operator, configure the replica values in your `{product-custom-resource-type}` custom resource. +* If you used the Helm chart, set the replica values in the Helm configuration. + +include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc[leveloffset=+1] + +include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-configuring-readonlyrootfilesystem.adoc b/assemblies/assembly-configuring-readonlyrootfilesystem.adoc new file mode 100644 index 0000000000..e43b2ac7ce --- /dev/null +++ b/assemblies/assembly-configuring-readonlyrootfilesystem.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +:context: readonlyrootfilesystem +[id="{context}"] += Configuring readOnlyRootFilesystem in {product} + +The {product} deployment consists of two containers: an `initContainer` that installs the Dynamic Plugins, and a backend container that runs the application. The `initContainer` has the `readOnlyRootFilesystem` option enabled by default. To enable this option on the backend container, you must either have permission to deploy resources through Helm or to create or update a CR for Operator-backed deployments. You can manually configure the `readOnlyRootFilesystem` option on the backend container by using the following methods: + +* The {product} Operator +* The {product} Helm chart + +include::modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment.adoc[leveloffset=+1] + +include::modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-configuring-techdocs.adoc b/assemblies/assembly-configuring-techdocs.adoc index 2242fb5151..8afb63a65e 100644 --- a/assemblies/assembly-configuring-techdocs.adoc +++ b/assemblies/assembly-configuring-techdocs.adoc @@ -1,26 +1,9 @@ :_mod-docs-content-type: ASSEMBLY :context: configuring-techdocs [id="{context}"] -= Configuring TechDocs += TechDocs configuration -Configure the {product} TechDocs plugin to create, find, and use documentation in a central location and in a standardized way. For example: - -Docs-like-code approach:: -Write your technical documentation in Markdown files that are stored inside your project repository along with your code. - -Documentation site generation:: -Use MkDocs to create a full-featured, Markdown-based, static HTML site for your documentation that is rendered centrally in {product-short}. - -Documentation site metadata and integrations:: -See additional metadata about the documentation site alongside the static documentation, such as the date of the last update, the site owner, top contributors, open GitHub issues, Slack support channels, and Stack Overflow Enterprise tags. - -Built-in navigation and search:: -Find the information that you want from a document more quickly and easily. - -Add-ons:: -Customize your TechDocs experience with Add-ons to address higher-order documentation needs. - -The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator config map. +The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator ConfigMap. [IMPORTANT] ==== @@ -34,34 +17,24 @@ After you configure {odf-name} to store the files that TechDocs generates, you c [role="_additional-resources"] .Additional resources -* For more information, see link:{LinkPluginsGuide}[Configuring plugins in {product}]. +* For more information, see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}]. include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1] - include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2] - include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+2] - include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+3] - include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+2] - include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+3] - include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1] - include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2] - include::modules/customizing-techdocs/proc-techdocs-generate-site.adoc[leveloffset=+2] - include::modules/customizing-techdocs/proc-techdocs-publish-site.adoc[leveloffset=+2] - diff --git a/assemblies/assembly-configuring-the-global-header.adoc b/assemblies/assembly-configuring-the-global-header.adoc new file mode 100644 index 0000000000..93badc6698 --- /dev/null +++ b/assemblies/assembly-configuring-the-global-header.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +:context: configuring-the-global-header-in-rhdh +[id="{context}"] += Configuring the global header in {product} + +As an administrator, you can configure the {product} global header to create a consistent and flexible navigation bar across your {product-short} instance. +By default, the {product-short} global header includes the following components: + +* *Self-service* button provides quick access to a variety of templates, enabling users to efficiently set up services, backend and front-end plugins within {product-short} +* *Support* button that can link an internal or external support page +* *Notifications* button displays alerts and updates from plugins and external services +* *Search* input field allows users to find services, components, documentation, and other resources within {product-short} +* *Plugin extension capabilities* provide a preinstalled and enabled catalog of available plugins in {product-short} +* *User profile* drop-down menu provides access to profile settings, appearance customization, {product-short} metadata, and a logout button + +include::modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc[leveloffset=+1] + + +include::modules/configuring-the-global-header/proc-mount-points.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-customizing-segment-source.adoc b/assemblies/assembly-customizing-segment-source.adoc new file mode 100644 index 0000000000..010cb9bca9 --- /dev/null +++ b/assemblies/assembly-customizing-segment-source.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="customizing-segment-source_{context}"] += Customizing Segment source + +The `analytics-provider-segment` plugin sends the collected web analytics data to {company-name} by default. However, you can configure a new Segment source that receives web analytics data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source. + +[NOTE] +==== +Create your own web analytics data collection notice for your application users. +==== + +include::modules/analytics/proc-customizing-segment-source-using-the-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc[leveloffset=+1] + +.Additional resources +* To learn how to collect and analyze the same set of data, see link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. \ No newline at end of file diff --git a/assemblies/assembly-customizing-the-appearance.adoc b/assemblies/assembly-customizing-the-appearance.adoc index dc1be2a9fd..041dd7057f 100644 --- a/assemblies/assembly-customizing-the-appearance.adoc +++ b/assemblies/assembly-customizing-the-appearance.adoc @@ -25,7 +25,18 @@ include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[ include::modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc[leveloffset=+1] -include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1] +include::modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1] + +include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-customizing-entity-tab-titles.adoc[leveloffset=+1] + + +include::modules/customizing-the-appearance/proc-customizing-entity-detail-tab-layout.adoc[leveloffset=+1] include::modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc[leveloffset=+1] @@ -45,4 +56,3 @@ include::modules/customizing-the-appearance/ref-customize-rhdh-default-backstage include::modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc[leveloffset=+1] include::modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc[leveloffset=+1] - diff --git a/assemblies/assembly-customizing-the-learning-paths.adoc b/assemblies/assembly-customizing-the-learning-paths.adoc new file mode 100644 index 0000000000..b70fc33aac --- /dev/null +++ b/assemblies/assembly-customizing-the-learning-paths.adoc @@ -0,0 +1,15 @@ +[id='proc-customize-rhdh-learning-paths_{context}'] += Customizing the Learning Paths in {product} + +In {product}, you can configure Learning Paths by hosting the required data externally, +and using the built-in proxy to deliver this data rather than the default. + +You can provide Learning Paths data from the following sources: + +* A JSON file hosted on a web server, such as GitHub or GitLab. +* A dedicated service that provides the Learning Paths data in JSON format using an API. + +include::modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-hosted-json-files.adoc[leveloffset=+1] + + +include::modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-a-dedicated-service.adoc[leveloffset=+1] diff --git a/assemblies/assembly-customizing-the-tech-radar-page.adoc b/assemblies/assembly-customizing-the-tech-radar-page.adoc new file mode 100644 index 0000000000..0ec1a64d5f --- /dev/null +++ b/assemblies/assembly-customizing-the-tech-radar-page.adoc @@ -0,0 +1,22 @@ +[id='proc-customizing-the-tech-radar-page_{context}'] += Customizing the Tech Radar page in {product} + +In {product}, the Tech Radar page is provided by the `tech-radar` dynamic plugin, which is disabled by default. For information about enabling dynamic plugins in {product} see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}]. + +In {product}, you can configure Learning Paths by passing the data into the `{my-app-config-file}` file as a proxy. The base Tech Radar URL must include the `/developer-hub/tech-radar` proxy. + +[NOTE] +==== +Due to the use of overlapping `pathRewrites` for both the `tech-radar` and `homepage` quick access proxies, you must create the `tech-radar` configuration (`^api/proxy/developer-hub/tech-radar`) before you create the `homepage` configuration (`^/api/proxy/developer-hub`). + +For more information about customizing the Home page in {product}, see xref:customizing-the-home-page[Customizing the Home page in {product}]. +==== + +You can provide data to the Tech Radar page from the following sources: + +* JSON files hosted on GitHub or GitLab. +* A dedicated service that provides the Tech Radar data in JSON format using an API. + +include::modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc[leveloffset=+1] + +include::modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc[leveloffset=+1] diff --git a/assemblies/assembly-disabling-telemetry-data-collection.adoc b/assemblies/assembly-disabling-telemetry-data-collection.adoc new file mode 100644 index 0000000000..421d49db5b --- /dev/null +++ b/assemblies/assembly-disabling-telemetry-data-collection.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: ASSEMBLY +[id="disabling-telemetry-data-collection_{context}"] += Disabling telemetry data collection in {product-very-short} + +To disable telemetry data collection, you must disable the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator configuration. + +As an administrator, you can disable the telemetry data collection feature based on your needs. For example, in an air-gapped environment, you can disable this feature to avoid needless outbound requests affecting the responsiveness of the {product-very-short} application. For more details, see the link:{telemetry-data-collection-book-url}#proc-disabling-telemetry-using-operator_title-telemetry[Disabling telemetry data collection in {product-very-short}] section. + +include::modules/analytics/proc-disabling-telemetry-using-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-disabling-telemetry-using-helm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/observe/ref-enabling-telemetry.adoc b/assemblies/assembly-enabling-telemetry-data-collection.adoc similarity index 64% rename from modules/observe/ref-enabling-telemetry.adoc rename to assemblies/assembly-enabling-telemetry-data-collection.adoc index 9df4622324..62fa2dc9dd 100644 --- a/modules/observe/ref-enabling-telemetry.adoc +++ b/assemblies/assembly-enabling-telemetry-data-collection.adoc @@ -1,5 +1,9 @@ +:_mod-docs-content-type: ASSEMBLY [id="enabling-telemetry-data-collection_{context}"] = Enabling telemetry data collection in {product-very-short} The telemetry data collection feature is enabled by default. However, if you have disabled the feature and want to re-enable it, you must enable the `analytics-provider-segment` plugin either by using the Helm Chart or the {product} Operator configuration. +include::modules/analytics/proc-enabling-telemetry-using-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-enabling-telemetry-using-helm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-install-rhdh-airgapped-environment-ocp-helm.adoc b/assemblies/assembly-install-rhdh-airgapped-environment-ocp-helm.adoc new file mode 100644 index 0000000000..660e97488c --- /dev/null +++ b/assemblies/assembly-install-rhdh-airgapped-environment-ocp-helm.adoc @@ -0,0 +1,12 @@ +[id="assembly-install-rhdh-airgapped-environment-ocp-helm_{context}"] += Installing {product} on {ocp-short} in an air-gapped environment with the Helm chart + +You can install {product} in a fully disconnected or partially disconnected environment using the {product} Helm chart. + +[role="_additional-resources"] +.Additional resources +* For more information about registry authentication, see https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. + +include::modules/installation/proc-install-rhdh-helm-airgapped-full.adoc[leveloffset=+1] + +include::modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-install-rhdh-airgapped-environment-ocp-operator.adoc b/assemblies/assembly-install-rhdh-airgapped-environment-ocp-operator.adoc new file mode 100644 index 0000000000..7de6c7bd60 --- /dev/null +++ b/assemblies/assembly-install-rhdh-airgapped-environment-ocp-operator.adoc @@ -0,0 +1,9 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-install-rhdh-airgapped-environment-ocp-operator_{context}"] += Installing {product} in an air-gapped environment with the Operator + +You can install {product} in a fully disconnected or partially disconnected environment using the {product} Operator. For a list of supported platforms, see the link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle page]. + +include::modules/installation/proc-install-rhdh-operator-airgapped-full.adoc[leveloffset=+1] + +include::modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-install-rhdh-eks-operator.adoc b/assemblies/assembly-install-rhdh-eks-operator.adoc new file mode 100644 index 0000000000..457e182e71 --- /dev/null +++ b/assemblies/assembly-install-rhdh-eks-operator.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-install-rhdh-eks-operator"] += Installing {product-short} on {eks-short} with the Operator + +The {product} Operator installation requires the Operator Lifecycle Manager (OLM) framework. + +.Additional resources +* For information about the OLM, see link:https://olm.operatorframework.io/docs/[Operator Lifecycle Manager(OLM)] documentation. + +include::modules/installation/proc-rhdh-deploy-eks-operator.adoc[leveloffset=+1] diff --git a/assemblies/assembly-logging-with-amazon-cloudwatch.adoc b/assemblies/assembly-logging-with-amazon-cloudwatch.adoc new file mode 100644 index 0000000000..3d3c7b9057 --- /dev/null +++ b/assemblies/assembly-logging-with-amazon-cloudwatch.adoc @@ -0,0 +1,16 @@ +[id="assembly-logging-with-amazon-cloudwatch_{context}"] += Logging with Amazon CloudWatch + +Logging within the {product} relies on the link:https://github.com/winstonjs/winston[Winston library]. +The default logging level is `info`. +To have more detailed logs, set the `LOG_LEVEL` environment variable to `debug` in your {product} instance. + + +include::modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-operator.adoc[leveloffset=+1] + + +include::modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-helm-chart.adoc[leveloffset=+1] + + +include::modules/observe/proc-retrieving-logs-from-amazon-cloudwatch.adoc[leveloffset=+1] + diff --git a/assemblies/assembly-managing-labels-annotations-topology.adoc b/assemblies/assembly-managing-labels-annotations-topology.adoc new file mode 100644 index 0000000000..ca5d269af6 --- /dev/null +++ b/assemblies/assembly-managing-labels-annotations-topology.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-managing-labels-annotations-topology"] += Managing labels and annotations for Topology plugins +:context: assembly-managing-labels-annotations-topology + +include::modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-entity-annotation-or-label.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-namespace-annotation.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-label-selector-query-annotation.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-app-grouping.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-node-connector.adoc[leveloffset=+1] + +For more information about the labels and annotations, see _Guidelines for labels and annotations for OpenShift applications_. \ No newline at end of file diff --git a/assemblies/assembly-monitoring-and-logging-with-aws.adoc b/assemblies/assembly-monitoring-and-logging-with-aws.adoc new file mode 100644 index 0000000000..5e90e14d8f --- /dev/null +++ b/assemblies/assembly-monitoring-and-logging-with-aws.adoc @@ -0,0 +1,11 @@ +[id="assembly-monitoring-and-logging-with-aws_{context}"] += Monitoring and logging {product} on {aws-brand-name} ({aws-short}) + +You can configure {product} to use Amazon CloudWatch for real-time monitoring and Amazon Prometheus for comprehensive logging. +This is convenient when hosting {product-short} on {aws-brand-name} ({aws-short}) infrastructure. + +include::assembly-monitoring-with-amazon-prometheus.adoc[leveloffset=+1] + + +include::assembly-logging-with-amazon-cloudwatch.adoc[leveloffset=+1] + diff --git a/assemblies/assembly-monitoring-with-amazon-prometheus.adoc b/assemblies/assembly-monitoring-with-amazon-prometheus.adoc new file mode 100644 index 0000000000..5f31e876df --- /dev/null +++ b/assemblies/assembly-monitoring-with-amazon-prometheus.adoc @@ -0,0 +1,22 @@ +[id="assembly-monitoring-with-amazon-prometheus_{context}"] += Monitoring with Amazon Prometheus + +You can configure {product} to use Amazon Prometheus for comprehensive logging. +Amazon Prometheus extracts data from pods that have specific pod annotations. + +== Prerequisites + +* You link:https://docs.aws.amazon.com/eks/latest/userguide/prometheus.htm[configured Prometheus for your {eks-name} ({eks-short}) clusters]. +* You link:https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-create-workspace.html[created an Amazon managed service for the Prometheus workspace]. +* You link:https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-ingest-metrics.html[configured Prometheus to import the {product-short} metrics]. +* You ingested Prometheus metrics into the created workspace. + + +include::modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-operator.adoc[leveloffset=+1] + + +include::modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-helm-chart.adoc[leveloffset=+1] + + + + diff --git a/assemblies/assembly-release-notes-fixed-security-issues.adoc b/assemblies/assembly-release-notes-fixed-security-issues.adoc deleted file mode 100644 index a741a16d1a..0000000000 --- a/assemblies/assembly-release-notes-fixed-security-issues.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:_content-type: ASSEMBLY -[id="fixed-security-issues"] -= Fixed security issues - -This section lists security issues fixed in {product} {product-version}. - -== {product} {product-bundle-version} - -include::modules/release-notes/snip-fixed-security-issues-in-product-1.3.0.adoc[leveloffset=+2] - -include::modules/release-notes/snip-fixed-security-issues-in-rpm-1.3.0.adoc[leveloffset=+2] - diff --git a/assemblies/assembly-rhdh-telemetry.adoc b/assemblies/assembly-rhdh-telemetry.adoc deleted file mode 100644 index 00ee46fdda..0000000000 --- a/assemblies/assembly-rhdh-telemetry.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="assembly-rhdh-telemetry"] -= Telemetry data collection - -The telemetry data collection feature helps in collecting and analyzing the telemetry data to improve your experience with {product}. This feature is enabled by default. - -[IMPORTANT] -==== -As an administrator, you can disable the telemetry data collection feature based on your needs. For example, in an air-gapped environment, you can disable this feature to avoid needless outbound requests affecting the responsiveness of the {product-very-short} application. For more details, see the link:{telemetry-data-collection-book-url}#proc-disabling-telemetry-using-operator_title-telemetry[Disabling telemetry data collection in {product-very-short}] section. -==== - -{company-name} collects and analyzes the following data: - -* Events of page visits and clicks on links or buttons. -* System-related information, for example, locale, timezone, user agent including browser and OS details. -* Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters. -* Anonymized IP addresses, recorded as `0.0.0.0`. -* Anonymized username hashes, which are unique identifiers used solely to identify the number of unique users of the {product-very-short} application. - -With {product-very-short}, you can customize the telemetry data collection feature and the telemetry Segment source configuration based on your needs. - - -// disabling telemetry -include::modules/observe/ref-disabling-telemetry.adoc[leveloffset=+1] - -include::modules/observe/proc-disabling-telemetry-using-operator.adoc[leveloffset=+2] - -include::modules/observe/proc-disabling-telemetry-using-helm.adoc[leveloffset=+2] - -// enabling telemetry -include::modules/observe/ref-enabling-telemetry.adoc[leveloffset=+1] - -include::modules/observe/proc-enabling-telemetry-using-operator.adoc[leveloffset=+2] - -include::modules/observe/proc-enabling-telemetry-using-helm.adoc[leveloffset=+2] - -// customizing telemetry segment source -include::modules/observe/ref-customizing-telemetry-segment.adoc[leveloffset=+1] - -include::modules/observe/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+2] - -include::modules/observe/proc-customizing-telemetry-segment-using-helm.adoc[leveloffset=+2] diff --git a/assemblies/assembly-techdocs-add-docs.adoc b/assemblies/assembly-techdocs-add-docs.adoc new file mode 100644 index 0000000000..ed5a306e10 --- /dev/null +++ b/assemblies/assembly-techdocs-add-docs.adoc @@ -0,0 +1,8 @@ +:_mod-docs-content-type: ASSEMBLY +:context: assembly-techdocs-add-docs +[id="{context}"] += Adding documentation to TechDocs + +After an administrator configures the TechDocs plugin, a developer can add documentation to TechDocs by importing it from a remote repository. Any authorized user or group can access the documentation that is imported into the TechDocs plugin. + +include::modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc[leveloffset=+1] diff --git a/assemblies/assembly-techdocs-addons-installing.adoc b/assemblies/assembly-techdocs-addons-installing.adoc new file mode 100644 index 0000000000..9acaa7ef95 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-installing.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-installing +[id="techdocs-addon-installing"] += Installing and configuring a TechDocs add-on + +TechDocs add-ons supported by {company-name} are exported to the TechDocs plugin by the`backstage-plugin-techdocs-module-addons-contrib` plugin package, which is preinstalled on {product} and enabled by default. The `` add-on is part of the default configuration of this plugin package and comes ready to use in the TechDocs plugin. + +You can install other supported TechDocs add-ons by configuring the`backstage-plugin-techdocs-module-addons-contrib` plugin package in the {product} ConfigMap or Helm chart, depending on whether you use the Operator or Helm chart for installation. If you want to customize your TechDocs experience beyond the functions of the supported add-ons, you can install third-party add-ons on your TechDocs plugin, including add-ons that you create yourself. + +include::modules/techdocs/proc-techdocs-addon-install-operator.adoc[] + +include::modules/techdocs/proc-techdocs-addon-install-helm.adoc[] + +include::modules/techdocs/proc-techdocs-addon-install-third-party.adoc[] + +.Additional resources +* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about[Installing dynamic plugins in Red Hat Developer Hub] +* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/assembly-third-party-plugins[Third-party plugins in Red Hat Developer Hub] diff --git a/assemblies/assembly-techdocs-addons-removing.adoc b/assemblies/assembly-techdocs-addons-removing.adoc new file mode 100644 index 0000000000..ce6c9c9af3 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-removing.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-removing +[id="techdocs-addon-removing"] += Removing a TechDocs add-on + +Administrators can remove installed TechDocs add-ons from your {product} instance by using either the Operator or Helm chart, depending on the method used to install the add-on. If you used the Operator to install the add-on, remove it from the ConfigMap. If you used the Helm chart to install the add-on, remove it from the Helm chart. + +If you want to disable a plugin instead of removing it from your {product} instance, you can disable the plugin that you are using to import the TechDocs add-on. Since the `disabled` status is controlled at the plugin level, disabling the plugin disables all of the TechDocs add-ons in the specified plugin package. + +include::modules/techdocs/proc-techdocs-addon-remove-operator.adoc[] + +include::modules/techdocs/proc-techdocs-addon-remove-helm.adoc[] diff --git a/assemblies/assembly-techdocs-addons-using.adoc b/assemblies/assembly-techdocs-addons-using.adoc new file mode 100644 index 0000000000..8fb4713e60 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-using.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-using +[id="techdocs-addon-using"] += Using TechDocs add-ons + +After an administrator installs a TechDocs add-on in your {product} instance, you can use it to extend the functionality of the TechDocs plugin and enhance your documentation experience. + +include::modules/techdocs/proc-techdocs-addon-use-report-issue.adoc[] + +include::modules/techdocs/proc-techdocs-addon-use-text-size.adoc[] + +include::modules/techdocs/proc-techdocs-addon-use-light-box.adoc[] diff --git a/assemblies/assembly-techdocs-addons.adoc b/assemblies/assembly-techdocs-addons.adoc new file mode 100644 index 0000000000..ea4f380c12 --- /dev/null +++ b/assemblies/assembly-techdocs-addons.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon +[id="techdocs-addon"] += TechDocs add-ons + +TechDocs add-ons are dynamic plugins that extend the functionality of the built-in TechDocs plugin. For example, you can use add-ons to report documentation issues, change text size, or view images in overlay in either the TechDocs Reader page or an Entity page. + +The following table describes the TechDocs add-ons that are available for {product} {product-version}: + +.TechDocs Add-ons available in {product} +|=== +| TechDocs Add-on | Package/Plugin | Description | Type + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation. The issue template is automatically populated with the selected text. +| Preinstalled + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Customize text size on documentation pages by increasing or decreasing the font size with a slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. +| External + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Open images in a light-box on documentation pages, to navigate to multiple images on a single page. The image size of the light-box image is the same as the image size on the document page. Clicking the zoom icon increases the image size to fit the screen. +| External + +//future release | `` +//future release | `backstage-plugin-techdocs-module-addons-contrib` +//future release | Expand or collapse the subtitles in the TechDocs navigation menu and keep your preferred state between documentation sites. +|=== + +The `backstage-plugin-techdocs-module-addons-contrib` plugin package exports both preinstalled and external add-ons supported by {company-name} to the TechDocs plugin. This plugin package is preinstalled on {product} and is enabled by default. If the plugin package is disabled, all of the TechDocs add-ons exported by the package as also disabled. diff --git a/assemblies/assembly-topology-plugin-configure.adoc b/assemblies/assembly-topology-plugin-configure.adoc new file mode 100644 index 0000000000..ad1157b65d --- /dev/null +++ b/assemblies/assembly-topology-plugin-configure.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-topology-plugin-configure"] += Configuring the Topology plugin +:context: assembly-topology-plugin-configure + +include::modules/dynamic-plugins/proc-viewing-openshift-routes.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-pod-logs.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-virtual-machines.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-using-kubernetes-custom-actions.adoc b/assemblies/assembly-using-kubernetes-custom-actions.adoc new file mode 100644 index 0000000000..f3610ed9bf --- /dev/null +++ b/assemblies/assembly-using-kubernetes-custom-actions.adoc @@ -0,0 +1,22 @@ +[id='con-Kubernetes-custom-actions_{context}'] += Kubernetes custom actions in {product} + +include::{docdir}/artifacts/snip-technology-preview.adoc[] + +With Kubernetes custom actions, you can create and manage Kubernetes resources. + +The Kubernetes custom actions plugin is preinstalled and disabled on a {product-short} instance by default. You can disable or enable the Kubernetes custom actions plugin, and change other parameters, by configuring the {product} Helm chart. + +[NOTE] +==== +Kubernetes scaffolder actions and Kubernetes custom actions refer to the same concept throughout this documentation. +==== + + +include::modules/using-kubernetes-custom-actions/proc-enable-kubernetes-custom-actions-plugin.adoc[leveloffset=+1] + +include::modules/using-kubernetes-custom-actions/proc-using-kubernetes-custom-actions-plugin.adoc[leveloffset=+1] + +include::modules/using-kubernetes-custom-actions/ref-creating-a-template-using-kubernetes-custom-actions.adoc[leveloffset=+1] + +include::modules/using-kubernetes-custom-actions/ref-supported-kubernetes-custom-actions.adoc[leveloffset=+2] \ No newline at end of file diff --git a/assemblies/assembly-using-techdocs.adoc b/assemblies/assembly-using-techdocs.adoc new file mode 100644 index 0000000000..61990c879a --- /dev/null +++ b/assemblies/assembly-using-techdocs.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +:context: assembly-using-techdocs +[id="{context}"] += Using TechDocs + +The TechDocs plugin is installed and enabled on your {product} instance by default. After an administrator configures the TechDocs plugin, an authorized developer can use the TechDocs plugin to add, view, or manage documentation. + +include::assembly-techdocs-add-docs.adoc[leveloffset=+1] + +include::modules/techdocs/proc-techdocs-find-docs.adoc[leveloffset=+1] + +include::modules/techdocs/proc-techdocs-view-docs.adoc[leveloffset=+1] + +include::modules/techdocs/proc-techdocs-edit-docs.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index 5fa7b95bb3..eb541ce985 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -20,13 +20,7 @@ include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-r include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-admin.adoc[leveloffset=+1] // Topology -== Installing and configuring the Topology plugin -include::../modules/dynamic-plugins/proc-topology-install.adoc[leveloffset=+2] -include::../modules/dynamic-plugins/proc-topology-configure.adoc[leveloffset=+2] - -include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] - -include::../assembly-using-servicenow.adoc[leveloffset=+1] +include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1] // Overriding Core Backend Service Configuration -include::../modules/dynamic-plugins/con-overriding-core-backend-services.adoc[leveloffset=+1] +include::../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc b/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc new file mode 100644 index 0000000000..666cf29070 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc @@ -0,0 +1,42 @@ +[id="rhdh-extensions-plugins_{context}"] += Extensions in {product} + +include::{docdir}/artifacts/snip-technology-preview.adoc[] + +:context: rhdh-extensions-plugins + +{product} ({product-very-short}) includes the Extensions feature which is preinstalled and enabled by default. Extensions provides users with a centralized interface to browse and manage available plugins + +You can use Extensions to discover plugins that extend {product-very-short} functionality, streamline development workflows, and improve the developer experience. + +// The feature is a first read-only version of the extensions plugin +// (previously called marketplace) +// It can show Plugins (a display name, icon, highlights, description) and +// Packages (npm package names and versions) in RHDH under +// Administration > Extensions +// The data are stored in the Software Catalog +// There are default Plugins for all Dynamic plugin. +// Customers can add their own. +// There is no option to install a Plugin in 1.5. + + +// Viewing Extensions +include::../modules/dynamic-plugins/proc-catalog-viewing.adoc[leveloffset=+1] + +// Viewing installed plugins +include::../modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] + +// Searching and filtering Extensions +include::../modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc[leveloffset=+1] + +// Viewing a plugin +include::../modules/dynamic-plugins/ref-catalog-plugin.adoc[leveloffset=+2] + +// Disabling Extensions +include::../modules/dynamic-plugins/proc-extensions-disabling.adoc[leveloffset=+1] + +// Managing the extensions plugin entries - For 1.6+ +//include::../modules/dynamic-plugins/proc-extensions-managing.adoc[leveloffset=+1] + +// Creating the extensions plugin metadata - For 1.6+ +//include::../modules/dynamic-plugins/proc-extensions-creating.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc index 06906e30d4..8abb61c354 100644 --- a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc +++ b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc @@ -15,7 +15,7 @@ Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yam [NOTE] ==== -You can also load dynamic plugins from another directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. +You can also load dynamic plugins from another directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. For more information, see xref:proc-enable-plugins-rhdh-container-image_{context}[]. ==== //OCI image diff --git a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc new file mode 100644 index 0000000000..8cd66db051 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc @@ -0,0 +1,14 @@ +[id="install-topology-plugin_{context}"] += Installing the Topology plugin + +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-bulk-importing-from-github.adoc[leveloffset=+1] + +include::../assembly-using-servicenow.adoc[leveloffset=+1] + +include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc b/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc index 2ef19277e8..27b4366094 100644 --- a/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc @@ -15,7 +15,7 @@ include::../modules/dynamic-plugins/ref-rh-supported-plugins.adoc[leveloffset=+3 [NOTE] ==== -* For more information about configuring KeyCloak, see link:{plugins-configure-book-url}[{plugins-configure-book-title}]. +* For more information about configuring KeyCloak, see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}]. * For more information about configuring TechDocs, see link:{customizing-book-url}#configuring-techdocs[Configuring TechDocs]. ==== @@ -27,14 +27,14 @@ include::../../artifacts/snip-dynamic-plugins-support.adoc[leveloffset=+3] [id="rhdh-tech-preview-plugins"] include::../modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc[leveloffset=+4] -[NOTE] -==== -* A new Technology Preview plugin for Red Hat Ansible Automation Platform (RHAAP) is available, which replaces this older one. See link:{LinkPluginsGuide}#rhdh-compatible-plugins[Other installable plugins] in the _{NameOfPluginsGuide} guide_ for further details. See xref:rhdh-compatible-plugins[Dynamic plugins support matrix]. -==== +//[NOTE] +//==== +//* A new Technology Preview plugin for Red Hat Ansible Automation Platform (RHAAP) is available, which replaces this older one. See link:{configuring-dynamic-plugins-book-url}#rhdh-compatible-plugins[Other installable plugins] in _{configuring-dynamic-plugins-book-title}_ for further details. See xref:rhdh-compatible-plugins[Dynamic plugins support matrix]. +//==== // Community plugins -// [id="rhdh-community-plugins"] -// include::../modules/dynamic-plugins/ref-community-plugins.adoc[leveloffset=+4] +[id="rhdh-community-plugins"] +include::../modules/dynamic-plugins/ref-community-plugins.adoc[leveloffset=+4] // Red Hat compatible plugins [id="rhdh-compatible-plugins"] diff --git a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc index 662abd1e79..4d9d74eb90 100644 --- a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc @@ -20,4 +20,4 @@ include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-r include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-user.adoc[leveloffset=+1] // Topology -include::../../modules/dynamic-plugins/proc-using-topology-plugin.adoc[leveloffset=+1] \ No newline at end of file +include::../../assemblies/dynamic-plugins/assembly-using-topology-plugin.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-using-topology-plugin.adoc b/assemblies/dynamic-plugins/assembly-using-topology-plugin.adoc new file mode 100644 index 0000000000..76c9198dd6 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-using-topology-plugin.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: ASSEMBLY +:context: using-topology-plugin +[id="{context}"] += Using the Topology plugin + +Topology is a front-end plugin that enables you to view the workloads as nodes that power any service on the Kubernetes cluster. + +include::../modules/dynamic-plugins/proc-enable-users-to-use-topology-plugin.adoc[leveloffset=+1] + +include::../modules/dynamic-plugins/proc-using-topology-plugin.adoc[leveloffset=+1] diff --git a/images/rhdh-plugins-reference/active-users.jpg b/images/rhdh-plugins-reference/active-users.jpg new file mode 100644 index 0000000000..a8fda04db6 Binary files /dev/null and b/images/rhdh-plugins-reference/active-users.jpg differ diff --git a/images/rhdh-plugins-reference/adoption-insights-catalog-entities.jpg b/images/rhdh-plugins-reference/adoption-insights-catalog-entities.jpg new file mode 100644 index 0000000000..c430e60bdb Binary files /dev/null and b/images/rhdh-plugins-reference/adoption-insights-catalog-entities.jpg differ diff --git a/images/rhdh-plugins-reference/adoption-insights-daterange.jpg b/images/rhdh-plugins-reference/adoption-insights-daterange.jpg new file mode 100644 index 0000000000..e0ab533335 Binary files /dev/null and b/images/rhdh-plugins-reference/adoption-insights-daterange.jpg differ diff --git a/images/rhdh-plugins-reference/adoption-insights.jpg b/images/rhdh-plugins-reference/adoption-insights.jpg new file mode 100644 index 0000000000..8dbc7e3398 Binary files /dev/null and b/images/rhdh-plugins-reference/adoption-insights.jpg differ diff --git a/images/rhdh-plugins-reference/dynatrace-certified-and-verified.png b/images/rhdh-plugins-reference/dynatrace-certified-and-verified.png new file mode 100644 index 0000000000..8aeb07d7c2 Binary files /dev/null and b/images/rhdh-plugins-reference/dynatrace-certified-and-verified.png differ diff --git a/images/rhdh-plugins-reference/extensions-catalog-sidebar.png b/images/rhdh-plugins-reference/extensions-catalog-sidebar.png new file mode 100644 index 0000000000..1c2880a0c8 Binary files /dev/null and b/images/rhdh-plugins-reference/extensions-catalog-sidebar.png differ diff --git a/images/rhdh-plugins-reference/extensions-catalog.png b/images/rhdh-plugins-reference/extensions-catalog.png new file mode 100644 index 0000000000..d45c68076a Binary files /dev/null and b/images/rhdh-plugins-reference/extensions-catalog.png differ diff --git a/images/rhdh-plugins-reference/group1.jpg b/images/rhdh-plugins-reference/group1.jpg deleted file mode 100644 index 4b9a277ac4..0000000000 Binary files a/images/rhdh-plugins-reference/group1.jpg and /dev/null differ diff --git a/images/rhdh-plugins-reference/user-list.jpg b/images/rhdh-plugins-reference/user-list.jpg deleted file mode 100644 index 344fd51353..0000000000 Binary files a/images/rhdh-plugins-reference/user-list.jpg and /dev/null differ diff --git a/images/rhdh-plugins-reference/user2.jpg b/images/rhdh-plugins-reference/user2.jpg deleted file mode 100644 index 95d29b7666..0000000000 Binary files a/images/rhdh-plugins-reference/user2.jpg and /dev/null differ diff --git a/images/rhdh-plugins-reference/users.jpg b/images/rhdh-plugins-reference/users.jpg deleted file mode 100644 index 393f14bdd5..0000000000 Binary files a/images/rhdh-plugins-reference/users.jpg and /dev/null differ diff --git a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc new file mode 100644 index 0000000000..c5a48f3954 --- /dev/null +++ b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc @@ -0,0 +1,28 @@ +[id="telemetry-data-collection-and-analysis_{context}"] += Telemetry data collection and analysis + +The telemetry data collection feature helps in collecting and analyzing the telemetry data to improve your experience with {product}. This feature is enabled by default. + +{company-name} collects and analyzes the following data: + +Web Analytics:: +Web Analytics use the Segment tool. +It is the tracking of user behavior and interactions with {product}. +Specifically, it tracks the following: + +* Events of page visits and clicks on links or buttons. +* System-related information, for example, locale, time zone, user agent including browser and operating system details. +* Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters. +* Anonymized IP addresses, recorded as `0.0.0.0`. +* Anonymized username hashes, which are unique identifiers used solely to identify the number of unique users of the {product-very-short} application. + +System Observability:: +System Observability uses the OpenTelemetry tool. +It is the tracking of the performance of the {product-very-short}. +Specifically, it tracks the following metrics: + +* Key system metrics such as CPU usage, memory usage, and other performance indicators. +* Information about system components, such as the locale, time zone, and user agent (including details of the browser and operating system). +* Traces and logs monitor system processes, allowing you to troubleshoot potential issues impacting the performance of {product-very-short}. + +With {product-very-short}, you can customize the _Web Analytics_ and _System Observability_ configuration based on your needs. \ No newline at end of file diff --git a/modules/observe/proc-customizing-telemetry-segment-using-helm.adoc b/modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc similarity index 89% rename from modules/observe/proc-customizing-telemetry-segment-using-helm.adoc rename to modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc index 3b61cbb981..08deb63aa0 100644 --- a/modules/observe/proc-customizing-telemetry-segment-using-helm.adoc +++ b/modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc @@ -1,7 +1,7 @@ -[id="proc-customizing-telemetry-segment-using-helm_{context}"] -= Customizing telemetry Segment source using the Helm Chart +[id="customizing-segment-source-using-helm-the-helm-chart_{context}"] += Customizing Segment source using the Helm Chart -You can configure integration with your Segment source by using the Helm Chart. +You can configure integration with your Segment source by using the {product} Helm Chart. .Prerequisites diff --git a/modules/observe/proc-customizing-telemetry-segment-using-operator.adoc b/modules/analytics/proc-customizing-segment-source-using-the-operator.adoc similarity index 90% rename from modules/observe/proc-customizing-telemetry-segment-using-operator.adoc rename to modules/analytics/proc-customizing-segment-source-using-the-operator.adoc index 0d08938f23..5a1f01c9b2 100644 --- a/modules/observe/proc-customizing-telemetry-segment-using-operator.adoc +++ b/modules/analytics/proc-customizing-segment-source-using-the-operator.adoc @@ -1,7 +1,7 @@ [id="proc-customizing-telemetry-segment-using-operator_{context}"] -= Customizing telemetry Segment source using the Operator += Customizing Segment source using the Operator -You can configure integration with your Segment source by using the Operator. +You can configure integration with your Segment source by using the {product} Operator. .Prerequisites diff --git a/modules/observe/proc-disabling-telemetry-using-helm.adoc b/modules/analytics/proc-disabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/proc-disabling-telemetry-using-helm.adoc rename to modules/analytics/proc-disabling-telemetry-using-helm.adoc diff --git a/modules/observe/proc-disabling-telemetry-using-operator.adoc b/modules/analytics/proc-disabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/proc-disabling-telemetry-using-operator.adoc rename to modules/analytics/proc-disabling-telemetry-using-operator.adoc diff --git a/modules/observe/proc-enabling-telemetry-using-helm.adoc b/modules/analytics/proc-enabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/proc-enabling-telemetry-using-helm.adoc rename to modules/analytics/proc-enabling-telemetry-using-helm.adoc diff --git a/modules/observe/proc-enabling-telemetry-using-operator.adoc b/modules/analytics/proc-enabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/proc-enabling-telemetry-using-operator.adoc rename to modules/analytics/proc-enabling-telemetry-using-operator.adoc diff --git a/modules/authentication/proc-enabling-authentication-with-github.adoc b/modules/authentication/proc-enabling-authentication-with-github.adoc index 44294e1de6..2c9a0b1ca5 100644 --- a/modules/authentication/proc-enabling-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-authentication-with-github.adoc @@ -51,11 +51,11 @@ TIP: If you plan to make changes using the GitHub API, ensure that `Read and wri * **Private key** * **Webhook secret** -. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{plugins-configure-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: +. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: + `AUTH_GITHUB_APP_ID`:: Enter the saved **App ID**. `AUTH_GITHUB_CLIENT_ID`:: Enter the saved **Client ID**. -`GITHUB_HOST_DOMAIN`:: Enter your GitHub host domain: `github.com` unless you are using GitHub Enterprise. +//`GITHUB_HOST_DOMAIN`:: Enter your GitHub host domain: `github.com` unless you are using GitHub Enterprise. `GITHUB_ORGANIZATION`:: Enter your GitHub organization name, such as `____'. `GITHUB_ORG_URL`:: Enter `$GITHUB_HOST_DOMAIN/$GITHUB_ORGANIZATION`. `GITHUB_CLIENT_SECRET`:: Enter the saved **Client Secret**. @@ -63,18 +63,17 @@ TIP: If you plan to make changes using the GitHub API, ensure that `Read and wri `GITHUB_WEBHOOK_URL`:: Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. `GITHUB_WEBHOOK_SECRET`:: Enter the saved *Webhook secret*. -. To set up the GitHub authentication provider and enable integration with the GitHub API in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content: +. . To set up the GitHub authentication provider and enable integration with the GitHub API in your {product-short} custom configuration, edit your custom {product-short} config map such as `{my-app-config-config-map}`, and add the following lines to the `{my-app-config-file}` file content: + --- -.`app-config-rhdh.yaml` fragment with mandatory fields to enable authentication with GitHub +.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub [source,yaml] ---- auth: - environment: production + environment: production # <1> providers: github: production: - clientId: ${AUTH_GITHUB_CLIENT_ID} + clientId: ${AUTH_GITHUB_CLIENT_ID} # <2> clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} integrations: github: @@ -87,26 +86,81 @@ integrations: webhookSecret: ${GITHUB_WEBHOOK_SECRET} privateKey: | ${GITHUB_PRIVATE_KEY_FILE} -signInPage: github +signInPage: github # <3> +---- +<1> Mark the environment as `production` and disable the Guest login option in the {product-short} login page. +<2> Apply the GitHub credentials configured in your {product-short} secrets. +<3> To enable the GitHub provider as your {product-short} sign-in provider. + +.. Optional: Consider adding the following optional fields: + +`callbackUrl`:: +The callback URL that GitHub uses when initiating an OAuth flow, such as: ____. +Define it when {product-short} is not the immediate receiver, such as in cases when you use one OAuth app for many {product-short} instances. ++ +.`{my-app-config-file}` file fragment with optional `enterpriseInstanceUrl` field +[source,yaml,subs="+quotes"] +---- +auth: + providers: + github: + production: + callbackUrl: ____ +---- + +//// +`enterpriseInstanceUrl`:: +Your GitHub Enterprise URL. +Requires you defined the `GITHUB_HOST_DOMAIN` secret in the previous step. ++ +.`{my-app-config-file}` file fragment with optional `enterpriseInstanceUrl` field +[source,yaml,subs="+quotes"] +---- +auth: + providers: + github: + production: + enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN} +---- +//// + +`sessionDuration`:: +Lifespan of the user session. +Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. ++ +.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field +[source,yaml,subs="+quotes"] +---- +auth: + providers: + github: + production: + sessionDuration: { hours: 24 } ---- -`environment: production`:: -Mark the environment as `production` to hide the Guest login in the {product-short} home page. +`signIn` :: -`clientId`, `clientSecret`, `host`, `appId`, `webhookUrl`, `webhookSecret`, `privateKey`:: -Use the {product-short} application information that you have created in GitHub and configured in OpenShift as secrets. +`resolvers`::: +After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog. To best match users securely for your use case, consider configuring a specific resolver. Enter the resolver list to override the default resolver: `usernameMatchingUserEntityName`. ++ +The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. ++ +WARNING: In production mode, only configure one resolver to ensure users are securely matched. -`sigInPage: github`:: -To enable the GitHub provider as default sign-in provider. +`resolver`:::: +Enter the sign-in resolver name. +Available resolvers: -Optional: Consider adding the following optional fields: +* `usernameMatchingUserEntityName` +* `preferredUsernameMatchingUserEntityName` +* `emailMatchingUserEntityProfileEmail` -`dangerouslyAllowSignInWithoutUserInCatalog: true`:: -To enable authentication without requiring to provision users in the {product-short} software catalog. +`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: +Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. + -.`app-config-rhdh.yaml` fragment with optional field to allow authenticating users absent from the software catalog +.`{my-app-config-file}` file fragment with optional field to allow signing in users absent from the software catalog [source,yaml] ---- auth: @@ -116,6 +170,10 @@ auth: production: clientId: ${AUTH_GITHUB_CLIENT_ID} clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} + signIn: + resolvers: + - resolver: usernameMatchingUserEntityName + dangerouslyAllowSignInWithoutUserInCatalog: true integrations: github: - host: ${GITHUB_HOST_DOMAIN} @@ -128,35 +186,6 @@ integrations: privateKey: | ${GITHUB_PRIVATE_KEY_FILE} signInPage: github -dangerouslyAllowSignInWithoutUserInCatalog: true ----- - -`callbackUrl`:: -The callback URL that GitHub uses when initiating an OAuth flow, such as: ____. -Define it when {product-short} is not the immediate receiver, such as in cases when you use one OAuth app for many {product-short} instances. -+ -.`app-config-rhdh.yaml` fragment with optional `enterpriseInstanceUrl` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - github: - production: - callbackUrl: ____ ----- - -`enterpriseInstanceUrl`:: -Your GitHub Enterprise URL. -Requires you defined the `GITHUB_HOST_DOMAIN` secret in the previous step. -+ -.`app-config-rhdh.yaml` fragment with optional `enterpriseInstanceUrl` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - github: - production: - enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN} ---- [TIP] @@ -166,7 +195,7 @@ To enable GitHub integration with a different authentication provider, complete * Add the GitHub provider to the existing `auth` section. * Keep the `signInPage` section from your authentication provider configuration. -.`app-config-rhdh.yaml` fragment with mandatory fields to enable GitHub integration and use a different authentication provider +.`{my-app-config-file}` file fragment with mandatory fields to enable GitHub integration and use a different authentication provider [source,yaml,subs="+quotes"] ---- auth: @@ -192,8 +221,6 @@ signInPage: ____ ---- ==== --- - .Verification . Go to the {product-short} login page. . Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled. diff --git a/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc index ab43795f59..f3d2cde132 100644 --- a/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc @@ -27,8 +27,7 @@ * `openid` * `profile` * `User.Read` -* Optional custom scopes for the Microsoft Graph API that you define both in this section and in the {product-short} configuration (`app-config-rhdh.yaml`). -+ +* Optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. [NOTE] ==== Your company might require you to grant admin consent for these permissions. @@ -44,60 +43,33 @@ To grant administrator consent, a directory administrator must go to the link:ht - **Application (client) ID** - **Application (client) secret** -. To add your Microsoft Azure credentials to {product-short}, add the following key/value pairs to link:{plugins-configure-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: +. To add your Microsoft Azure credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: + `AUTH_AZURE_TENANT_ID`:: Enter your saved *Directory (tenant) ID*. `AUTH_AZURE_CLIENT_ID`:: Enter your saved *Application (client) ID*. `AUTH_AZURE_CLIENT_SECRET`:: Enter your saved *Application (client) secret*. -. Set up the Microsoft Azure authentication provider in your {product-short} custom configuration, such as `app-config-rhdh`: +. Set up the Microsoft Azure authentication provider in your `{my-app-config-file}` file: + -- -.`app-config-rhdh.yaml` fragment +.`{my-app-config-file}` file fragment [source,yaml,subs="+quotes,+attributes"] ---- auth: - environment: production + environment: production # <1> providers: microsoft: production: - clientId: ${AUTH_AZURE_CLIENT_ID} + clientId: ${AUTH_AZURE_CLIENT_ID} # <2> clientSecret: ${AUTH_AZURE_CLIENT_SECRET} tenantId: ${AUTH_AZURE_TENANT_ID} -signInPage: microsoft +signInPage: microsoft # <3> ---- +<1> Mark the environment as production and disable the **Guest** login option in the {product-short} login page. +<2> Apply the Microsoft Azure credentials configured in your {product-short} secrets. +<3> Set the Microsoft Azure provider as your {product-short} sign-in provider. -`environment: production`:: -Mark the environment as production to hide the **Guest** login in the {product-short} home page. - -`clientId`, `clientSecret` and `tenantId`:: -Use the {product-short} application information that you have created in Microsoft Azure and configured in OpenShift as secrets. - -`signInPage: microsoft`:: -Enable the Microsoft Azure provider as default sign-in provider. - -Optional: Consider adding following optional fields: - -`dangerouslyAllowSignInWithoutUserInCatalog: true`:: -+ -To enable authentication without requiring to provision users in the {product-short} software catalog. -+ -WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. -+ -.`app-config-rhdh.yaml` fragment with optional field to allow authenticating users absent from the software catalog -[source,yaml] ----- -auth: - environment: production - providers: - microsoft: - production: - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - tenantId: ${AUTH_AZURE_TENANT_ID} -signInPage: microsoft -dangerouslyAllowSignInWithoutUserInCatalog: true ----- +.. Optional: Consider adding following optional fields: `domainHint`:: Optional for single-tenant applications. @@ -106,7 +78,7 @@ If you want to use this parameter for a single-tenant application, uncomment and If your application registration is multi-tenant, leave this parameter blank. For more information, see link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy[Home Realm Discovery]. + -.`app-config-rhdh.yaml` fragment with optional `domainHint` field +.`{my-app-config-file}` file fragment with optional `domainHint` field [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -122,7 +94,7 @@ Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. The default and mandatory value lists: `'openid', 'offline_access', 'profile', 'email', 'User.Read'`. + -.`app-config-rhdh.yaml` fragment with optional `additionalScopes` field +.`{my-app-config-file}` file fragment with optional `additionalScopes` field [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -133,7 +105,60 @@ auth: additionalScopes: - Mail.Send ---- --- + +`sessionDuration`:: +Lifespan of the user session. +Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. ++ +.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field +[source,yaml,subs="+quotes"] +---- +auth: + providers: + microsoft: + production: + sessionDuration: { hours: 24 } +---- + +`signIn` :: + +`resolvers`::: +After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog. To best match users securely for your use case, consider configuring a specific resolver. Enter the resolver list to override the default resolver: `emailLocalPartMatchingUserEntityName`. ++ +The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. ++ +WARNING: In production mode, only configure one resolver to ensure users are securely matched. + +`resolver`:::: +Enter the sign-in resolver name. +Available resolvers: + +* `userIdMatchingUserEntityAnnotation` +* `emailLocalPartMatchingUserEntityName` +* `emailMatchingUserEntityProfileEmail` + +`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: +Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. ++ +WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. ++ +.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog +[source,yaml] +---- +auth: + environment: production + providers: + microsoft: + production: + clientId: ${AUTH_AZURE_CLIENT_ID} + clientSecret: ${AUTH_AZURE_CLIENT_SECRET} + tenantId: ${AUTH_AZURE_TENANT_ID} + signIn: + resolvers: + - resolver: usernameMatchingUserEntityName + dangerouslyAllowSignInWithoutUserInCatalog: true +signInPage: microsoft +---- [NOTE] ==== diff --git a/modules/authentication/proc-enabling-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc index edcbcb1598..58dc7ff7ed 100644 --- a/modules/authentication/proc-enabling-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc @@ -9,13 +9,13 @@ To authenticate users with {rhbk-brand-name} ({rhbk}), enable the OpenID Connect * You have sufficient permissions in {rhsso} to create and manage a realm. .Procedure -. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-secure-the-first-application[secure the first application]: +. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-secure-the-first-application[secure the first application]: -.. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm], with a distinctive **Name** such as ____. +.. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm], with a distinctive **Name** such as ____. Save the value for the next step: * **{rhbk} realm base URL**, such as: ____/realms/____. -.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/getting_started_guide/index#getting-started-zip-secure-the-first-application[secure the first application], with: +.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html-single/getting_started_guide/index#getting-started-zip-secure-the-first-application[secure the first application], with: ... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__. ... **Valid redirect URIs**: Set to the OIDC handler URL: `https://____/api/auth/oidc/handler/frame`. ... Navigate to the **Credentials** tab and copy the **Client secret**. @@ -23,17 +23,18 @@ Save the value for the next step: * **Client ID** * **Client Secret** -.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. Save the user credential information for the verification steps. +.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. Save the user credential information for the verification steps. -. To add your {rhsso} credentials to your {product-short}, add the following key/value pairs to link:{plugins-configure-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: +. To add your {rhsso} credentials to your {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: + `AUTH_OIDC_CLIENT_ID`:: Enter the saved **Client ID**. `AUTH_OIDC_CLIENT_SECRET`:: Enter the saved **Client Secret**. `AUTH_OIDC_METADATA_URL`:: Enter the saved **{rhbk} realm base URL**. . To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `{my-app-config-file}` content: + +.. Configure mandatory fields: + --- .`{my-app-config-file}` fragment with mandatory fields to enable authentication with {rhbk} [source,yaml] ---- @@ -45,6 +46,7 @@ auth: metadataUrl: ${AUTH_OIDC_METADATA_URL} clientId: ${AUTH_OIDC_CLIENT_ID} clientSecret: ${AUTH_OIDC_CLIENT_SECRET} + prompt: auto signInPage: oidc ---- @@ -57,6 +59,13 @@ To configure the OIDC provider with your secrets. `sigInPage: oidc`:: To enable the OIDC provider as default sign-in provider. +`prompt: auto`:: +To allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active {rhsso} session exists. + +[NOTE] +==== +If `prompt: auto` is not set, the identity provider defaults to `prompt: none`, which assumes that you are already logged in and rejects sign-in requests without an active session. +==== Optional: Consider adding the following optional fields: @@ -64,9 +73,9 @@ Optional: Consider adding the following optional fields: + -- To enable authentication without requiring to provision users in the {product-short} software catalog. -+ + WARNING: Use this option to explore {product-short} features, but do not use it in production. -+ + .`{my-app-config-file}` fragment with optional field to allow authenticating users absent from the software catalog [source,yaml] ---- @@ -78,15 +87,15 @@ auth: metadataUrl: ${AUTH_OIDC_METADATA_URL} clientId: ${AUTH_OIDC_CLIENT_ID} clientSecret: ${AUTH_OIDC_CLIENT_SECRET} + prompt: auto signInPage: oidc dangerouslyAllowSignInWithoutUserInCatalog: true ---- -- `callbackUrl`:: --- {rhbk} callback URL. - ++ .`{my-app-config-file}` fragment with optional `callbackURL` field [source,yaml] ---- @@ -96,12 +105,10 @@ auth: production: callbackUrl: ${AUTH_OIDC_CALLBACK_URL} ---- --- `tokenEndpointAuthMethod`:: --- Token endpoint authentication method. - ++ .`{my-app-config-file}` fragment with optional `tokenEndpointAuthMethod` field [source,yaml] ---- @@ -111,12 +118,10 @@ auth: production: tokenEndpointAuthMethod: ${AUTH_OIDC_TOKEN_ENDPOINT_METHOD} ---- --- `tokenSignedResponseAlg`:: --- Token signed response algorithm. - ++ .`{my-app-config-file}` fragment with optional `tokenSignedResponseAlg` field [source,yaml] ---- @@ -126,12 +131,10 @@ auth: production: tokenSignedResponseAlg: ${AUTH_OIDC_SIGNED_RESPONSE_ALG} ---- --- `scope`:: --- {rhbk} scope. - ++ .`{my-app-config-file}` fragment with optional `scope` field [source,yaml] ---- @@ -141,14 +144,25 @@ auth: production: scope: ${AUTH_OIDC_SCOPE} ---- --- - -`signIn.resolvers`:: --- -Declarative resolvers to override the default resolver: `emailLocalPartMatchingUserEntityName`. -The authentication provider tries each sign-in resolver until it succeeds, and fails if none succeed. -.`{my-app-config-file}` fragment with optional `callbackURL` field +`signIn`:: +`resolvers`::: +After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog. +To best match users securely for your use case, consider configuring a specific resolver. +Enter the resolver list to override the default resolver: `oidcSubClaimMatchingKeycloakUserId`. ++ +The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. ++ +WARNING: In production mode, only configure one resolver to ensure users are securely matched. +`resolver`:::: +Enter the sign-in resolver name. +Available values: +* `oidcSubClaimMatchingKeycloakUserId` +* `emailLocalPartMatchingUserEntityName` +* `emailMatchingUserEntityProfileEmail` +* `preferredUsernameMatchingUserEntityName` ++ +.`{my-app-config-file}` fragment with optional `resolvers` list [source,yaml] ---- auth: @@ -157,35 +171,72 @@ auth: production: signIn: resolvers: + - resolver: oidcSubClaimMatchingKeycloakUserId - resolver: preferredUsernameMatchingUserEntityName - resolver: emailMatchingUserEntityProfileEmail - resolver: emailLocalPartMatchingUserEntityName ---- --- -`auth.backstageTokenExpiration`:: --- -To modify the {product-short} token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours. +`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: +Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. ++ +WARNING: Use this option to explore {product-short} features, but do not use it in production. ++ +.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog +[source,yaml] +---- +auth: + environment: production + providers: + oidc: + production: + metadataUrl: ${AUTH_OIDC_METADATA_URL} + clientId: ${AUTH_OIDC_CLIENT_ID} + clientSecret: ${AUTH_OIDC_CLIENT_SECRET} + signIn: + resolvers: + - resolver: oidcSubClaimMatchingKeycloakUserID + dangerouslyAllowSignInWithoutUserInCatalog: true +signInPage: oidc +---- -.`{my-app-config-file}` fragment with optional `auth.backstageTokenExpiration` field +`sessionDuration`:: +Lifespan of the user session. +Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. ++ +.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field [source,yaml,subs="+quotes"] ---- auth: - backstageTokenExpiration: { minutes: __ } + providers: + github: + production: + sessionDuration: { hours: 24 } ---- --- --- +`auth`:: +`backstageTokenExpiration`::: +To modify the {product-short} token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours. ++ +.`{my-app-config-file}` fragment with optional `auth.backstageTokenExpiration` field +[source,yaml,subs="+quotes"] +---- +auth: + backstageTokenExpiration: { minutes: __ } +---- ++ +[WARNING] .Security consideration +==== If multiple valid refresh tokens are issued due to frequent refresh token requests, older tokens will remain valid until they expire. To enhance security and prevent potential misuse of older tokens, enable a refresh token rotation strategy in your {rhbk} realm. . From the *Configure* section of the navigation menu, click *Realm Settings*. . From the *Realm Settings* page, click the *Tokens* tab. . From the *Refresh tokens* section of the *Tokens* tab, toggle the *Revoke Refresh Token* to the *Enabled* position. +==== .Verification . Go to the {product-short} login page. . Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled. . Log in with OIDC by using the saved **Username** and **Password** values. - diff --git a/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc index 3b2c456d49..ab0e9df5a4 100644 --- a/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc +++ b/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc @@ -18,7 +18,6 @@ Consider configuring {product-short} to provision users from GitHub to the softw .`{my-app-config-file}` fragment with mandatory `github` fields [source,yaml] ---- -dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: github: @@ -43,9 +42,6 @@ catalog: minutes: 15 ---- -`dangerouslyAllowSignInWithoutUserInCatalog: false`:: -Allow authentication only for users present in the {product-short} software catalog. - `organization`, `githubUrl`, and `orgs`:: Use the {product-short} application information that you have created in GitHub and configured in OpenShift as secrets. diff --git a/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc index 8c6bc31d87..662eb29447 100644 --- a/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc +++ b/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc @@ -14,7 +14,6 @@ To authenticate users with Microsoft Azure, after xref:enabling-authentication-w .`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields [source,yaml] ---- -dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: microsoftGraphOrg: @@ -25,9 +24,6 @@ catalog: clientSecret: ${AUTH_AZURE_CLIENT_SECRET} ---- -`dangerouslyAllowSignInWithoutUserInCatalog: false`:: -Allow authentication only for users in the {product-short} software catalog. - `target: https://graph.microsoft.com/v1.0`:: Defines the MSGraph API endpoint the provider is connecting to. You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint]. diff --git a/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc index d5edff880b..8b4839d8a1 100644 --- a/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc +++ b/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc @@ -13,7 +13,6 @@ .`{my-app-config-file}` fragment with mandatory `keycloakOrg` fields [source,yaml] ---- -dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: keycloakOrg: @@ -23,9 +22,6 @@ catalog: clientSecret: ${AUTH_OIDC_CLIENT_SECRET} ---- -`dangerouslyAllowSignInWithoutUserInCatalog: false`:: - Allow authentication only for users present in the {product-short} software catalog. - `baseUrl`:: Your {rhbk} server URL, defined when xref:enabling-authentication-with-rhbk[enabling authentication with {rhbk}]. diff --git a/modules/authorization/proc-configuring-the-RBAC-backend-plugin.adoc b/modules/authorization/proc-configuring-the-RBAC-backend-plugin.adoc new file mode 100644 index 0000000000..ca4a96a355 --- /dev/null +++ b/modules/authorization/proc-configuring-the-RBAC-backend-plugin.adoc @@ -0,0 +1,29 @@ +[id="configuring-the-rbac-backend-plugin_{context}"] += Configuring the RBAC backend plugin + +You can configure the RBAC backend plugin by updating the `{my-app-config-file}` file to enable the permission framework. + +.Prerequisites +* You have installed the `@janus-idp/backstage-plugin-rbac` plugin in {product-short}. For more information, see link:{plugins-configure-book-url}[{plugins-configure-book-title}]. + +.Procedure +* Update the `{my-app-config-file}` file to enable the permission framework as shown: + +[source,yaml,subs=+quotes] +---- +permission + enabled: true + rbac: + admin: + users: + - name: user:default/guest + pluginsWithPermission: + - catalog + - permission + - scaffolder +---- + +[NOTE] +==== +The `pluginsWithPermission` section of the `{my-app-config-file}` file includes only three plugins by default. Update the section as needed to include any additional plugins that also incorporate permissions. +==== diff --git a/modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.adoc b/modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.adoc index 646668b451..9631d1e368 100644 --- a/modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.adoc +++ b/modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.adoc @@ -93,7 +93,7 @@ name::: `rbac-policies` . Update your {product-short} `{my-app-config-file}` configuration file to use the `rbac-policies.csv` and `rbac-conditional-policies.yaml` external files: + -.`app-config.yml` fragment +.`{my-app-config-file}` file fragment [source,yaml] ---- permission: diff --git a/modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.adoc b/modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.adoc index da928f2b92..dd97e154a5 100644 --- a/modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.adoc +++ b/modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.adoc @@ -90,9 +90,9 @@ spec: - name: rbac-policies ---- -. Update your {product-short} `app-config.yaml` configuration file to use the `rbac-policies.csv` and `rbac-conditional-policies.yaml` external files: +. Update your {product-short} `{my-app-config-file}` configuration file to use the `rbac-policies.csv` and `rbac-conditional-policies.yaml` external files: + -.`app-config.yml` fragment +.`{my-app-config-file}` file fragment [source,yaml] ---- permission: diff --git a/modules/authorization/proc-delegating-rbac-access.adoc b/modules/authorization/proc-delegating-rbac-access.adoc new file mode 100644 index 0000000000..3ef727a176 --- /dev/null +++ b/modules/authorization/proc-delegating-rbac-access.adoc @@ -0,0 +1,179 @@ +[id='proc-delegating-rbac-access_{context}'] += Delegating role-based access controls (RBAC) access in {product} + +An enterprise customer requires the ability to delegate role-based access control (RBAC) responsibilities to other individuals in the organization. In this scenario, you, as the administrator, can provide access to the RBAC plugin specifically to designated users, such as team leads. Each team lead is then able to manage permissions exclusively for users within their respective team or department, without visibility into or control over permissions outside their assigned scope. This approach allows team leads to manage access and permissions for their own teams independently, while administrators maintain global oversight. + +In {product-very-short}, you can delegate RBAC access using the multitenancy feature of RBAC plugin, specifically the `IS_OWNER` conditional rule. + +By delegating the RBAC access, you can expect the following outcomes: + +* Team leads can manage RBAC settings for their teams independently. +* Visibility of other users' or teams' permissions is restricted. +* Administrators retain overarching control while delegating team-specific access. + +.Prerequisites +* Your {product-very-short} instance is up and running with RBAC plugin installed and configured. +* You have administrative access to {product-very-short}. +* You have API access using `curl` or another tool. + +.Procedure +. In your {product-very-short} instance, navigate to the *Administration -> RBAC* page. +. Create a new role designated for team leads using the Web UI or API: ++ +-- +.Example of creating a new role for the team lead using the RBAC backend API +[source,bash] +---- +curl -X POST 'http://localhost:7007/api/permission/roles' \ +--header "Authorization: Bearer $ADMIN_TOKEN" \ +--header "Content-Type: application/json" \ +--data '{ + "memberReferences": ["user:default/team_lead"], + "name": "role:default/team_lead", + "metadata": { + "description": "This is an example team lead role" + } +}' +---- + +For more information about creating a role using the Web UI, see xref:proc-rbac-ui-create-role_title-authorization[Creating a role in the {product} Web UI]. +-- + +. Allow team leads to read catalog entities and create permissions in the RBAC plugin using the Web UI or the following API request: ++ +-- +.Example of granting the team lead role permission to create RBAC policies and read catalog entities +[source,bash] +---- +curl -X POST 'http://localhost:7007/api/permission/policies' \ +--header "Authorization: Bearer $ADMIN_TOKEN" \ +--header "Content-Type: application/json" \ +--data '[ + { + "entityReference": "role:default/team_lead", + "permission": "policy.entity.create", + "policy": "create", + "effect": "allow" + }, + { + "entityReference": "role:default/team_lead", + "permission": "catalog-entity", + "policy": "read", + "effect": "allow" + } +]' +---- +-- + +. To ensure team leads can only manage what they own, use the `IS_OWNER` conditional rule as follows: ++ +-- +.Example `curl` of applying a conditional access policy using the `IS_OWNER` rule for the team lead role +[source,bash] +---- +curl -X POST 'http://localhost:7007/api/permission/roles/conditions' \ +--header "Authorization: Bearer $ADMIN_TOKEN" \ +--header "Content-Type: application/json" \ +--data '{ + "result": "CONDITIONAL", + "pluginId": "permission", + "resourceType": "policy-entity", + "conditions": { + "rule": "IS_OWNER", + "resourceType": "policy-entity", + "params": { + "owners": [ + "user:default/team_lead" + ] + } + }, + "roleEntityRef": "role:default/team_lead", + "permissionMapping": [ + "read", + "update", + "delete" + ] +}' +---- +The previous example of conditional policy limits visibility and control to only owned roles and policies. +-- + +. Log in to {product-very-short} as team lead and verify the following: ++ +-- +.. Use the following request and verify that you do not see any roles: ++ +.Example `curl` to retrieve roles visible to the team lead +[source,bash] +---- +curl -X GET 'http://localhost:7007/api/permission/roles' \ +--header "Authorization: Bearer $TEAM_LEAD_TOKEN" + +---- + +.. Use the following request to create a new role for their team: ++ +.Example `curl` of team lead creating a new role for their team with ownership assigned +[source,bash] +---- +curl -X POST 'http://localhost:7007/api/permission/roles' \ +--header "Authorization: Bearer $TEAM_LEAD_TOKEN" \ +--header "Content-Type: application/json" \ +--data '{ + "memberReferences": ["user:default/team_member"], + "name": "role:default/team_a", + "metadata": { + "description": "This is an example team_a role", + "owner": "user:default/team_lead" + } +}' +---- ++ +[NOTE] +==== +You can set the ownership during creation, but you can also update the ownership at any time. +==== + +.. Use the following request to assign a permission policy to the new role: ++ +.Example `curl` for granting read access to catalog entities for the new role +[source,bash] +---- +curl -X POST 'http://localhost:7007/api/permission/policies' \ +--header "Authorization: Bearer $ADMIN_TOKEN" \ +--header "Content-Type: application/json" \ +--data '[ + { + "entityReference": "role:default/team_a", + "permission": "catalog-entity", + "policy": "read", + "effect": "allow" + } +]' +---- + +.. Use the following request to verify that only team-owned roles and policies are visible: ++ +.Example `curl` to retrieve roles and permission policies visible to the team lead +[source,bash] +---- +curl -X GET 'http://localhost:7007/api/permission/roles' \ +--header "Authorization: Bearer $TEAM_LEAD_TOKEN" + +curl -X GET 'http://localhost:7007/api/permission/policies' \ +--header "Authorization: Bearer $TEAM_LEAD_TOKEN" +---- +-- + +.Verification +* Log in as a team lead and verify the following: ++ +-- +** The RBAC UI is accessible. +** Only the assigned users or group is visible. +** Permissions outside the scoped team are not viewable or editable. +-- +* Log in as an administrator and verify that you retain full visibility and control. + + + diff --git a/modules/authorization/proc-enabling-the-rbac-plugin.adoc b/modules/authorization/proc-enabling-the-rbac-plugin.adoc index 6cda18d35e..864bf0fa45 100644 --- a/modules/authorization/proc-enabling-the-rbac-plugin.adoc +++ b/modules/authorization/proc-enabling-the-rbac-plugin.adoc @@ -22,10 +22,10 @@ plugins: disabled: false ---- + -See link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}]. +See link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}]. . Declare policy administrators to enable a select number of authenticated users to configure RBAC policies through the REST API or Web UI, instead of modifying the CSV file directly. -The permissions can be specified in a separate CSV file referenced in the `app-config-rhdh` ConfigMap, or permissions can be created using the REST API or Web UI. +The permissions can be specified in a separate CSV file referenced in your `{my-app-config-config-map}` config map, or permissions can be created using the REST API or Web UI. + To declare users such as __ as policy administrators, edit your custom {product-short} ConfigMap, such as `app-config-rhdh`, and add following code to the `{my-app-config-file}` content: + diff --git a/modules/authorization/proc-setting-up-the-guest-authentication-provider.adoc b/modules/authorization/proc-setting-up-the-guest-authentication-provider.adoc new file mode 100644 index 0000000000..12b41ae4ce --- /dev/null +++ b/modules/authorization/proc-setting-up-the-guest-authentication-provider.adoc @@ -0,0 +1,26 @@ +[id="setting-up-the-guest-authentication-provider_{context}"] += Setting up the guest authentication provider + +You can enable guest authentication and use it alongside the RBAC frontend plugin. + +.Prerequisites +* You have installed the `@janus-idp/backstage-plugin-rbac` plugin in {product-short}. For more information, see link:{plugins-configure-book-url}[{plugins-configure-book-title}]. + +.Procedure + +* In the `{my-app-config-file}` file, add the user entity reference to resolve and enable the `dangerouslyAllowOutsideDevelopment` option, as shown in the following example: + +[source,yaml,subs="+attributes,+quotes"] +---- +auth: + environment: development + providers: + guest: + userEntityRef: user:default/guest + dangerouslyAllowOutsideDevelopment: true +---- + +[NOTE] +==== +You can use `user:default/guest` as the user entity reference to match the added user under the `permission.rbac.admin.users` section of the `{my-app-config-file}` file. +==== diff --git a/modules/authorization/ref-rbac-permission-policies.adoc b/modules/authorization/ref-rbac-permission-policies.adoc index 12e92867f6..dfebf48068 100644 --- a/modules/authorization/ref-rbac-permission-policies.adoc +++ b/modules/authorization/ref-rbac-permission-policies.adoc @@ -135,6 +135,11 @@ Scaffolder permissions:: | |`read` |Allows a user or role to read all scaffolder tasks and their associated events and logs + +|`scaffolder.template.management` +| +|`use` +|Allows a user or role to access frontend template management features, including editing, previewing, and trying templates, forms, and custom fields. |=== RBAC permissions:: @@ -153,7 +158,7 @@ RBAC permissions:: |Allows a user or role to read permission policies and roles |`policy.entity.create` -|`policy-entity` +| |`create` |Allows a user or role to create a single or multiple permission policies and roles @@ -178,6 +183,16 @@ Kubernetes permissions:: |Policy |Description +|`kubernetes.clusters.read` +| +|`read` +|Allows a user to read Kubernetes cluster details under the `/clusters` path + +|`kubernetes.resources.read` +| +|`read` +|Allows a user to read information about Kubernetes resources located at `/services/:serviceId` and `/resources` + |`kubernetes.proxy` | |`use` @@ -236,13 +251,45 @@ Topology permissions:: |Policy |Description -|`topology.view.read` +|`kubernetes.clusters.read` +| +|`read` +|Allows a user to read Kubernetes cluster details under the `/clusters` path + +|`kubernetes.resources.read` | |`read` -|Allows a user or role to view the topology plugin +|Allows a user to read information about Kubernetes resources located at `/services/:serviceId` and `/resources` |`kubernetes.proxy` | |`use` |Allows a user or role to access the proxy endpoint, allowing the user or role to read pod logs and events within {product-very-short} |=== + + +Tekton permissions:: + +.Tekton permissions +[cols="15%,25%,15%,45%", frame="all", options="header"] +|=== +|Name +|Resource type +|Policy +|Description + +|`kubernetes.clusters.read` +| +|`read` +|Allows a user to read Kubernetes cluster details under the `/clusters` path + +|`kubernetes.resources.read` +| +|`read` +|Allows a user to read information about Kubernetes resources located at `/services/:serviceId` and `/resources` + +|`kubernetes.proxy` +| +|`use` +|Allows a user or role to access the proxy endpoint, allowing the user or role to read pod logs and events within {product-very-short} +|=== \ No newline at end of file diff --git a/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc b/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc new file mode 100644 index 0000000000..7396212e1f --- /dev/null +++ b/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc @@ -0,0 +1,295 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-configuring-floating-action-button-as-a-dynamic-plugin_{context}"] += Configuring a floating action button as a dynamic plugin + +You can configure the floating action button as a dynamic plugin to perform actions or open an internal or external link. + +.Prerequisties +You must have sufficient permissions as a platform engineer. + +.Procedure + +To configure a floating action button as a dynamic plugin, complete any of the following tasks: + +* Specify the `global.floatingactionbutton/config` mount point in your `app-config-dynamic.yaml` file. For example: ++ +.Example of a bulk-import plugin as a floating action button +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-bulk-import: + # Start of the floating action button configuration + mountPoints: + - mountPoint: global.floatingactionbutton/config + importName: BulkImportPage # <1> + config: + slot: 'page-end' + icon: # <2> + label: 'Bulk import' + toolTip: 'Register multiple repositories in bulk' + to: /bulk-import/repositories + # End of the floating action button configuration + appIcons: + - name: bulkImportIcon + importName: BulkImportIcon + dynamicRoutes: + - path: /bulk-import/repositories + importName: BulkImportPage + menuItem: + icon: bulkImportIcon + text: Bulk import +---- +<1> (Required) The import name with an associated component to the mount point. +<2> Use the `svg` value to display a black BulkImportPage icon. + +* To configure an action as a floating action button that opens an external link, specify the `global.floatingactionbutton/config` mount point in your `dynamic-plugins.yaml` file within the `backstage-plugin-global-floating-action-button` plugin. For example: ++ +.Example of a floating action button that opens GitHub +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-global-floating-action-button: + mountPoints: + - mountPoint: application/listener + importName: DynamicGlobalFloatingActionButton + - mountPoint: global.floatingactionbutton/config + importName: NullComponent # <1> + config: + icon: '' # <2> + label: 'Quay' + showLabel: true + toolTip: 'Quay' + to: 'https://quay.io' + - mountPoint: global.floatingactionbutton/config + importName: NullComponent + config: + icon: github + label: 'Git' + toolTip: 'Github' + to: https://github.com/redhat-developer/rhdh-plugins +---- +<1> (Required) The import name with an associated component to the mount point. +<2> Use the `svg` value to display the `Quay` icon. + +* To configure a floating action button that contains a submenu, define the `global.floatingactionbutton/config` mount point in the same `slot` field in your `dynamic-plugins.yaml` file for multiple actions. The default slot is `page-end` when not specified. For example: ++ +.Example of a floating action button with submenu actions +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-bulk-import: + # Start of fab config + mountPoints: + - mountPoint: global.floatingactionbutton/config + importName: BulkImportPage # <1> + config: + slot: 'page-end' + icon: + label: 'Bulk import' + toolTip: 'Register multiple repositories in bulk' + to: /bulk-import/repositories + # end of fab config + appIcons: + - name: bulkImportIcon + importName: BulkImportIcon + dynamicRoutes: + - path: /bulk-import/repositories + importName: BulkImportPage + menuItem: + icon: bulkImportIcon + text: Bulk import + +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-global-floating-action-button: + mountPoints: + - mountPoint: application/listener + importName: DynamicGlobalFloatingActionButton + - mountPoint: global.floatingactionbutton/config + importName: NullComponent # <1> + config: + icon: github + label: 'Git' + toolTip: 'Github' + to: https://github.com/redhat-developer/rhdh-plugins + - mountPoint: global.floatingactionbutton/config + importName: NullComponent # <1> + config: + icon: '' + label: 'Quay' + showLabel: true + toolTip: 'Quay' + to: 'https://quay.io' +---- +<1> (Required) The import name with an associated component to the mount point. + +* To configure a floating action button to display only on specific pages, configure the `global.floatingactionbutton/config` mount point in the `backstage-plugin-global-floating-action-button` plugin and set the `visibleOnPaths` property as shown in the following example: ++ +.Example of a floating action button to display specific pages +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-bulk-import: + # start of fab config + mountPoints: + - mountPoint: global.floatingactionbutton/config + importName: BulkImportPage # <1> + config: + slot: 'page-end' + icon: + label: 'Bulk import' + toolTip: 'Register multiple repositories in bulk' + to: /bulk-import/repositories + visibleOnPaths: ['/catalog', '/settings'] + # end of fab config + appIcons: + - name: bulkImportIcon + importName: BulkImportIcon + dynamicRoutes: + - path: /bulk-import/repositories + importName: BulkImportPage + menuItem: + icon: bulkImportIcon + text: Bulk import +---- +<1> (Required) The import name with an associated component to the mount point. + +* To hide a floating action button on specific pages, configure the `global.floatingactionbutton/config` mount point in the `backstage-plugin-global-floating-action-button` plugin and set the `excludeOnPaths` property as shown in the following example: ++ +.Example of a floating action button to hide specific pages +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-bulk-import: + # start of fab config + mountPoints: + - mountPoint: global.floatingactionbutton/config + importName: BulkImportPage # <1> + config: + slot: 'page-end' + icon: + label: 'Bulk import' + toolTip: 'Register multiple repositories in bulk' + to: /bulk-import/repositories + excludeOnPaths: ['/bulk-import'] + # end of fab config + appIcons: + - name: bulkImportIcon + importName: BulkImportIcon + dynamicRoutes: + - path: /bulk-import/repositories + importName: BulkImportPage + menuItem: + icon: bulkImportIcon + text: Bulk import +---- +<1> (Required) The import name with an associated component to the mount point. + +== Floating action button parameters +Use the parameters as shown in the following table to configure your floating action button plugin. + +.Floating action button parameters +|=== +| Name | Description | Type | Default value | Required + +| `slot` +| Position of the floating action button. Valid values: `PAGE_END`, `BOTTOM_LEFT` +| `enum` +| `PAGE_END` +| No + +| `label` +| Name of the floating action button +| `String` +| Not applicable +| Yes + +| `icon` +| Icon of the floating action button. Recommended to use filled icons from the link:https://fonts.google.com/icons[Material Design library]. You can also use an svg icon. For example: `` +| `String`, `React.ReactElement`, `SVG image icon`, `HTML image icon` +| Not applicable +| No + +| `showLabel` +| Display of the label next to your icon +| `Boolean` +| Not applicable +| No + +| `size` +| Size of the floating action button +| `small`, `medium`, `large` +| `medium` +| No + +| `color` +| Color of the component. It supports both default and custom theme colors, that are added from the link:https://mui.com/material-ui/customization/palette/#custom-colors[Palette Getting started guide]. +| `default`, `error`, `info`, `inherit`, `primary`, `secondary`, `success`, `warning` +| `default` +| No + +| `onClick` +| Performed action when selecting a floating action button +| `React.MouseEventHandler` +| Not applicable +| No + +| `to` +| Link that opens when selecting a floating action button +| `String` +| Not applicable +| No + +| `toolTip` +| Text that appears when hovering over a floating action button +| `String` +| Not applicable +| No + +| `priority` +| Order of the floating action buttons displayed in the submenu. A larger value means higher priority. +| `number` +| Not applicable +| No + +| `visibleOnPaths` +| Display floating action button on the specified paths +| `string[]` +| Display floating action button on all paths +| No + +| `excludeOnPaths` +| Hide floating action button on the specified paths +| `string[]` +| Display floating action button on all paths +| No + +|=== + +[NOTE] +==== +If multiple floating button actions are assigned to the same `slot` value, the floating buttons are displayed as submenu options within the main floating action button. +==== \ No newline at end of file diff --git a/modules/configuring-deployment/proc-configuring-deployment-by-using-the-operator.adoc b/modules/configuring-deployment/proc-configuring-deployment-by-using-the-operator.adoc index ebdcaf9636..24623fced2 100644 --- a/modules/configuring-deployment/proc-configuring-deployment-by-using-the-operator.adoc +++ b/modules/configuring-deployment/proc-configuring-deployment-by-using-the-operator.adoc @@ -1,7 +1,7 @@ [id="configuring-the-deployment"] = Configuring {product} deployment when using the Operator -The {product} Operator exposes a `rhdh.redhat.com/v1alpha2` API Version of its custom resource (CR). This CR exposes a generic `spec.deployment.patch` field, which gives you full control over the {product-short} Deployment resource. This field can be a fragment of the standard `apps.Deployment` Kubernetes object. +The {product} Operator exposes a `rhdh.redhat.com/v1alpha3` API Version of its custom resource (CR). This CR exposes a generic `spec.deployment.patch` field, which gives you full control over the {product-short} Deployment resource. This field can be a fragment of the standard `apps.Deployment` Kubernetes object. .Procedure @@ -11,7 +11,7 @@ The {product} Operator exposes a `rhdh.redhat.com/v1alpha2` API Version of its c .Example [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -28,7 +28,7 @@ Add labels to the {product-short} pod. .Example adding the label `my=true` [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -50,7 +50,7 @@ Add an additional volume named `my-volume` and mount it under `/my/path` in the .Example additional volume [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -78,7 +78,7 @@ Replace the default `dynamic-plugins-root` volume with a persistent volume claim .Example `dynamic-plugins-root` volume replacement [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -103,7 +103,7 @@ Set the CPU request for the {product-short} application container to 250m. .Example CPU request [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -127,7 +127,7 @@ Add a new `my-sidecar` sidecar container into the {product-short} Pod. .Example side car container [source, yaml] ---- -apiVersion: rhdh.redhat.com/v1alpha2 +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub diff --git a/modules/configuring-external-databases/proc-configuring-mount-paths.adoc b/modules/configuring-external-databases/proc-configuring-mount-paths.adoc new file mode 100644 index 0000000000..42d9279d4b --- /dev/null +++ b/modules/configuring-external-databases/proc-configuring-mount-paths.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-configuring-mount-paths_{context}"] += Configuring mount paths for Secrets and PVCs + +By default, the mount path is the working directory of the {product-short} container. If you do not define the mount path, it defaults to `/opt/app-root/src`. + +.Procedure + +. To specify a PVC mount path, add the `rhdh.redhat.com/mount-path` annotation to your configuration file as shown in the following example: ++ +.Example specifying where the PVC mounts +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: __ + annotations: + rhdh.redhat.com/mount-path: /mount/path/from/annotation +---- +where: + +`rhdh.redhat.com/mount-path`:: Specifies which mount path the PVC mounts to (in this case, `/mount/path/from/annotation` directory). +__:: Specifies the PVC to mount. + +. To specify a Secret mount path, add the `rhdh.redhat.com/mount-path` annotation to your configuration file as shown in the following example: ++ +.Example specifying where the Secret mounts +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: __ + annotations: + rhdh.redhat.com/mount-path: /mount/path/from/annotation +---- +where: + +__:: Specifies the Secret name. \ No newline at end of file diff --git a/modules/configuring-external-databases/proc-configuring-postgresql-instance-using-helm.adoc b/modules/configuring-external-databases/proc-configuring-postgresql-instance-using-helm.adoc index 2f4c86d730..43a64c671f 100644 --- a/modules/configuring-external-databases/proc-configuring-postgresql-instance-using-helm.adoc +++ b/modules/configuring-external-databases/proc-configuring-postgresql-instance-using-helm.adoc @@ -24,7 +24,7 @@ By default, {product-short} uses a database for each plugin and automatically cr . Optional: Create a certificate secret to configure your PostgreSQL instance with a TLS connection: + -[source,terminal] +[source,terminal, subs="+attributes"] ---- cat < create -f - apiVersion: v1 @@ -52,7 +52,7 @@ EOF . Create a credential secret to connect with the PostgreSQL instance: + -[source,terminal] +[source,terminal, subs="+attributes"] ---- cat < create -f - apiVersion: v1 @@ -76,7 +76,7 @@ EOF . Configure your PostgreSQL instance in the Helm configuration file named `values.yaml`: + -[source,yaml] +[source,yaml,subs="+quotes,+attributes"] ---- # ... upstream: @@ -89,10 +89,10 @@ upstream: backend: database: connection: # configure Backstage DB connection parameters - host: ${POSTGRES_HOST} - port: ${POSTGRES_PORT} - user: ${POSTGRES_USER} - password: ${POSTGRES_PASSWORD} + host: $\{POSTGRES_HOST} + port: $\{POSTGRES_PORT} + user: $\{POSTGRES_USER} + password: $\{POSTGRES_PASSWORD} ssl: rejectUnauthorized: true, ca: @@ -140,7 +140,7 @@ upstream: secret: defaultMode: 420 optional: true - secretName: dynamic-plugins-npmrc + secretName: '{{ printf "%s-dynamic-plugins-npmrc" .Release.Name }}' - name: postgres-crt secret: secretName: {my-product-database-certificates-secrets} <7> diff --git a/modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc b/modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc index f2ab5c3824..8724519039 100644 --- a/modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc +++ b/modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc @@ -81,7 +81,7 @@ You can stop port forwarding when the copying of the data is complete. For more . Reconfigure your `{product-custom-resource-type}` custom resource (CR). For more information, see link:{configuring-book-url}#proc-configuring-postgresql-instance-using-operator_configuring-external-postgresql-databases[Configuring an external PostgreSQL instance using the Operator]. . Check that the following code is present at the end of your `Backstage` CR after reconfiguration: + -[source,yaml] +[source,yaml, subs="+attributes"] ---- # ... spec: diff --git a/modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc b/modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc new file mode 100644 index 0000000000..b5f04c1b04 --- /dev/null +++ b/modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc @@ -0,0 +1,43 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-mounting-to-specific-containers_{context}"] += Mounting Secrets and PVCs to specific containers + +By default, Secrets and PVCs mount only to the {product} `backstage-backend` container. You can add the `rhdh.redhat.com/containers` annotation to your configuration file to specify the containers to mount to. + +.Procedure + +. To mount Secrets to *all* containers, set the `rhdh.redhat.com/containers` annotation to `*` in your configuration file: ++ +.Example mounting to all containers +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: __ + annotations: + rhdh.redhat.com/containers: `*` +---- ++ +[IMPORTANT] +==== +Set `rhdh.redhat.com/containers` to `*` to mount it to all containers in the deployment. +==== + +. To mount to specific containers, separate the names with commas: ++ +.Example separating the list of containers +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: __ + annotations: + rhdh.redhat.com/containers: "init-dynamic-plugins,backstage-backend" +---- ++ +[NOTE] +==== +This configuration mounts the `__` PVC to the `init-dynamic-plugins` and `backstage-backend` containers. +==== \ No newline at end of file diff --git a/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc b/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc new file mode 100644 index 0000000000..7609a167e8 --- /dev/null +++ b/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc @@ -0,0 +1,19 @@ +[id="proc-configuring-high-availability-in-rhdh-helm-chart-deployment"] += Configuring high availability in a {product} Helm chart deployment + +When you are deploying {product-short} using the Helm chart, you must set `replicas` to a value greater than `1` in your Helm chart. The default value for `replicas` is `1`. + +.Procedure +To configure your {product-short} Helm chart for high availability, complete the following step: + +* In your Helm chart configuration file, set `replicas` to a value greater than `1`. For example: ++ +==== +[source,yaml,subs="+attributes,+quotes"] +---- +upstream: + backstage: + replicas: __ <1> +---- +==== +<1> Set the number of replicas based on the number of backup instances that you want to configure. \ No newline at end of file diff --git a/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc b/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc new file mode 100644 index 0000000000..c832f007b7 --- /dev/null +++ b/modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc @@ -0,0 +1,25 @@ +[id="proc-configuring-high-availability-in-rhdh-operator-deployment"] += Configuring High availability in a {product} Operator deployment + +{product-very-short} instances that are deployed with the Operator use configurations in the `{product-custom-resource-type}` custom resource. In the `{product-custom-resource-type}` custom resource, the default value for the `replicas` field is `1`. If you want to configure your {product-very-short} instance for high availability, you must set `replicas` to a value greater than `1`. + + +.Procedure + +* In your `{product-custom-resource-type}` custom resource, set `replicas` to a value greater than `1`. For example: ++ +==== +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: __ +spec: + application: + ... + replicas: __ <1> + ... +---- +==== +<1> Set the number of replicas based on the number of backup instances that you want to configure. \ No newline at end of file diff --git a/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc b/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc new file mode 100644 index 0000000000..87618fe945 --- /dev/null +++ b/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc @@ -0,0 +1,15 @@ +[id="proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment"] += Configuring the readOnlyRootFilesystem option in a {product} Helm chart deployment + +.Procedure +. In your `values.yaml` file, add the `readOnlyRootFilesystem: true` line to the `containerSecurityContext` section. For example: ++ +==== +[source,yaml,subs="+attributes,+quotes"] +---- +upstream: + backstage: + containerSecurityContext: + readOnlyRootFilesystem: true +---- +==== diff --git a/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment.adoc b/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment.adoc new file mode 100644 index 0000000000..3d2745f787 --- /dev/null +++ b/modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment.adoc @@ -0,0 +1,25 @@ +[id="proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment"] += Configuring the readOnlyRootFilesystem option in a {product} Operator deployment + +When you are deploying {product-short} using the Operator, you must specify a `patch` for the `deployment` in your `{product-custom-resource-type}` custom resource (CR) that applies the `readOnlyRootFilesystem` option to the `securityContext` section in the {product-short} backend container. + +.Procedure + +. In your `{product-custom-resource-type}` CR, add the `securityContext` specification. For example: ++ +==== +[source,yaml,subs="+attributes,+quotes"] +---- +spec: + deployment: + patch: + spec: + template: + spec: + containers: + - name: backstage-backend <1> + securityContext: + readOnlyRootFilesystem: true +---- +==== +<1> Name of the main container defined in the Operator default configuration. \ No newline at end of file diff --git a/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc b/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc new file mode 100644 index 0000000000..ac52bbcfa5 --- /dev/null +++ b/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc @@ -0,0 +1,167 @@ +[id="customizing-your-product-global-header_{context}"] += Customizing your {product} global header + +You can use the `red-hat-developer-hub.backstage-plugin-global-header` dynamic plugin to extend the global header with additional buttons and customize the order and position of icons and features. Additionally, you can create and integrate your custom dynamic header plugins using the mount points provided by this new header feature, allowing you to further tailor to suit your needs. +For more information about enabling dynamic plugins, see link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}]. + +.Default global header configuration + +[source,yaml,subs="+attributes,+quotes"] +---- + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header + disabled: false + pluginConfig: + app: + sidebar: + search: false <1> + settings: false <2> + dynamicPlugins: + frontend: + default.main-menu-items: <3> + menuItems: + default.create: + title: '' + red-hat-developer-hub.backstage-plugin-global-header: # the default enabled dynamic header plugin + mountPoints: + - mountPoint: application/header + importName: GlobalHeader + config: + position: above-main-content <4> + - mountPoint: global.header/component + importName: SearchComponent + config: + priority: 100 + - mountPoint: global.header/component + importName: Spacer + config: + priority: 99 + props: + growFactor: 0 + - mountPoint: global.header/component + importName: HeaderIconButton + config: + priority: 90 + props: + title: Self-service + icon: add + to: create + - mountPoint: global.header/component + importName: SupportButton + config: + priority: 80 + - mountPoint: global.header/component + importName: NotificationButton + config: + priority: 70 + - mountPoint: global.header/component + importName: Divider + config: + priority: 50 + - mountPoint: global.header/component + importName: ProfileDropdown + config: + priority: 10 + - mountPoint: global.header/profile + importName: MenuItemLink + config: + priority: 100 + props: + title: Settings + link: /settings + icon: manageAccounts + - mountPoint: global.header/profile + importName: LogoutButton + config: + priority: 10 +---- +<1> *search*: Hides the *Search* modal in the sidebar menu. Change it to `true` to display the *Search* modal in the sidebar. +<2> *settings*: Hides the *Settings* button in the sidebar menu. Change it to `true` to display the *Settings* button in the sidebar. +<3> `default.main-menu-items`: Hides the *Self-service* button from the sidebar menu. Remove this field to display the *Self-service* button in the sidebar. +<4> *position*: Defines the position of the header. Options: `above-main-content` or `above-sidebar`. + +To extend the functionality of the default global header, include any the following attributes in your global header entry: + +`mountPoint`:: +Specifies the location of the header. Use `application/header` to specify it as a global header. You can configure several global headers at different positions by adding entries to the `mountPoints` field. + +`importName`:: +Specifies the component exported by the global header plugin. ++ +The `red-hat-developer-hub.backstage-plugin-global-header` package (enabled by default) offers the following header components as possible mount point values: + +- **`SearchComponent`**: Adds a search bar (enabled by default). +- **`Spacer`**: Adds spacing in the header to position buttons at the end. Useful when you disable `SearchComponent`. +- **`HeaderIconButton`**: Adds an icon button. By default, the *Self-service* icon button remains enabled. +- **`SupportButton`**: Adds a *Support* icon button, allowing users to configure a link to an internal or external page. Enabled by default but requires additional configuration to display. +- **`NotificationButton`**: Adds a *Notifications* icon button to display unread notifications in real time and navigate to the *Notifications* page. Enabled by default (requires the notifications plugin). +- **`Divider`**: Adds a vertical divider. By default, a divider appears between the profile dropdown and other header components. +- **`ProfileDropdown`**: Adds a profile dropdown showing the logged-in user's name. By default, it contains two menu items. +- **`MenuItemLink`**: Adds a link item in a dropdown menu. By default, the profile dropdown includes a link to the *Settings* page. +- **`LogoutButton`**: Adds a logout button in the profile dropdown (enabled by default). +- **`CreateDropdown`**: Adds a *Self-service* dropdown button (disabled by default). The menu items are configurable. +- **`SoftwareTemplatesSection`**: Adds a list of software template links to the *Self-service* dropdown menu (disabled by default). You must enable `CreateDropdown`. +- **`RegisterAComponentSection`**: Adds a link to the *Register a Component* page in the *Self-service* dropdown menu (disabled by default). You must enable `CreateDropdown`. + +`config.position`:: +Specifies the position of the header. Supported values are `above-main-content` and `above-sidebar`. + +.Prerequisites +* You must configure the support URL in the `{my-app-config-file}` file to display the *Support* button in the header. +* You must install the notifications plugin to display the *Notifications* button in the header. + +.Procedure + +. Copy the default configuration and modify the field values to suit your needs. You can adjust the `priority` value of each header component to control its position. Additionally, you can enable or disable components by adding or removing them from the configuration. To ensure that the remaining header buttons align with the end of the header before the profile dropdown button, set `config.props.growFactor` to `1` in the `Spacer` mount point to enable the `Spacer` component. For example: ++ +[source,yaml] +---- +- mountPoint: global.header/component + importName: Spacer + config: + priority: 100 + props: + growFactor: 1 +---- + +. To use your custom header, you must install it as a dynamic plugin by adding your plugin configuration to your `app-config-dynamic.yaml` file. For example: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +- package: __ + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + : + mountPoints: + - mountPoint: application/header + importName: __ + config: + position: above-main-content + - mountPoint: global.header/component + importName: __ + config: + priority: 100 + - mountPoint: global.header/component + importName: __ + config: + priority: 90 +---- ++ +where: + +:: Specifies the package name. +:: Specifies the name of the application header. For example: `MyHeader` +:: Specifies the name of the header component. For example: `MyHeaderComponent` ++ +[NOTE] +==== +`importName` is an optional name referencing the value returned by the scaffolder field extension API. +==== +. Optional: To disable the global header, set the value of the `disabled` field to `true` in your `dynamic-plugins.yaml` file. For example: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header + disabled: true +---- \ No newline at end of file diff --git a/modules/configuring-the-global-header/proc-mount-points.adoc b/modules/configuring-the-global-header/proc-mount-points.adoc new file mode 100644 index 0000000000..3e3b91a364 --- /dev/null +++ b/modules/configuring-the-global-header/proc-mount-points.adoc @@ -0,0 +1,73 @@ +[id="mount-points-for-dynamic-plugin-intergration_{context}"] += Mount points for dynamic plugin integration + +You can customize the application header in {product-short} using mount points for dynamic plugins. These mount points give flexibility in configuring the position of the header, its components and dropdown menus. You can create a customized experience with the following enhancements: + +application/header:: +Controls the header position. Use `config.position` to set placement as either `above-main-content` or `above-sidebar`. + +global.header/component:: +Configures header components. Use `config.priority` to set the order of components, and pass properties (including CSS styles) via `config.props`. ++ +.Example adding a *Self-service* button +[source,yaml,subs="attributes,quotes"] +---- +- mountPoint: global.header/component + importName: HeaderIconButton + config: + priority: 80 + props: + title: *Self-service* + icon: add + to: create +---- ++ +.Example adding a spacer element +[source,yaml] +---- +- mountPoint: global.header/component + importName: Spacer + config: + priority: 99 + props: + growFactor: 0 +---- ++ +.Example adding a divider element +[source,yaml] +---- +mountPoints: + - mountPoint: global.header/component + importName: Divider + config: + priority: 150 +---- + +global.header/profile:: +Configures the profile dropdown list when the `ProfileDropdown` component is enabled. ++ +.Example adding a settings link to the profile dropdown +[source,yaml] +---- +- mountPoint: global.header/profile + importName: MenuItemLink + config: + priority: 100 + props: + title: Settings + link: /settings + icon: manageAccounts +---- + +global.header/create:: +Configures the create dropdown list when the `CreateDropdown` component is enabled. ++ +.Example adding a section for registering a component +[source,yaml] +---- +- mountPoint: global.header/create + importName: RegisterAComponentSection + config: + props: + growFactor: 0 +---- \ No newline at end of file diff --git a/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc b/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc index 96c5f849af..8508c9f3a6 100644 --- a/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc +++ b/modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc @@ -11,7 +11,7 @@ The `mountPath` field specifies the location where a ConfigMap or Secret is moun [NOTE] ==== -* {ocp-short} does not automatically update a volume mounted with `subPath`. By default, the {product-very-short} operator monitors these ConfigMaps or Secrets and refreshes the {product-very-short} Pod when changes occur. +* {ocp-short} does not automatically update a volume mounted with `subPath`. By default, the {product-very-short} Operator monitors these ConfigMaps or Secrets and refreshes the {product-very-short} Pod when changes occur. * For security purposes, {product} does not give the Operator Service Account read access to Secrets. As a result, mounting files from Secrets without specifying both mountPath and key is not supported. ==== @@ -40,14 +40,14 @@ data: ---- ==== + -.Minimal `{my-product-secrets}` Secret example +.Minimal {product} Secret example ==== [source,yaml,subs="+attributes,+quotes"] ---- apiVersion: v1 kind: Secret metadata: - name: {my-product-secrets} + name: `__` StringData: secret11.txt: | secret-content @@ -69,9 +69,14 @@ spec: key: file12.txt mountPath: /my/my-rhdh-config-map/path secrets: - - name: {my-product-secrets} + - name: `__` key: secret11.txt mountPath: /my/my-rhdh-secret/path ---- ==== + +[NOTE] +==== +`__` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}. +==== diff --git a/modules/configuring/proc-provisioning-your-custom-configuration.adoc b/modules/configuring/proc-provisioning-your-custom-configuration.adoc index 58b1fc6276..f4f41608fe 100644 --- a/modules/configuring/proc-provisioning-your-custom-configuration.adoc +++ b/modules/configuring/proc-provisioning-your-custom-configuration.adoc @@ -13,15 +13,21 @@ Your changes on this configuration might get reverted on {product-short} restart * By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance. .Procedure -. Author your custom `{my-product-secrets}.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files. +. Author your custom `__.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files. It contains one secret per line in `KEY=value` form. + * link:{authentication-book-url}[Enter your authentication secrets]. . Author your custom `{my-app-config-file}` file. This is the main {product-short} configuration file. -+ -The `baseUrl` field is mandatory in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. You must specify the `baseUrl` in both the `app` and `backend` sections to avoid errors during initialization. +You need a custom `{my-app-config-file}` file to avoid the {product-short} installer to revert user edits during upgrades. +When your custom `{my-app-config-file}` file is empty, {product-short} is using default values. + +** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file. + +** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. +The base URL is what a {product-short} user sees in their browser when accessing {product-short}. +The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection: + .Configuring the `baseUrl` in `{my-app-config-file}` ==== @@ -43,13 +49,13 @@ backend: origin: {my-product-url} ---- ==== -+ -Optionally, enter your configuration such as: -* link:{authentication-book-url}[{authentication-book-title}]. -* link:{authorization-book-url}[{authorization-book-title}]. -* link:{customizing-book-url}[Customization]. -* xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration]. +** Optionally, enter your configuration such as: + +*** link:{authentication-book-url}[{authentication-book-title}]. +*** link:{authorization-book-url}[{authorization-book-title}]. +*** link:{customizing-book-url}[Customization]. +*** xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration]. . Provision your custom configuration files to your {ocp-short} cluster. @@ -71,22 +77,27 @@ $ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file + Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config map by using the web console]. -.. Provision your `{my-product-secrets}.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project. +.. Provision your `__.txt` file to the `__` secret in the _<{my-product-namespace}>_ project. + [source,terminal,subs="+attributes,+quotes"] ---- -$ oc create secret generic {my-product-secrets} --from-file={my-product-secrets}.txt --namespace={my-product-namespace} +$ oc create secret generic `__` --from-file=`__.txt` --namespace={my-product-namespace} ---- + Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console]. +[NOTE] +==== +`__` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}. +==== + .Next steps Consider provisioning additional config maps and secrets: * To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets]. -* To enable dynamic plugins, link:{installing-and-viewing-dynamic-plugins-url}[provision your dynamic plugins config map]. +* To enable dynamic plugins, link:{installing-and-viewing-plugins-book-url}[provision your dynamic plugins config map]. * To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map]. diff --git a/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc index a67cf7d700..ca9a346c87 100644 --- a/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc +++ b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc @@ -1,7 +1,7 @@ [id="using-the-operator-to-run-rhdh-with-your-custom-configuration"] -= Using the {product} operator to run {product-short} with your custom configuration += Using the {product} Operator to run {product-short} with your custom configuration -To use the {product-short} operator to run {product} with your custom configuration, create your {product-custom-resource-type} custom resource (CR) that: +To use the {product-short} Operator to run {product} with your custom configuration, create your {product-custom-resource-type} custom resource (CR) that: * Mounts files provisioned in your custom config maps. * Injects environment variables provisioned in your custom secrets. @@ -31,7 +31,7 @@ spec: - name: {my-app-config-config-map} extraEnvs: secrets: - - name: {my-product-secrets} + - name: `__` extraFiles: mountPath: /opt/app-root/src replicas: 1 @@ -60,7 +60,7 @@ spec: dynamicPluginsConfigMapName: dynamic-plugins-rhdh extraEnvs: secrets: - - name: {my-product-secrets} + - name: `__` - name: {my-product-database-secrets} extraFiles: mountPath: /opt/app-root/src @@ -136,7 +136,7 @@ spec: `spec.application.extraEnvs.secrets`::: Enter your environment variables secret name list. + -.Inject the environment variables in your `{my-product-secrets}` secret +.Inject the environment variables in your {product} secret ==== [source,yaml,subs="+attributes,+quotes"] ---- @@ -144,11 +144,11 @@ spec: application: extraEnvs: secrets: - - name: {my-product-secrets} + - name: `__` ---- ==== + -.Inject the environment variables in the `{my-product-secrets}` and `{my-product-database-secrets}` secrets +.Inject the environment variables in the {product} and `{my-product-database-secrets}` secrets ==== [source,yaml,subs="+attributes,+quotes"] ---- @@ -156,11 +156,16 @@ spec: application: extraEnvs: secrets: - - name: {my-product-secrets} + - name: `__` - name: {my-product-database-secrets} ---- ==== +[NOTE] +==== +`__` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}. +==== + `spec.application.extraFiles.secrets`::: Enter your certificates files secret name and files list. + diff --git a/modules/customizing-templates/proc-adding-templates.adoc b/modules/customizing-templates/proc-adding-templates.adoc index 91ff78ec9b..837b3c9e34 100644 --- a/modules/customizing-templates/proc-adding-templates.adoc +++ b/modules/customizing-templates/proc-adding-templates.adoc @@ -15,7 +15,7 @@ You can add an existing template to your {product} instance by using the Catalog .Procedure -* In the `app-config.yaml` configuration file, modify the `catalog.rules` section to include a rule for templates, and configure the `catalog.locations` section to point to the template that you want to add, as shown in the following example: +* In the `{my-app-config-file}` configuration file, modify the `catalog.rules` section to include a rule for templates, and configure the `catalog.locations` section to point to the template that you want to add, as shown in the following example: + [source,yaml] ---- diff --git a/modules/customizing-templates/proc-creating-templates.adoc b/modules/customizing-templates/proc-creating-templates.adoc index 8113d724ea..7dd2ccdf99 100644 --- a/modules/customizing-templates/proc-creating-templates.adoc +++ b/modules/customizing-templates/proc-creating-templates.adoc @@ -14,10 +14,10 @@ You can create a template by using the Template Editor. + image::rhdh/template-editor.png[Template Editor] ** Open the URL `\https:///create/edit` for your {product} instance. -** Click *Create...* in the navigation menu of the {product} console, then click the overflow menu button and select *Template editor*. +** Click *Self-service* in the navigation menu of the {product} console, then click the overflow menu button and select *Template editor*. . Click *Edit Template Form*. . Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see <>. -. In the *Name ** field, enter a unique name for your template. +. In the *Name* field, enter a unique name for your template. . From the *Owner* drop-down menu, choose an owner for the template. . Click *Next*. . In the *Repository Location* view, enter the following information about the hosted repository that you want to publish the template to: diff --git a/modules/customizing-templates/ref-creating-templates.adoc b/modules/customizing-templates/ref-creating-templates.adoc index d894a74ace..b0e3e71ff1 100644 --- a/modules/customizing-templates/ref-creating-templates.adoc +++ b/modules/customizing-templates/ref-creating-templates.adoc @@ -57,8 +57,8 @@ spec: # ... ---- <1> Specify a name for the template. -<2> Specify a title for the template. This is the title that is visible on the template tile in the *Create...* view. -<3> Specify a description for the template. This is the description that is visible on the template tile in the *Create...* view. +<2> Specify a title for the template. This is the title that is visible on the template tile in the *Self-service* view. +<3> Specify a description for the template. This is the description that is visible on the template tile in the *Self-service* view. <4> Specify the ownership of the template. The `owner` field provides information about who is responsible for maintaining or overseeing the template within the system or organization. In the provided example, the `owner` field is set to `backstage/techdocs-core`. This means that this template belongs to the `techdocs-core` project in the `backstage` namespace. <5> Specify the component type. Any string value is accepted for this required field, but your organization should establish a proper taxonomy for these. {product} instances may read this field and behave differently depending on its value. For example, a `website` type component may present tooling in the {product} interface that is specific to just websites. + diff --git a/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc b/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc new file mode 100644 index 0000000000..2c8936032b --- /dev/null +++ b/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc @@ -0,0 +1,9 @@ +[id='con-customize-rhdh-sidebar-menuitems_{context}'] += Customizing the sidebar menu items for your {product-short} instance + +The sidebar menu in {product} consists of two main parts that you can configure: + +Dynamic plugin menu items:: Your preferences and your active plugins define dynamically one part of the sidebar menu. +Main menu items:: The core navigation structure of sidebar is static. + +* *Dynamic plugin menu items*: These items are displayed beneath the main menu and can be customized based on the plugins installed. The main menu items section is dynamic and can change based on your preferences and installed plugins. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc new file mode 100644 index 0000000000..663db7104a --- /dev/null +++ b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc @@ -0,0 +1,63 @@ +[id='proc-configuring-dynamic-plugin-menuitem_{context}'] += Configuring a dynamic plugin menu item for your {product-short} instance + +Configure a dynamic plugin menu item using the following step: + +.Procedure + +* In the `{my-app-config-file}` file, update the `menuItems` section of your __ plugin. For example: ++ +[source,yaml] +---- +dynamicPlugins: + frontend: + __: # <1> + menuItems: + : # <2> + icon: # home | group | category | extension | school | __ # <3> + title: __ # <4> + priority: 10 # <5> + parent: favorites # <6> +---- +<1> `__`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file. +<2> `__`: Enter a unique name in the main sidebar navigation for either a standalone menu item or a parent menu item. If this field specifies a plugin menu item, the name of the menu item must match the name using in the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. +<3> `icon`: (Optional) Enter the icon name. You can use any of the following icons: + ** Default icons, such as `home`, `group`, `category`, `extension`, and `school`. To use default icons, set the icon as an (`" "`) empty string. + ** A custom icon, where __ specifies the name of your custom icon + ** An SVG icon, such as: `icon: ...` + ** An HTML image, such as: `icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png` +<4> `title`: (Optional) Enter the menu item title. Omit it when the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. To hide the title from the sidebar, set the title as an (`" "`) empty string. +// Update <4> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. +<5> `priority`: (Optional) Sets the order in which menu items appear in the sidebar. The default priority is 0, which places the item at the bottom of the list. A higher priority value places the item higher in the sidebar. You can define this field for each section. +<6> `parent`: (Optional) Enter the parent menu item under which the current item is nested. If this field is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this field for each section. + ++ +.Example `menuItems` configuration +[source,yaml,subs="+attributes"] +---- +dynamicPlugins: + frontend: + __: + dynamicRoutes: + - path: /my-plugin + module: CustomModule + importName: FooPluginPage + menuItem: + icon: fooIcon + text: Foo Plugin Page + menuItems: + my-plugin: # <1> + priority: 10 # <2> + parent: favorites # <3> + favorites: # <4> + icon: favorite # <5> + title: Favorites # <6> + priority: 100 # <7> +---- +<1> `my-plugin`: Matches the value of the `path` field in `dynamicRoutes`. +<2> `priority`: Controls order of plugins under the parent menu item. +<3> `parent`: Nests this plugin under the `favorites` parent menu item. +<4> `favorites`: Configuration for the parent menu item. +<5> `icon`: Displays the `favorite` icon from the {product-very-short} system icons. +<6> `title`: Displays the title name for the parent menu item. +<7> `priority`: Order of the `favourites` menu item in the sidebar. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc index 0304c411a3..b6c8cc44f0 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc @@ -5,9 +5,9 @@ [id="proc-customize-rhdh-branding-logo_{context}"] = Customizing the branding logo of your {product-short} instance -You can customize the branding logo of your {product-short} instance by configuring the `branding` section the `app-config-rhdh.yaml` file, as shown in the following example: +You can customize the branding logo of your {product-short} instance by configuring the `branding` section in the `{my-app-config-file}` file, as shown in the following example: -[source,yaml] +[source,yaml,subs="+quotes"] ---- app: branding: @@ -19,6 +19,22 @@ where: <1> `fullLogo` is the logo on the expanded (pinned) sidebar and expects a base64 encoded image. <2> `iconLogo` is the logo on the collapsed (unpinned) sidebar and expects a base64 encoded image. ++ +You can format the `BASE64_EMBEDDED_FULL_LOGO` environment variable as follows: ++ +[source,yaml,subs="+quotes"] +---- +BASE64_EMBEDDED_FULL_LOGO: "data:__;base64,__" +---- ++ +The following example demonstrates how to customize the `BASE64_EMBEDDED_FULL_LOGO` using the `data:__;base64,__` format: ++ +[source,yaml,subs="+quotes"] +---- +SVGLOGOBASE64=$(base64 -i logo.svg) +BASE64_EMBEDDED_FULL_LOGO="data:image/svg+xml;base64,$SVGLOGOBASE64" +---- +Replace `image/svg+xml` with the correct media type for your image (for example, `image/png` and `image/jpeg`), and adjust the file extension accordingly. As a result, you can embed the logo directly without referencing an external file. You can also customize the width of the branding logo by setting a value for the `fullLogoWidth` field in the `branding` section, as shown in the following example: diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-font.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-font.adoc index 8a6caee0da..79876b751b 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-font.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-font.adoc @@ -4,7 +4,7 @@ [id="proc-customize-rhdh-font_{context}"] = Customizing the font for your {product-short} instance -You can configure the `typography` section of the `app-config-rhdh.yaml` file to change the default font family and size of the page text, as well as the font family and size of each heading level, as shown in the following example: +You can configure the `typography` section of the `{my-app-config-file}` file to change the default font family and size of the page text, as well as the font family and size of each heading level, as shown in the following example: [source,yaml] ---- diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc index 27c212a035..e61d21e192 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc @@ -4,7 +4,7 @@ [id="proc-customize-rhdh-page-theme_{context}"] = Customizing the page theme header for your {product-short} instance -You can customize the header color for the light and dark theme modes in your {product-short} instance by modifying the `branding.theme` section of the `app-config-rhdh.yaml` file. You can also customize the page headers for additional {product-short} pages, such as the *Home*, *Catalog*, and *APIs* pages. +You can customize the header color for the light and dark theme modes in your {product-short} instance by modifying the `branding.theme` section of the `{my-app-config-file}` file. You can also customize the page headers for additional {product-short} pages, such as the *Home*, *Catalog*, and *APIs* pages. [source,yaml] ---- diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc index a848198913..5f7869bce7 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc @@ -4,7 +4,7 @@ [id="proc-customize-rhdh-branding_{context}"] = Customizing the theme mode color palettes for your {product-short} instance -You can customize the color palettes of the light and dark theme modes in your {product-short} instance by configuring the `light.palette` and `dark.palette` parameters in the `branding.theme` section of the `app-config-rhdh.yaml` file, as shown in the following example: +You can customize the color palettes of the light and dark theme modes in your {product-short} instance by configuring the `light.palette` and `dark.palette` parameters in the `branding.theme` section of the `{my-app-config-file}` file, as shown in the following example: [source,yaml] ---- diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc index 201d15172d..5dd1a4e2f9 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc @@ -1,129 +1,46 @@ [id='proc-customize-rhdh-sidebar-menuitems_{context}'] = Customizing the sidebar menu items for your {product-short} instance -The sidebar menu in {product} consists of two main parts: - -* *Main menu items*: These items are the static menu items that form the core navigation structure of sidebar. These menu items remain consistent and are predefined. - -* *Dynamic plugin menu items*: These items are displayed beneath the main menu and can be customized based on the plugins installed. The main menu items section is dynamic and can change based on your preferences and installed plugins. +Customize the main menu items using the following steps: .Procedure - -. Customize the main menu items using the following steps: -+ --- -.. Open the `app-config-rhdh.yaml` file. +. Open the `{my-app-config-file}` file. .. To customize the order and parent-child relationships for the main menu items, use the `dynamicPlugins.frontend.default.main-menu-items.menuItems` field. .. For dynamic plugin menu items, use the `dynamicPlugins.frontend..menuItems` field. -.Example `app-config-rhdh.yaml` file -[source,yaml] ----- -dynamicPlugins: - frontend: - : # same as `scalprum.name` key in plugin's `package.json` - menuItems: # optional, allows you to configure plugin menu items in the main sidebar navigation - : # unique name in the plugin menu items list <1> - icon: home | group | category | extension | school | __ # <2> - title: My Plugin Page # optional, same as `menuItem.text` in `dynamicRoutes` <3> - priority: 10 # optional, defines the order of menu items in the sidebar <4> - parent: favorites # optional, defines parent-child relationships for nested menu items <5> ----- - -You can modify the fields in the previous example to configure the desired order and parent-child relationships of the sidebar menu items. - -<1> This attribute represents a unique name in the main sidebar navigation. It can denote either a standalone menu item or a parent menu item. If this attribute represents a plugin menu item, the name of the attribute must match with the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. -+ -For more complex, multi-segment paths such as `path: /metrics/users/info`, the `menu_item_name` must use dot notation to represent the full path, for example, `metrics.users.info`. Trailing and leading slashes in paths are ignored. For example, `path: /docs` results in `menu_item_name: docs`, and `path: /metrics/users` results in `menu_item_name: metrics.users`. - -<2> This optional attribute specifies the icon for the menu item. You can use default icons or extend the icon set with dynamic plugins. {product-short} also provides additional icons in its internal library, such as: -+ -.Home Icon in the internal library -[source, yaml] ----- -dynamicPlugins: - frontend: - : - menuItems: - : - icon: home ----- -+ -Similarly, the internal library includes icons for `group`, `category`, `extension`, and `school`. If the icon is already defined in the `dynamicRoutes` configuration under `menuItem.icon`, it can be removed from the in the `menuItems` configuration. Also, both SVG and HTML image icons are supported. For example: -+ -.Example SVG icon -[source,html] ----- -icon: ... ----- -+ -.Example image icon -[source,html] ----- -icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png ----- - -<3> This optional attribute specifies the title of the menu item. It can be removed if the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. - -<4> This optional attribute sets the order in which menu items appear in the sidebar. The default priority is 0, which places the item at the bottom of the list. A higher priority value places the item higher in the sidebar. You can define this attribute for each section. - -<5> This optional attribute specifies the parent menu item under which the current item is nested. If this attribute is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this attribute for each section. - -.Example `menuItems` configuration -[source,yaml] ----- -dynamicPlugins: - frontend: - : - dynamicRoutes: - - path: /my-plugin - module: CustomModule - importName: FooPluginPage - menuItem: - icon: fooIcon - text: Foo Plugin Page - menuItems: - my-plugin: # matches `path` in `dynamicRoutes` - priority: 10 # controls order of plugins under the parent menu item - parent: favorites # nests this plugin under the `favorites` parent menu item - favorites: # configuration for the parent menu item - icon: favorite # icon from RHDH system icons - title: Favorites # title for the parent menu item - priority: 100 # controls the order of this top-level menu item ----- --- - -. To ensure that a menu item is identified as a main menu item, you must add the `default.` prefix to its key. For example: -+ --- -.Example configuration of main menu items in sidebar navigation +.Example `{my-app-config-file}` file [source,yaml] ---- dynamicPlugins: frontend: - default.main-menu-items: # key for configuring static main menu items - menuItems: - default.: # key of the menu item configuration. `default.` prefix is required for a main menu item key <1> - parent: my_menu_group # optional, specifies the parent menu item for this item - priority: 10 # optional, specifies the order of this menu item within its menu level - default.: # must be configured if it is specified as the parent of any menu items. `default.` prefix is required for a main group parent item key <1> - icon: my_menu_group_icon # required for parent menu items, defines the icon for the menu group - title: my_menu_group_title # required for parent menu items, defines the icon for the menu group - priority: 100 # optional, specifies the order of the parent menu item in the sidebar ----- - - -<1> The `default.` prefix identifies an item as a main menu item. You can add the `default.` prefix to both individual menu items or parent menu group configuration, such as `default.` in the previous example. - -[NOTE] -==== -The default priority of main menu items determines their order in the sidebar. You can customize the order of the static main menu items by adjusting their priority values. Ensure that the priority and title of each item is clear to facilitate easy reordering. -==== --- - - - - - - - + default.main-menu-items: + menuItems: + default.home: + title: Home + icon: home + priority: 100 + default.my-group: + title: My Group + icon: group + priority: 90 + default.catalog: + title: Catalog + icon: category + to: catalog + priority: 80 + default.apis: + title: APIs + icon: extension + to: api-docs + priority: 70 + default.learning-path: + title: Learning Paths + icon: school, + to: learning-paths + priority: 60 + default.create: + title: Self-service + icon: add + to: create + priority: 50 +---- \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customizing-entity-detail-tab-layout.adoc b/modules/customizing-the-appearance/proc-customizing-entity-detail-tab-layout.adoc new file mode 100644 index 0000000000..16ada838b6 --- /dev/null +++ b/modules/customizing-the-appearance/proc-customizing-entity-detail-tab-layout.adoc @@ -0,0 +1,50 @@ +[id="configuring-entity-detail-tab-layout_{context}"] += Configuring entity detail tab layout + +Each {product} entity detail tab has a default opinionated layout. +For consistency with your organization needs, you can change the entity detail tab content when the plugin that contributes the tab content allows a configuration. + +.Prerequisites + +* The plugin that contributes the tab content allows a configuration, such as https://github.com/redhat-developer/rhdh/blob/release-{product-version}/dynamic-plugins.default.yaml[{product-short} plugins defining a default configuration in a `config` section]. + +.Procedure + +* Copy the plugin default configuration in your `{my-app-config-file}` file, and change the `layout` properties. ++ +[source,yaml,subs="+quotes"] +---- +global: + dynamic: + plugins: + - package: __ + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + __: + mountPoints: + - mountPoint: __ + importName: __ + config: + layout: + gridColumn: + lg: span 6 + xs: span 12 +---- +`package`:: +Enter your package location, such as `./dynamic-plugins/dist/backstage-community-plugin-tekton`. + +`__`:: +Enter your plugin name, such as: `backstage-community.plugin-tekton`. + +`mountPoint`:: +Copy the mount point defined in the plugin default configuration, such as: `entity.page.ci/cards`. + +`importName`:: +Copy the import name defined in the plugin default configuration, such as: `TektonCI`. + +`layout`:: Enter your layout configuration. +The tab content is displayed in a responsive grid that uses a 12 column-grid and supports different breakpoints (`xs`, +`sm`, `md`, `lg`, `xl`) that can be specified for a CSS property, such as `gridColumn`. +The example uses 6 of the 12 columns to show two Tekton CI cards side-by-side on large (`lg`) screens (`span 6` columns) and show them among themselves (`xs` and above `span 12` columns). diff --git a/modules/customizing-the-appearance/proc-customizing-entity-tab-titles.adoc b/modules/customizing-the-appearance/proc-customizing-entity-tab-titles.adoc new file mode 100644 index 0000000000..85952723a7 --- /dev/null +++ b/modules/customizing-the-appearance/proc-customizing-entity-tab-titles.adoc @@ -0,0 +1,42 @@ +[id="configuring-entity-tab-titles_{context}"] += Configuring entity tab titles + +{product} provides a default opinionated tab set for catalog entity views. +For consistency with your organization needs, you can rename, reorder, remove, and add tab titles. + +.Procedure +* For each tab to modify, enter your desired values in the `entityTabs` section in your `{my-app-config-file}` file: ++ +[source,yaml,subs="+quotes"] +---- +upstream: + backstage: + appConfig: + dynamicPlugins: + frontend: + __: + entityTabs: + - mountPoint: __ + path: __ + title: __ + priority: _<priority>_ +---- + +`_<plugin_name>_`:: +Enter the plugin name, such as `backstage-community.plugin-topology`. + +`mountPoint`:: +Enter the tab mountpoint, such as `entity.page.topology`. + +`path`:: +Enter the tab path, such as `/topology`. +`title`:: +Enter the tab title, such as `Topology`. + +`priority`:: +Optional. ++ +To reorder tabs, enter the tab priority, such as `42`. +Higher priority appears first. ++ +To remove a tab, enter a negative value, such as `-1`. diff --git a/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc b/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc index 48e372045a..fa279ccc3f 100644 --- a/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc +++ b/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc @@ -24,7 +24,7 @@ For more information about creating a custom theme, see link:https://backstage.i . Configure {product-short} to load the theme in the UI by using the `themes` configuration field: + -.`app-config-rhdh.yaml` fragment +.`{my-app-config-file}` fragment [source,yaml] ---- dynamicPlugins: diff --git a/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc new file mode 100644 index 0000000000..091c7b84e5 --- /dev/null +++ b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc @@ -0,0 +1,66 @@ +[id='proc-modifying-or-adding-rhdh-custom-menuitem_{context}'] += Modifying or adding a custom menu items for your {product-short} instance + +Modify a main menu item or add a custom menu item using the following step: + +.Procedure +* In the `{my-app-config-file}` file, add a section to the `default.main-menu-items` > `menuItems` section. Use the `default.` prefix to identify the key as a main menu item. ++ +[source,yaml] +---- +dynamicPlugins: + frontend: + default.main-menu-items: + menuItems: + default._<menu_group_parent_item_name>_: # <1> + icon: # home | group | category | extension | school | _<my_icon>_ # <2> + title: _<menu_group_parent_title>_ # <3> + priority: 10 # <4> + default._<menu_item_name>_: # <5> + parent: _<menu_group_parent_item_name>_ # <6> + icon: # home | group | category | extension | school | _<my_icon>_ # <7> + title: _<my_menu_title>_ # <8> + to: _<path_to_the_menu_target_page>_ # <9> + priority: 100 # <10> +---- +<1> `default._<menu_group_parent_item_name>_`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default._<menu_item_name>_` has a `parent` value set, this field is not needed. +<2> `icon`: Enter the menu icon. Required for parent menu items. +<3> `title`: Enter the menu group title. Required for parent menu items. +<4> `priority`: (Optional) Enter the order of this menu item within its menu level. +<5> `default._<menu_item_name>_`: Enter the menu item name for which you want to override the default value. Add the `default.` prefix to identify a main menu item. +<6> `parent`: (Optional) Enter the parent menu item for this item. Required if <menu_item_name> is specified as the child of any menu items. +<7> `icon`: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string. +<8> `title`: (Optional) Enter the menu group title. Only required for adding a new custom main menu item. To hide a default main menu item title from the sidebar, set the title as an (`" "`) empty string. +// Update <8> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. +<9> `to`: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page. +<10> `priority`: (Optional) Enter the order of this menu item within its menu level. + ++ +.Example `mainItems` configuration +[source,yaml] +---- +default.main-menu-items: + menuItems: + default.catalog: + icon: category # <1> + title: My Catalog + priority: 5 + default.learning-path: + title: '' # <2> + default.parentlist: # <3> + title: Overview + icon: bookmarks + default.home: + parent: default.parentlist # <4> + default.references: + title: References # <5> + icon: school # <6> + to: /references # <7> +---- +<1> `icon`: Specifies if you want to change the icon default menu item for the catalog. +<2> `title`: Specifies an empty string `" "` to hide the learning path from the default sidebar. +<3> `default.parentlist`: Introduces the parent menu item. +<4> `parent`: Nests home menu under the `default.parentlist` parent menu item. +<5> `title`: Specifies a name for `default.references` +<6> `icon`: Displays the `school` icon. +<7> `to`: Redirects `default.references` to the `/references` page. \ No newline at end of file diff --git a/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc b/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc index 139b597764..ac95e5b45d 100644 --- a/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc +++ b/modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc @@ -11,7 +11,7 @@ There are two component variants that you can use to customize various component In addition to assigning a component variant to each parameter in the light or dark theme mode configurations, you can toggle the `rippleEffect` `on` or `off`. -The following code shows the options that you can use in the `app-config-rhdh.yaml` file to configure the theme components for your {product-short} instance: +The following code shows the options that you can use in the link:{configuring-book-url}[`{my-app-config-file}` file] to configure the theme components for your {product-short} instance: [source,yaml] ---- diff --git a/modules/customizing-the-appearance/ref-customize-rhdh-default-backstage.adoc b/modules/customizing-the-appearance/ref-customize-rhdh-default-backstage.adoc index 5fdd98e980..121b4c7b6e 100644 --- a/modules/customizing-the-appearance/ref-customize-rhdh-default-backstage.adoc +++ b/modules/customizing-the-appearance/ref-customize-rhdh-default-backstage.adoc @@ -4,11 +4,11 @@ [id="ref-customize-rhdh-default-backstage_{context}"] = Default Backstage theme -You can use the default Backstage theme configurations to make your {product-short} instance look like a standard Backstage instance. You can also modify the `app-config-rhdh.yaml` file to customize or disable particular parameters. +You can use the default Backstage theme configurations to make your {product-short} instance look like a standard Backstage instance. You can also modify the `{my-app-config-file}` file to customize or disable particular parameters. == Default Backstage theme color palette -The `app-config-rhdh.yaml` file uses the following configurations for the default Backstage color palette: +The `{my-app-config-file}` file uses the following configurations for the default Backstage color palette: [source,yaml] ---- @@ -138,7 +138,7 @@ app: warningText: "#000000" ---- -Alternatively, you can use the following `variant` and `mode` values in the `app-config-rhdh.yaml` file to apply the previous default configuration: +Alternatively, you can use the following `variant` and `mode` values in the `{my-app-config-file}` file to apply the previous default configuration: [source,yaml] ---- @@ -155,7 +155,7 @@ app: == Default Backstage page themes -The default Backstage header color is white in light mode and black in dark mode, as shown in the following `app-config-rhdh.yaml` file configuration: +The default Backstage header color is white in light mode and black in dark mode, as shown in the following `{my-app-config-file}` file configuration: [source,yaml] ---- diff --git a/modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc b/modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc index d2aa3acdf3..ed2ab28059 100644 --- a/modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc +++ b/modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc @@ -4,11 +4,11 @@ [id="ref-customize-rhdh-default-rhdh_{context}"] = Default {product} theme -You can use the default {product} theme configurations to make your {product-short} instance look like a standard {product} instance. You can also modify the `app-config-rhdh.yaml` file to customize or disable particular parameters. +You can use the default {product} theme configurations to make your {product-short} instance look like a standard {product} instance. You can also modify the `{my-app-config-file}` file to customize or disable particular parameters. == Default {product} theme color palette -The `app-config-rhdh.yaml` file uses the following configurations for the default {product} color palette: +The `{my-app-config-file}` file uses the following configurations for the default {product} color palette: [source,yaml] ---- @@ -88,7 +88,7 @@ app: mainSectionBackgroundColor: "#FFF" headerBottomBorderColor: "#C7C7C7" cardBackgroundColor: "#FFF" - sideBarBackgroundColor: "#212427" + sidebarBackgroundColor: "#212427" cardBorderColor: "#C7C7C7" tableTitleColor: "#181818" tableSubtitleColor: "#616161" @@ -180,7 +180,7 @@ app: mainSectionBackgroundColor: "#0f1214" headerBottomBorderColor: "#A3A3A3" cardBackgroundColor: "#292929" - sideBarBackgroundColor: "#1b1d21" + sidebarBackgroundColor: "#1b1d21" cardBorderColor: "#A3A3A3" tableTitleColor: "#E0E0E0" tableSubtitleColor: "#E0E0E0" @@ -202,7 +202,7 @@ app: headerBackgroundImage: "none" ---- -Alternatively, you can use the following `variant` and `mode` values in the `app-config-rhdh.yaml` file to apply the previous default configuration: +Alternatively, you can use the following `variant` and `mode` values in the `{my-app-config-file}` file to apply the previous default configuration: [source,yaml] ---- @@ -219,7 +219,7 @@ app: == Default {product} page themes -The default {product-short} header color is white in light mode and black in dark mode, as shown in the following `app-config-rhdh.yaml` file configuration: +The default {product-short} header color is white in light mode and black in dark mode, as shown in the following `{my-app-config-file}` file configuration: [source,yaml] ---- diff --git a/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc b/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc index 8b24339041..43d5d50a44 100644 --- a/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc +++ b/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc @@ -7,7 +7,7 @@ Administrators can change the fixed height of cards that are in a 12-column grid. -The default Home page is as shown in the following `app-config` file configuration: +The default Home page is as shown in the following `{my-app-config-file}` file configuration: [source,yaml] ---- diff --git a/modules/customizing-the-home-page/proc-defining-the-layout-of-the-product-home-page.adoc b/modules/customizing-the-home-page/proc-defining-the-layout-of-the-product-home-page.adoc index a8deb3d9ec..7c9bb2e8c6 100644 --- a/modules/customizing-the-home-page/proc-defining-the-layout-of-the-product-home-page.adoc +++ b/modules/customizing-the-home-page/proc-defining-the-layout-of-the-product-home-page.adoc @@ -5,6 +5,8 @@ [id="defining-the-layout-of-the-product-home-page_{context}"] = Defining the layout of the {product} Home page +The Home page uses a 12-column grid to position your cards. You can use the optimal parameters to define the layout of your {product-short} Home page. + .Prerequisites * Include the following optimal parameters in each of your breakpoints: ** width (w) @@ -12,7 +14,7 @@ ** position (x and y) .Procedure -* Configure your {product-short} `app-config.yaml` configuration file by choosing one of the following options: +* Configure your {product-short} `{my-app-config-file}` configuration file by choosing one of the following options: ** Use the full space on smaller windows and half of the space on larger windows as follows: [source,yaml] @@ -36,7 +38,7 @@ dynamicPlugins: debugContent: a placeholder ---- -** Show the cards side by side by defining the `x` parameter as follows: +* Show the cards side by side by defining the `x` parameter as shown in the following example: [source,yaml] ---- @@ -73,7 +75,7 @@ dynamicPlugins: ---- However, you can see a second card below this card by default. -* Show the cards in three columns by defining the `x` parameter as follows: +* Show the cards in three columns by defining the `x` parameter as shown in the following example: [source,yaml] ---- diff --git a/modules/customizing-the-learning-paths/proc-customize-rhdh-learning-paths.adoc b/modules/customizing-the-learning-paths/proc-customize-rhdh-learning-paths.adoc deleted file mode 100644 index 965f9574a5..0000000000 --- a/modules/customizing-the-learning-paths/proc-customize-rhdh-learning-paths.adoc +++ /dev/null @@ -1,82 +0,0 @@ -[id='proc-customize-rhdh-learning-paths_{context}'] -= Customizing the Learning Paths in {product} - -In {product}, you can configure Learning Paths by passing the data into the `{my-app-config-file}` file as a proxy. The base URL must include the `/developer-hub/learning-paths` proxy. - -[NOTE] -==== -Due to the use of overlapping `pathRewrites` for both the `learning-path` and `homepage` quick access proxies, you must create the `learning-paths` configuration (`^api/proxy/developer-hub/learning-paths`) before you create the `homepage` configuration (`^/api/proxy/developer-hub`). - -For more information about customizing the Home page in {product}, see xref:customizing-the-home-page[Customizing the Home page in {product}]. -==== - -You can provide data to the Learning Path from the following sources: - -* JSON files hosted on GitHub or GitLab. -* A dedicated service that provides the Learning Path data in JSON format using an API. - -== Using hosted JSON files to provide data to the Learning Paths - -.Prerequisites - -You have installed {product} by using either the Operator or Helm chart. -For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp[{installing-on-ocp-book-title}]. - -.Procedure - -To access the data from the JSON files, complete the following step: - -* Add the following code to the `{my-app-config-file}` file: -+ -[source,yaml] ----- -proxy: - endpoints: - '/developer-hub': - target: https://raw.githubusercontent.com/ - pathRewrite: - '^/api/proxy/developer-hub/learning-paths': '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json' - '^/api/proxy/developer-hub/tech-radar': '/redhat-developer/rhdh/main/packages/app/public/tech-radar/data-default.json' - '^/api/proxy/developer-hub': '/redhat-developer/rhdh/main/packages/app/public/homepage/data.json' - changeOrigin: true - secure: true ----- - -== Using a dedicated service to provide data to the Learning Paths - -When using a dedicated service, you can do the following: - -* Use the same service to provide the data to all configurable {product-short} pages or use a different service for each page. -* Use the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] as an example service, which provides data for both the Home and Tech Radar pages. The `red-hat-developer-hub-customization-provider` service provides the same data as default {product-short} data. You can fork the `red-hat-developer-hub-customization-provider` service repository from GitHub and modify it with your own data, if required. -* Deploy the `red-hat-developer-hub-customization-provider` service and the {product-short} Helm chart on the same cluster. - -.Prerequisites - -* You have installed the {product} using Helm chart. -For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp[{installing-on-ocp-book-title}]. - -.Procedure - -To use a dedicated service to provide the Learning Path data, complete the following steps: - -. Add the following code to the `app-config-rhdh.yaml` file: -+ -[source,yaml] ----- - proxy: - endpoints: - # Other Proxies - '/developer-hub/learning-paths': - target: ${LEARNING_PATH_DATA_URL} - changeOrigin: true - # Change to "false" in case of using self hosted cluster with a self-signed certificate - secure: true ----- -where the `LEARNING_PATH_DATA_URL` is defined as `pass:c[http://<SERVICE_NAME>/learning-paths]`, for example, `pass:c[http://rhdh-customization-provider/learning-paths]`. -+ -[NOTE] -==== -You can define the `LEARNING_PATH_DATA_URL` by adding it to `rhdh-secrets` or by directly replacing it with its value in your custom ConfigMap. -==== -+ -. Delete the {product-short} pod to ensure that the new configurations are loaded correctly. diff --git a/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-a-dedicated-service.adoc b/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-a-dedicated-service.adoc new file mode 100644 index 0000000000..7e07c05fe7 --- /dev/null +++ b/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-a-dedicated-service.adoc @@ -0,0 +1,23 @@ +[id='proc-customizing-the-learning-paths-by-using-a-customization-service_{context}'] += Customizing the Learning Paths by using a customization service + +For advanced scenarios, you can host your {product} customization service to provide data to all configurable {product-short} pages, such as the Learning Paths. +You can even use a different service for each page. + +.Procedure +. Deploy your {product-short} customization service on the same {ocp-short} cluster as your {product-short} instance. +You can find an example at link:https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`], that provides the same data as default {product-short} data. +The customization service provides a Learning Paths data URL such as: `pass:c,a,q[http://_<rhdh-customization-provider>_/learning-paths]`. + +. Configure the {product-short} proxy to use your dedicated service to provide the Learning Path data, add the following to the link:{configuring-book-url}[`{my-app-config-file}` file]: ++ +[source,yaml,subs='+quotes'] +---- +proxy: + endpoints: + '/developer-hub/learning-paths': + target: _<learning_path_data_url>_ + changeOrigin: true + qsecure: true # <1> +---- +<1> Change to "false" in case of using self hosted cluster with a self-signed certificate diff --git a/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-hosted-json-files.adoc b/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-hosted-json-files.adoc new file mode 100644 index 0000000000..8fdc190bdb --- /dev/null +++ b/modules/customizing-the-learning-paths/proc-customizing-the-learning-paths-by-using-hosted-json-files.adoc @@ -0,0 +1,49 @@ +[id='proc-customizing-the-learning-paths-by-using-a-hosted-json-file_{context}'] += Customizing the Learning Paths by using a hosted JSON file + +For ease of use and simplicity, you can configure the Learning Paths by using a hosted JSON file. + +.Procedure +. Publish the JSON file containing your Learning Paths data to a web server, such as GitHub or Gitlab. You can find an example at link:https://raw.githubusercontent.com/redhat-developer/rhdh/release-{product-version}/packages/app/public/learning-paths/data.json[]. + +. Configure the {product-short} proxy to access the Learning Paths data from the hosted JSON file, by adding the following to the `{my-app-config-file}` file: ++ +[source,yaml,subs='+quotes'] +---- +proxy: + endpoints: + '/developer-hub': + target: _<target>_ + pathRewrite: + '^/api/proxy/developer-hub/learning-paths': '_<learning_path.json>_' + changeOrigin: true + secure: true +---- + +`_<target>_`:: Enter the hosted JSON file base URL, such as `https://raw.githubusercontent.com`. + +`_<learning_path.json>_`:: Enter the hosted JSON file path without the base URL, such as +`'/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json'` ++ +[TIP] +==== +When also configuring the home page, due to the use of overlapping `pathRewrites` for both the `learning-path` and `homepage` quick access proxies, create the `learning-paths` configuration (`^api/proxy/developer-hub/learning-paths`) before you create the `homepage` configuration (`^/api/proxy/developer-hub`). +For example: + +[source,yaml] +---- +proxy: + endpoints: + '/developer-hub': + target: https://raw.githubusercontent.com/ + pathRewrite: + '^/api/proxy/developer-hub/learning-paths': '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json' + '^/api/proxy/developer-hub/tech-radar': '/redhat-developer/rhdh/main/packages/app/public/tech-radar/data-default.json' + '^/api/proxy/developer-hub': '/redhat-developer/rhdh/main/packages/app/public/homepage/data.json' + changeOrigin: true + secure: true +---- +==== + +.Additional resources +* xref:customizing-the-home-page[Customizing the Home page in {product}]. diff --git a/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc b/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc index 60348bd630..4bc51b2fa5 100644 --- a/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc +++ b/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc @@ -6,7 +6,7 @@ [id="using-a-dedicated-service-to-provide-data-to-the-quick-access-card_{context}"] = Using a dedicated service to provide data to the Quick access card -When using a dedicated service, you can do the following: +When using a dedicated service, you can do the following tasks: * Use the same service to provide the data to all configurable {product-short} pages or use a different service for each page. * Use the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] as an example service, which provides data for both the Home and Tech Radar pages. The `red-hat-developer-hub-customization-provider` service provides the same data as default {product-short} data. You can fork the `red-hat-developer-hub-customization-provider` service repository from GitHub and modify it with your own data, if required. @@ -14,7 +14,7 @@ When using a dedicated service, you can do the following: .Prerequisites -* You have installed the {product} using Helm Chart. +* You have installed the {product} using Helm chart. For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp-helm[{installing-on-ocp-book-title} with the Helm chart]. .Procedure @@ -28,15 +28,15 @@ To use a separate service to provide the Home page data, complete the following To use the `red-hat-developer-hub-customization-provider` service, add the URL for the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[red-hat-developer-hub-customization-provider] repository or your fork of the repository containing your customizations. -- -. On the *General* tab, enter *red-hat-developer-hub-customization-provider* in the *Name* field and click *Create*. -. On the *Advanced Options* tab, copy the value from the *Target Port*. +. On the *General* tab, enter `red-hat-developer-hub-customization-provider` in the *Name* field and click *Create*. +. On the *Advanced Options* tab, copy the value from *Target Port*. + [NOTE] ==== -The *Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with. +*Target Port* automatically generates a Kubernetes or {ocp-short} service to communicate with. ==== + -. Add the following code to the `app-config-rhdh.yaml` file: +. Add the following code to the link:{configuring-book-url}[`{my-app-config-file}` file]: + [source,yaml] ---- @@ -45,16 +45,16 @@ proxy: # Other Proxies # customize developer hub instance '/developer-hub': - target: ${HOMEPAGE_DATA_URL} + target: ${HOMEPAGE_DATA_URL} <1> changeOrigin: true # Change to "false" in case of using self-hosted cluster with a self-signed certificate secure: true ---- -where `HOMEPAGE_DATA_URL` is defined as `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`. +<1> `pass:c[http://<SERVICE_NAME>:8080]`, for example, `pass:c[http://rhdh-customization-provider:8080]`. + [NOTE] ==== -The `red-hat-developer-hub-customization-provider` service contains the 8080 port by default. If you are using a custom port, you can specify it with the 'PORT' environmental variable in the `app-config-rhdh.yaml` file. +The `red-hat-developer-hub-customization-provider` service contains the 8080 port by default. If you are using a custom port, you can specify it with the 'PORT' environmental variable in the `{my-app-config-file}` file. ==== + . Replace the `HOMEPAGE_DATA_URL` by adding the URL to `rhdh-secrets` or by directly replacing it in your custom ConfigMap. @@ -62,11 +62,11 @@ The `red-hat-developer-hub-customization-provider` service contains the 8080 por . Delete the {product-short} pod to ensure that the new configurations are loaded correctly. .Verification -* To view the service, navigate to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*. +* To view the service, go to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*. + [NOTE] ==== -You can also view the *Service Resources* in the Topology view. +You can also view *Service Resources* in the Topology view. ==== * Ensure that the provided API URL for the Home page returns the data in JSON format as shown in the following example: @@ -109,16 +109,16 @@ You can also view the *Service Resources* in the Topology view. If the request call fails or is not configured, the {product-short} instance falls back to the default local data. ==== -* If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the content security policy’s (csp) `img-src` in your custom ConfigMap as follows: +* If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the content security policy (csp) `img-src` in your custom ConfigMap as shown in the following example: -[source,yaml] +[source,yaml,subs="attributes+"] ---- kind: ConfigMap apiVersion: v1 metadata: - name: app-config-rhdh + name: {my-app-config-file} data: - app-config-rhdh.yaml: | + {my-app-config-file}: | app: title: Red Hat Developer Hub backend: diff --git a/modules/customizing-the-quick-access-card/proc-using-hosted-json-files-to-provide-data-to-the-quick-access-card.adoc b/modules/customizing-the-quick-access-card/proc-using-hosted-json-files-to-provide-data-to-the-quick-access-card.adoc index 585c7f447f..214dfc02a1 100644 --- a/modules/customizing-the-quick-access-card/proc-using-hosted-json-files-to-provide-data-to-the-quick-access-card.adoc +++ b/modules/customizing-the-quick-access-card/proc-using-hosted-json-files-to-provide-data-to-the-quick-access-card.adoc @@ -13,9 +13,9 @@ See xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp[{installing-on-o .Procedure -* To access the data from the JSON files, add the following code to the {product-short} `app-config.yaml` configuration file: +* To access the data from the JSON files, add the following code to the `{my-app-config-file}` {product-short} configuration file: -* Add the following code to the `app-config.yaml` file: +* Add the following code to the `{my-app-config-file}` file: + [source,yaml] ---- diff --git a/modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc b/modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc deleted file mode 100644 index 7fccb0536d..0000000000 --- a/modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id='proc-customize-rhdh-tech-radar-page_{context}'] -= Customizing the Tech Radar page in {product} - -In {product}, the Tech Radar page is provided by the `tech-radar` dynamic plugin, which is disabled by default. For information about enabling dynamic plugins in {product} see link:{LinkPluginsGuide}[Configuring plugins in {product}]. - -In {product}, you can configure Learning Paths by passing the data into the `app-config.yaml` file as a proxy. The base Tech Radar URL must include the `/developer-hub/tech-radar` proxy. - -[NOTE] -==== -Due to the use of overlapping `pathRewrites` for both the `tech-radar` and `homepage` quick access proxies, you must create the `tech-radar` configuration (`^api/proxy/developer-hub/tech-radar`) before you create the `homepage` configuration (`^/api/proxy/developer-hub`). - -For more information about customizing the Home page in {product}, see xref:customizing-the-home-page[Customizing the Home page in {product}]. -==== - -You can provide data to the Tech Radar page from the following sources: - -* JSON files hosted on GitHub or GitLab. -* A dedicated service that provides the Tech Radar data in JSON format using an API. - -== Using hosted JSON files to provide data to the Tech Radar page - -.Prerequisites - -* You have installed {product} by using either the Operator or Helm chart. For more information, see link:{installing-on-ocp-book-url}[{installing-on-ocp-book-title}]. -* You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `app-config.yaml` file. For example, to configure GitHub as an integration, see link:{authentication-book-url}#authenticating-with-github[Authenticating with GitHub]. - -.Procedure - -To access the data from the JSON files, complete the following step: - -. Enable the `./dynamic-plugins/dist/backstage-community-plugin-tech-radar` and `/dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` plugins. -. Add the following code to the `app-config.yaml` file: -+ -[source,yaml] ----- -techRadar: - url: ${TECH_RADAR_DATA_URL} <1> ----- -<1> `TECH_RADAR_DATA_URL` is the URL from which the JSON data is loaded. - -== Using a dedicated service to provide data to the Tech Radar page - -When using a dedicated service, you can do the following: - -* Use the same service to provide the data to all configurable {product-short} pages or use a different service for each page. -* Use the https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] as an example service, which provides data for both the Home and Tech Radar pages. The `red-hat-developer-hub-customization-provider` service provides the same data as default {product-short} data. You can fork the `red-hat-developer-hub-customization-provider` service repository from GitHub and modify it with your own data, if required. -* Deploy the `red-hat-developer-hub-customization-provider` service and the {product-short} Helm chart on the same cluster. - -.Prerequisites - -* You have installed the {product} using Helm Chart. -For more information, see xref:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp-helm[{installing-on-ocp-book-title} with the Helm chart]. - -.Procedure - -To use a separate service to provide the Tech Radar data, complete the following steps: - -. Add the dedicated service as an allowed host by adding the following code to the `app-config.yaml` file: -+ -[source,yaml] ----- -backend: - reading: - allow: - - host: 'hostname' ----- -. Add the following to the `app-config.yaml` file: -+ -[source,yaml] ----- -techRadar: - url: ${TECH_RADAR_DATA_URL} <1> ----- -<1> `TECH_RADAR_DATA_URL` is the URL from which the JSON data is loaded. \ No newline at end of file diff --git a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc new file mode 100644 index 0000000000..bf1498043e --- /dev/null +++ b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc @@ -0,0 +1,37 @@ +[id='proc-customizing-rhdh-tech-radar-page-by-using-a-customization-service_{context}'] += Customizing the Tech Radar page by using a customization service + +For advanced scenarios, you can host your {product} customization service to provide data to all configurable {product-short} pages, such as the Tech Radar page. +You can even use a different service for each page. + +.Prerequisites +* You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `{my-app-config-file}` file. +For example, to configure GitHub as an integration, see link:{authentication-book-url}#authenticating-with-github[Authenticating with GitHub]. + +* You have enabled the `./dynamic-plugins/dist/backstage-community-plugin-tech-radar` and `/dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` plugins. + +.Procedure +. Deploy your {product-short} customization service on the same {ocp-short} cluster as your {product-short} instance. +You can find an example at link:https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`], that provides the same data as default {product-short} data. +The customization service provides a Tech Radar data URL such as: `pass:c,a,q[http://_<rhdh-customization-provider>_/tech-radar]`. + +. Add the dedicated service as an allowed host by adding the following code to the `{my-app-config-file}` file: ++ +[source,yaml,subs='+quotes'] +---- +backend: + reading: + allow: + - host: '_<rhdh_customization_provider_base_url>_' +---- +`_<rhdh_customization_provider_base_url>_`:: Enter the base URL of your Tech Radar data URL, such as: `pass:c,a,q[_<rhdh-customization-provider>_]`. + +. Add the following to the `{my-app-config-file}` file: ++ +[source,yaml,subs='+quotes'] +---- +techRadar: + url: _<tech_radar_data_url>_ +---- + +`_<tech_radar_data_url>_`:: Enter your Tech Radar data URL, such as: `pass:c,a,q[http://_<rhdh-customization-provider>_/tech-radar]`. diff --git a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc new file mode 100644 index 0000000000..697d3111b5 --- /dev/null +++ b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc @@ -0,0 +1,24 @@ +[id='proc-customizing-the-tech-radar-page-by-using-a-json-file_{context}'] += Customizing the Tech Radar page by using a JSON file + +For ease of use and simplicity, you can configure the Tech Radar page by using a hosted JSON file. + +.Prerequisites + +* You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `{my-app-config-file}` file. For example, to configure GitHub as an integration, see link:{authentication-book-url}#authenticating-with-github[Authenticating with GitHub]. + +* You have enabled the `./dynamic-plugins/dist/backstage-community-plugin-tech-radar` and `/dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` plugins. + +.Procedure + +. Publish the JSON file containing your Tech Radar data to a web server, such as GitHub or Gitlab. You can find an example at link:https://raw.githubusercontent.com/redhat-developer/rhdh/release-{product-version}/packages/app/public/tech-radar/data-default.json[]. + +. Configure {product-short} to access the Tech Radar data from the hosted JSON files, by adding the following to the `{my-app-config-file}` file: ++ +[source,yaml,subs='+quotes'] +---- +techRadar: + url: _<tech_radar_data_url>_ +---- + +`_<tech_radar_data_url>_`:: Enter the Tech Radar data hosted JSON URL. diff --git a/modules/customizing/proc-customizing-the-backend-secret.adoc b/modules/customizing/proc-customizing-the-backend-secret.adoc index 06ce1d3a62..1e82ace817 100644 --- a/modules/customizing/proc-customizing-the-backend-secret.adoc +++ b/modules/customizing/proc-customizing-the-backend-secret.adoc @@ -10,16 +10,15 @@ You can define your custom {product-short} backend secret. .Procedure -. To define the {product-short} backend secret, -add to your custom `{my-product-secrets}.txt` file the `BACKEND_SECRET` environment variable with a base64 encoded string. +. To define the {product-short} backend secret, add to your custom `_<my_product_secrets>_.txt` file the `BACKEND_SECRET` environment variable with a base64 encoded string. Use a unique value for each {product-short} instance. + -[source,terminal,subs="+attributes"] +[source,yaml,subs="+quotes,+attributes"] ---- -$ echo > {my-product-secrets}.txt "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')" +$ echo > `_<my_product_secrets>_.txt` "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')" ---- + -.`{my-product-secrets}.txt` example +.`_<my_product_secrets>_.txt` example ---- BACKEND_SECRET=3E2/rIPuZNFCtYHoxVP8wjriffnN1q/z ---- diff --git a/modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc b/modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc new file mode 100644 index 0000000000..d426eb1884 --- /dev/null +++ b/modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc @@ -0,0 +1,14 @@ += Search and filter the plugins + +== Search by plugin name +You can use the search bar in the header to filter the Extensions plugin cards by name. For example, if you type “A” into the search bar, Extensions shows only the plugins that contain the letter “A” in the Name field. + +image::rhdh-plugins-reference/dynatrace-certified-and-verified.png[Extensions catalog with a Dynatrace search] + +Optionally, you can use the search bar in conjunction with a filter to filter only plugins of the selected filter by name. For example, you can apply the *Category* filter and then type a character into the search bar to view only Openshift plugins that contain the typed character in the name. + +The following filters are available: + +* Category +* Author +* Support type \ No newline at end of file diff --git a/modules/dynamic-plugins/con-dynamic-plugins-cache.adoc b/modules/dynamic-plugins/con-dynamic-plugins-cache.adoc index 141d0819c5..c4b80167c5 100644 --- a/modules/dynamic-plugins/con-dynamic-plugins-cache.adoc +++ b/modules/dynamic-plugins/con-dynamic-plugins-cache.adoc @@ -13,10 +13,13 @@ When you enable dynamic plugins cache: == Enabling the dynamic plugins cache To enable the dynamic plugins cache in {product-very-short}, the plugins directory `dynamic-plugins-root` must be a persistent volume. -For Helm chart installations, a persistent volume named `dynamic-plugins-root` is automatically created. +=== Creating a PVC for the dynamic plugin cache by using the Operator -For operator-based installations, you must manually create the PersistentVolumeClaim (PVC) as follows: +For operator-based installations, you must manually create the persistent volume claim (PVC) by replacing the default `dynamic-plugins-root` volume with a PVC named `dynamic-plugins-root`. +.Procedure +. Create the persistent volume definition and save it to a file, such as `pvc.yaml`. For example: ++ [source,yaml] ---- kind: PersistentVolumeClaim @@ -30,9 +33,24 @@ spec: requests: storage: 5Gi ---- - -apiVersion: rhdh.redhat.com/v1alpha2 +---- ++ +[NOTE] +==== +This example uses `ReadWriteOnce` as the access mode which prevents multiple replicas from sharing the PVC across different nodes. +To run multiple replicas on different nodes, depending on your storage driver, you must use an access mode such as `ReadWriteMany`. +==== +. To apply this PVC to your cluster, run the following command: ++ +[source,terminal] +---- +oc apply -f pvc.yaml +---- +. Replace the default `dynamic-plugins-root` volume with a PVC named `dynamic-plugins-root`. For example: ++ +[source,yaml] +---- +apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: name: developer-hub @@ -48,21 +66,97 @@ spec: persistentVolumeClaim: claimName: dynamic-plugins-root ---- ++ +[NOTE] +To avoid adding a new volume, you must use the `$patch: replace` directive. +=== Creating a PVC for the dynamic plugin cache using the Helm Chart +For Helm chart installations, if you require the dynamic plugin cache to persist across pod restarts, you must create a persistent volume claim (PVC) and configure the Helm chart to use it. + +.Procedure +. Create the persistent volume definition. For example: ++ +[source,yaml] +---- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: dynamic-plugins-root +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +---- ++ [NOTE] ==== -Future versions of the {product-very-short} operator are planned to automatically create the PVC. +This example uses `ReadWriteOnce` as the access mode which prevents multiple replicas from sharing the PVC across different nodes. +To run multiple replicas on different nodes, depending on your storage driver, you must use an access mode such as `ReadWriteMany`. +==== + +. To apply this PVC to your cluster, run the following command: ++ +[source,terminal] +---- +oc apply -f pvc.yaml +---- +. Configure the Helm chart to use the PVC. For example: ++ +[source,yaml] +---- +upstream: + backstage: + extraVolumes: + - name: dynamic-plugins-root + persistentVolumeClaim: + claimName: dynamic-plugins-root + - name: dynamic-plugins + configMap: + defaultMode: 420 + name: '{{ printf "%s-dynamic-plugins" .Release.Name }}' + optional: true + - name: dynamic-plugins-npmrc + secret: + defaultMode: 420 + optional: true + secretName: '{{ printf "%s-dynamic-plugins-npmrc" .Release.Name }}' + - name: dynamic-plugins-registry-auth + secret: + defaultMode: 416 + optional: true + secretName: '{{ printf "%s-dynamic-plugins-registry-auth" .Release.Name }}' + - name: npmcacache + emptyDir: {} + - name: temp + emptyDir: {} +---- ++ +[NOTE] +==== +When you configure the Helm chart to use the PVC, you must also include the link:https://github.com/redhat-developer/rhdh-chart/blob/release-{product-version}/charts/backstage/values.yaml#L145-L181[`extraVolumes`] defined in the default Helm chart. ==== == Configuring the dynamic plugins cache -You can set the following optional dynamic plugin cache parameters: +You can set the following optional dynamic plugin cache parameters in your `dynamic-plugins.yaml` file: + +* `forceDownload`: Set the value to `true` to force a reinstall of the plugin, bypassing the cache. The default value is `false`. + +* `pullPolicy`: Similar to the `forceDownload` parameter and is consistent with other image container platforms. You can use one of the following values for this key: -* `forceDownload`: Set to `true` to force a reinstall of the plugin, bypassing the cache. Default is `false`. For example, modify your `dynamic-plugins.yaml` file as follows: +** `Always`: This value compares the image digest in the remote registry and downloads the artifact if it has changed, even if the plugin was previously downloaded. +** `IfNotPresent`: This value downloads the artifact if it is not already present in the dynamic-plugins-root folder, without checking image digests. + +[NOTE] +The `pullPolicy` setting is also applied to the NPM downloading method, although `Always` will download the remote artifact without a digest check. The existing `forceDownload` option remains functional, however, the `pullPolicy` option takes precedence. The `forceDownload` option may be deprecated in a future {product-short} release. + +.Example `dynamic-plugins.yaml` file configuration to download the remote artifact without a digest check: + [source,yaml] ---- plugins: - disabled: false - forceDownload: true + pullPolicy: Always package: 'oci://quay.io/example-org/example-plugin:v1.0.0!internal-backstage-plugin-example' ---- diff --git a/modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc b/modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc index 23d624207c..032ced1c8e 100644 --- a/modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc +++ b/modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc @@ -7,15 +7,25 @@ [id="con-install-dynamic-plugin-helm_{context}"] = Installing dynamic plugins using the Helm chart -You can deploy a {product-short} instance using a Helm chart, which is a flexible installation method. With the Helm chart, you can sideload dynamic plugins into your {product-short} instance without having to recompile your code or rebuild the container. +You can deploy a {product-short} instance by using a Helm chart, which is a flexible installation method. With the Helm chart, you can sideload dynamic plugins into your {product-short} instance without having to recompile your code or rebuild the container. To install dynamic plugins in {product-short} using Helm, add the following `global.dynamic` parameters in your Helm chart: * `plugins`: the dynamic plugins list intended for installation. By default, the list is empty. You can populate the plugins list with the following fields: ** `package`: a package specification for the dynamic plugin package that you want to install. You can use a package for either a local or an external dynamic plugin installation. For a local installation, use a path to the local folder containing the dynamic plugin. For an external installation, use a package specification from a public NPM repository. ** `integrity` (required for external packages): an integrity checksum in the form of `<alg>-<digest>` specific to the package. Supported algorithms include `sha256`, `sha384` and `sha512`. -** `pluginConfig`: an optional plugin-specific `app-config` YAML fragment. See plugin configuration for more information. +** `pluginConfig`: an optional plugin-specific `{my-app-config-file}` YAML fragment. See plugin configuration for more information. ** `disabled`: disables the dynamic plugin if set to `true`. Default: `false`. +** `forceDownload`: Set the value to `true` to force a reinstall of the plugin, bypassing the cache. The default value is `false`. + +** `pullPolicy`: Similar to the `forceDownload` parameter and is consistent with other image container platforms. You can use one of the following values for this key: + +*** `Always`: This value compares the image digest in the remote registry and downloads the artifact if it has changed, even if the plugin was previously downloaded. +*** `IfNotPresent`: This value downloads the artifact if it is not already present in the dynamic-plugins-root folder, without checking image digests. ++ +[NOTE] +The `pullPolicy` setting is also applied to the NPM downloading method, although `Always` will download the remote artifact without a digest check. The existing `forceDownload` option remains functional, however, the `pullPolicy` option takes precedence. The `forceDownload` option may be deprecated in a future {product-short} release. + * `includes`: a list of YAML files utilizing the same syntax. [NOTE] diff --git a/modules/dynamic-plugins/con-overriding-core-backend-services.adoc b/modules/dynamic-plugins/con-overriding-core-backend-services.adoc deleted file mode 100644 index 233c801d28..0000000000 --- a/modules/dynamic-plugins/con-overriding-core-backend-services.adoc +++ /dev/null @@ -1,101 +0,0 @@ -[id="overriding-core-backend-services_{context}"] -= Overriding Core Backend Service Configuration - -The {product} ({product-very-short}) backend platform consists of a number of core services that are well encapsulated. The {product-very-short} backend installs these default core services statically during initialization. - -You can configure these core services by customizing the backend source code and rebuilding your {product-short} application. Alternatively, you can customize a core service by installing it as a `BackendFeature` by using dynamic plugin functionality. - -To use the dynamic plugin functionality to customize a core service in your RHDH application, you must configure the backend to avoid statically installing a given default core service. - -For example, adding a middleware function to handle all incoming requests can be done by installing a custom `configure` function for the root `HTTP` router backend service which allows access to the underlying Express application. - -.Example of a `BackendFeature` middleware function to handle incoming `HTTP` requests - -[source,javascript] ----- -// Create the BackendFeature -export const customRootHttpServerFactory: BackendFeature = - rootHttpRouterServiceFactory({ - configure: ({ app, routes, middleware, logger }) => { - logger.info( - 'Using custom root HttpRouterServiceFactory configure function', - ); - app.use(middleware.helmet()); - app.use(middleware.cors()); - app.use(middleware.compression()); - app.use(middleware.logging()); - // Add a the custom middleware function before all - // of the route handlers - app.use(addTestHeaderMiddleware({ logger })); - app.use(routes); - app.use(middleware.notFound()); - app.use(middleware.error()); - }, - }); - -// Export the BackendFeature as the default entrypoint -export default customRootHttpServerFactory; ----- - -In the above example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. - -== Overriding environment variables -To allow a dynamic plugin to load a core service override, you must start the {product-short} backend with the corresponding core service ID environment variable set to `true`. - -.Environment variables and core service IDs -[cols="50%,50%", frame="all", options="header"] -|=== -|Variable -|Description - -|`ENABLE_CORE_AUTH_OVERRIDE` -|Override the `core.auth` service - -| `ENABLE_CORE_CACHE_OVERRIDE` -| Override the `core.cache` service - -| `ENABLE_CORE_ROOTCONFIG_OVERRIDE` -| Override the `core.rootConfig` service - -| `ENABLE_CORE_DATABASE_OVERRIDE` -| Override the `core.database` service - -| `ENABLE_CORE_DISCOVERY_OVERRIDE` -| Override the `core.discovery` service - -| `ENABLE_CORE_HTTPAUTH_OVERRIDE` -| Override the `core.httpAuth` service - -| `ENABLE_CORE_HTTPROUTER_OVERRIDE` -| Override the `core.httpRouter` service - -| `ENABLE_CORE_LIFECYCLE_OVERRIDE` -| Override the `core.lifecycle` service - -| `ENABLE_CORE_LOGGER_OVERRIDE` -| Override the `core.logger` service - -| `ENABLE_CORE_PERMISSIONS_OVERRIDE` -| Override the `core.permissions` service - -| `ENABLE_CORE_ROOTHEALTH_OVERRIDE` -| Override the `core.rootHealth` service - -| `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` -| Override the `core.rootHttpRouter` service - -| `ENABLE_CORE_ROOTLIFECYCLE_OVERRIDE` -| Override the `core.rootLifecycle` service - -| `ENABLE_CORE_SCHEDULER_OVERRIDE` -| Override the `core.scheduler` service - -| `ENABLE_CORE_USERINFO_OVERRIDE` -| Override the `core.userInfo` service - -| `ENABLE_CORE_URLREADER_OVERRIDE` -| Override the `core.urlReader` service - -| `ENABLE_EVENTS_SERVICE_OVERRIDE` -| Override the `events.service` service -|=== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-preinstalled-dynamic-plugins.adoc b/modules/dynamic-plugins/con-preinstalled-dynamic-plugins.adoc index af663e3359..e26dad13aa 100644 --- a/modules/dynamic-plugins/con-preinstalled-dynamic-plugins.adoc +++ b/modules/dynamic-plugins/con-preinstalled-dynamic-plugins.adoc @@ -11,8 +11,10 @@ The following preinstalled dynamic plugins are enabled by default: * `@backstage-community/plugin-scaffolder-backend-module-quay` * `@backstage-community/plugin-scaffolder-backend-module-regex` * `@backstage/plugin-techdocs-backend` +* `@backstage/plugin-techdocs-module-addons-contrib` * `@backstage/plugin-techdocs` * `@red-hat-developer-hub/backstage-plugin-dynamic-home-page` +* `@red-hat-developer-hub/backstage-plugin-global-header` The dynamic plugins that require custom configuration are disabled by default. diff --git a/modules/dynamic-plugins/proc-app-grouping.adoc b/modules/dynamic-plugins/proc-app-grouping.adoc new file mode 100644 index 0000000000..89d7bccb05 --- /dev/null +++ b/modules/dynamic-plugins/proc-app-grouping.adoc @@ -0,0 +1,11 @@ +[id="proc-app-grouping"] + += App grouping + +To display workload resources such as deployments or pods in a visual group, add the following label: + +[source,yaml] +---- +labels: + app.kubernetes.io/part-of: <GROUP_NAME> +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-catalog-viewing.adoc b/modules/dynamic-plugins/proc-catalog-viewing.adoc new file mode 100644 index 0000000000..ee22c1fc14 --- /dev/null +++ b/modules/dynamic-plugins/proc-catalog-viewing.adoc @@ -0,0 +1,11 @@ +[id="rhdh-extensions-plugins-viewing_{context}"] += Viewing available plugins + +You can view plugins available for your {product} application on the *Extensions* page. + +.Procedure + +. Open your {product-short} application and click *Administration* > *Extensions*. +. Go to the *Catalog* tab to view a list of available plugins and related information. ++ +image::rhdh-plugins-reference/extensions-catalog.png[Extensions Catalog] \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc b/modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc index d2cfd3dbfb..37771195ac 100644 --- a/modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc +++ b/modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc @@ -10,7 +10,7 @@ You can store the configuration for dynamic plugins in a `ConfigMap` object that [NOTE] ==== -If the `pluginConfig` field references environment variables, you must define the variables in your `my-rhdh-secrets` secret. +If the `pluginConfig` field references environment variables, you must define the variables in your `_<my_product_secrets>_` secret. ==== .Procedure diff --git a/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc index 464316c93d..31d4633a93 100644 --- a/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc +++ b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc @@ -48,7 +48,7 @@ npm pack --pack-destination ~/test/dynamic-plugins-root/ To create a plugin registry using HTTP server on {ocp-short}, run the following commands: .Example commands to build and deploy an HTTP server in {ocp-short} -[source,terminal] +[source,terminal, subs="+attributes"] ---- oc project {my-product-namespace} oc new-build httpd --name=plugin-registry --binary diff --git a/modules/dynamic-plugins/proc-enable-plugins-rhdh-container-image.adoc b/modules/dynamic-plugins/proc-enable-plugins-rhdh-container-image.adoc new file mode 100644 index 0000000000..abc8d270bd --- /dev/null +++ b/modules/dynamic-plugins/proc-enable-plugins-rhdh-container-image.adoc @@ -0,0 +1,36 @@ +[id="proc-enable-plugins-rhdh-container-image_{context}"] += Enabling plugins added in the {product-very-short} container image + +In the {product-very-short} container image, a set of dynamic plugins is preloaded to enhance functionality. However, due to mandatory configuration requirements, most of the plugins are disabled. + +You can enable and configure the plugins in the {product-very-short} container image, including how to manage the default configuration, set necessary environment variables, and ensure the proper functionality of the plugins within your application. + +.Prerequisites +* You have access to the link:https://github.com/janus-idp/backstage-showcase/blob/main/dynamic-plugins.default.yaml[`dynamic-plugins.default.yaml`] file, which lists all preloaded plugins and their default configuration. +* You have deployed the {product-very-short} application, and have access to the logs of the `install-dynamic-plugins` init container. +* You have the necessary permissions to modify plugin configurations and access the application environment. +* You have identified and set the required environment variables referenced by the plugin's default configuration. These environment variables must be defined in the Helm Chart or Operator configuration. + +.Procedure +. Start your {product-very-short} application and access the logs of the `install-dynamic-plugins` init container within the {product-very-short} pod. +. Identify the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/dynamic_plugins_reference/index#red-hat-supported-plugins[Red Hat supported plugins] that are disabled by default. +. Copy the package configuration from the link:https://github.com/janus-idp/backstage-showcase/blob/main/dynamic-plugins.default.yaml[`dynamic-plugins.default.yaml`] file. +. Open the plugin configuration file and locate the plugin entry you want to enable. ++ +The location of the plugin configuration file varies based on the deployment method. For more details, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index#proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[Installing dynamic plugins with the {product} Operator] and link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index#con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart]. +. Modify the `disabled` field to `false` and add the package name as follows: ++ +-- +.Example plugin configuration +[source,yaml] +---- +plugins: + - disabled: false + package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic +---- +For more information about how to configure dynamic plugins in {product-short}, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about[Installing dynamic plugins in {product}]. +-- + +.Verification +. Restart the {product-very-short} application and verify that the plugin is successfully activated and configured. +. Verify the application logs for confirmation and ensure the plugin is functioning as expected. diff --git a/modules/dynamic-plugins/proc-enable-users-to-use-topology-plugin.adoc b/modules/dynamic-plugins/proc-enable-users-to-use-topology-plugin.adoc new file mode 100644 index 0000000000..16f26783f3 --- /dev/null +++ b/modules/dynamic-plugins/proc-enable-users-to-use-topology-plugin.adoc @@ -0,0 +1,26 @@ +[id="enable-users-to-use-the-topology-plugin"] += Enable users to use the Topology plugin + +The Topology plugin is defining additional permissions. When link:{authorization-book-url}[{authorization-book-title}] is enabled, to enable users to use the Topology plugin, grant them: + +* The `kubernetes.clusters.read` and `kubernetes.resources.read`, `read` permissions to view the Topology panel. +* The `kubernetes.proxy` `use` permission to view the pod logs. +* The `catalog-entity` `read` permission to view the {product} software catalog items. + +.Prerequisites +* You are link:{authorization-book-url}#managing-authorizations-by-using-external-files[managing {authorization-book-title} by using external files]. + +.Procedure +* Add the following permission policies to your `rbac-policy.csv` file to create a `topology-viewer` role that has access to the Topology plugin features, and add the role to the users requiring this authorization: ++ +[source] +---- +g, user:default/<YOUR_USERNAME>, role:default/topology-viewer +p, role:default/topology-viewer, kubernetes.clusters.read, read, allow <1> +p, role:default/topology-viewer, kubernetes.resources.read, read, allow <1> +p, role:default/topology-viewer, kubernetes.proxy, use, allow <2> +p, role:default/topology-viewer, catalog-entity, read, allow <3> +---- +<1> Grants the user the ability to see the Topology panel. +<2> Grants the user the ability to view the pod logs. +<3> Grants the user the ability to see the catalog item. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc b/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc new file mode 100644 index 0000000000..6b85f376c5 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc @@ -0,0 +1,34 @@ +[id="proc-enabling-the-source-code-editor_{context}"] += Enabling the source code editor + +To enable the source code editor, you must grant read access to the CheClusters resource in the `ClusterRole` as shown in the following example code: + +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - org.eclipse.che + resources: + - checlusters + verbs: + - get + - list +---- + +To use the source code editor, you must add the following configuration to the `kubernetes.customResources` property in your `{my-app-config-file}` file: + +[source,yaml] +---- + kubernetes: + ... + customResources: + - group: 'org.eclipse.che' + apiVersion: 'v2' + plural: 'checlusters' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc new file mode 100644 index 0000000000..76776a84c6 --- /dev/null +++ b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc @@ -0,0 +1,24 @@ +[id="proc-entity-annotation-or-label"] + += Entity annotation/label + +For {product-very-short} to detect that an entity has Kubernetes components, add the following annotation to the `catalog-info.yaml` file of the entity: + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME> +---- + +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: <BACKSTAGE_ENTITY_NAME>` +---- + +[NOTE] +==== +When using the label selector, the mentioned labels must be present on the resource. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index 7fc47fd9a0..3fc63b7446 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -57,12 +57,12 @@ npx @janus-idp/cli@latest export-dynamic The following is an example of default `scalprum` configuration: + .Default `scalprum` configuration -[source,json] +[source,json,subs="+attributes"] ---- "scalprum": { "name": "<package_name>", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed. "exposedModules": { - "PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file. + "PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the {my-app-config-file} file. } } ---- diff --git a/modules/dynamic-plugins/proc-extensions-creating.adoc b/modules/dynamic-plugins/proc-extensions-creating.adoc new file mode 100644 index 0000000000..2b34bb80eb --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-creating.adoc @@ -0,0 +1,128 @@ +[id="rhdh-extensions-plugins-creating_{context}"] += Adding your own plugin metadata to Extensions +You can add your own plugin metadata to Extensions. + +.Prequisites + +.Procedure +. Update plugin metadata file, as follows: ++ +[source,yaml] +---- +# yaml-language-server: $schema=https://raw.githubusercontent.com/redhat-developer/rhdh-plugins/refs/heads/main/workspaces/marketplace/json-schema/plugins.json +apiVersion: extensions.backstage.io/v1alpha1 +kind: Plugin +metadata: + name: github-issues + namespace: rhdh + title: GitHub Issues + description: 'Based on the well-known GitHub slug annotation associated with the Entity, it renders the list of Open issues in GitHub' + annotations: + extensions.backstage.io/pre-installed: 'true' + tags: + - issue-tracker + links: + - title: Homepage + url: https://red.ht/rhdh + - title: Bugs + url: https://issues.redhat.com/browse/RHIDP + - title: Documentation for Red Hat Developer Hub + url: https://docs.redhat.com/en/documentation/red_hat_developer_hub + - title: Source Code + url: https://github.com/backstage/community-plugins/tree/main/workspaces/github-issues/plugins/github-issues +spec: + categories: + - Issue tracker + + icon: data:image/svg+xml;base64, + PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjgg + MTI4Ij48ZyBmaWxsPSIjMTgxNjE2Ij48cGF0aCBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcnVs + ZT0iZXZlbm9kZCIgZD0iTTY0IDUuMTAzYy0zMy4zNDcgMC02MC4zODggMjcuMDM1LTYwLjM4OCA2 + MC4zODggMCAyNi42ODIgMTcuMzAzIDQ5LjMxNyA0MS4yOTcgNTcuMzAzIDMuMDE3LjU2IDQuMTI1 + LTEuMzEgNC4xMjUtMi45MDUgMC0xLjQ0LS4wNTYtNi4xOTctLjA4Mi0xMS4yNDMtMTYuOCAzLjY1 + My0yMC4zNDUtNy4xMjUtMjAuMzQ1LTcuMTI1LTIuNzQ3LTYuOTgtNi43MDUtOC44MzYtNi43MDUt + OC44MzYtNS40OC0zLjc0OC40MTMtMy42Ny40MTMtMy42NyA2LjA2My40MjUgOS4yNTcgNi4yMjMg + OS4yNTcgNi4yMjMgNS4zODYgOS4yMyAxNC4xMjcgNi41NjIgMTcuNTczIDUuMDIuNTQyLTMuOTAz + IDIuMTA3LTYuNTY4IDMuODM0LTguMDc2LTEzLjQxMy0xLjUyNS0yNy41MTQtNi43MDQtMjcuNTE0 + LTI5Ljg0MyAwLTYuNTkzIDIuMzYtMTEuOTggNi4yMjMtMTYuMjEtLjYyOC0xLjUyLTIuNjk1LTcu + NjYyLjU4NC0xNS45OCAwIDAgNS4wNy0xLjYyMyAxNi42MSA2LjE5QzUzLjcgMzUgNTguODY3IDM0 + LjMyNyA2NCAzNC4zMDRjNS4xMy4wMjMgMTAuMy42OTQgMTUuMTI3IDIuMDMzIDExLjUyNi03Ljgx + MyAxNi41OS02LjE5IDE2LjU5LTYuMTkgMy4yODcgOC4zMTcgMS4yMiAxNC40Ni41OTMgMTUuOTgg + My44NzIgNC4yMyA2LjIxNSA5LjYxNyA2LjIxNSAxNi4yMSAwIDIzLjE5NC0xNC4xMjcgMjguMy0y + Ny41NzQgMjkuNzk2IDIuMTY3IDEuODc0IDQuMDk3IDUuNTUgNC4wOTcgMTEuMTgzIDAgOC4wOC0u + MDcgMTQuNTgzLS4wNyAxNi41NzIgMCAxLjYwNyAxLjA4OCAzLjQ5IDQuMTQ4IDIuODk3IDIzLjk4 + LTcuOTk0IDQxLjI2My0zMC42MjIgNDEuMjYzLTU3LjI5NEMxMjQuMzg4IDMyLjE0IDk3LjM1IDUu + MTA0IDY0IDUuMTA0eiIvPjxwYXRoIGQ9Ik0yNi40ODQgOTEuODA2Yy0uMTMzLjMtLjYwNS4zOS0x + LjAzNS4xODUtLjQ0LS4xOTYtLjY4NS0uNjA1LS41NDMtLjkwNi4xMy0uMzEuNjAzLS4zOTUgMS4w + NC0uMTg4LjQ0LjE5Ny42OS42MS41MzcuOTF6bTIuNDQ2IDIuNzI5Yy0uMjg3LjI2Ny0uODUuMTQz + LTEuMjMyLS4yOC0uMzk2LS40Mi0uNDctLjk4My0uMTc3LTEuMjU0LjI5OC0uMjY2Ljg0NC0uMTQg + MS4yNC4yOC4zOTQuNDI2LjQ3Mi45ODQuMTcgMS4yNTV6TTMxLjMxMiA5OC4wMTJjLS4zNy4yNTgt + Ljk3Ni4wMTctMS4zNS0uNTItLjM3LS41MzgtLjM3LTEuMTgzLjAxLTEuNDQuMzczLS4yNTguOTct + LjAyNSAxLjM1LjUwNy4zNjguNTQ1LjM2OCAxLjE5LS4wMSAxLjQ1MnptMy4yNjEgMy4zNjFjLS4z + My4zNjUtMS4wMzYuMjY3LTEuNTUyLS4yMy0uNTI3LS40ODctLjY3NC0xLjE4LS4zNDMtMS41NDQu + MzM2LS4zNjYgMS4wNDUtLjI2NCAxLjU2NC4yMy41MjcuNDg2LjY4NiAxLjE4LjMzMyAxLjU0M3pt + NC41IDEuOTUxYy0uMTQ3LjQ3My0uODI1LjY4OC0xLjUxLjQ4Ni0uNjgzLS4yMDctMS4xMy0uNzYt + Ljk5LTEuMjM4LjE0LS40NzcuODIzLS43IDEuNTEyLS40ODUuNjgzLjIwNiAxLjEzLjc1Ni45ODgg + MS4yMzd6bTQuOTQzLjM2MWMuMDE3LjQ5OC0uNTYzLjkxLTEuMjguOTItLjcyMy4wMTctMS4zMDgt + LjM4Ny0xLjMxNS0uODc3IDAtLjUwMy41NjgtLjkxIDEuMjktLjkyNC43MTctLjAxMyAxLjMwNi4z + ODcgMS4zMDYuODh6bTQuNTk4LS43ODJjLjA4Ni40ODUtLjQxMy45ODQtMS4xMjYgMS4xMTctLjcu + MTMtMS4zNS0uMTcyLTEuNDQtLjY1My0uMDg2LS40OTguNDIyLS45OTcgMS4xMjItMS4xMjYuNzE0 + LS4xMjMgMS4zNTQuMTcgMS40NDQuNjYzem0wIDAiLz48L2c+PC9zdmc+ + + + author: Backstage Community + support: tech-preview # production, tech-preview, dev-preveiw + lifecycle: active + publisher: Red Hat + highlights: + - Show GitHub issues for your entities + + description: | + + Based on the [well-known GitHub slug annotation](https://backstage.io/docs/features/software-catalog/well-known-annotations#githubcomproject-slug) associated with the Entity, it renders the list of Open issues in GitHub. + The plugin will attempt to determine the source code location using the [well-known Source location slug annotation](https://backstage.io/docs/features/software-catalog/well-known-annotations/#backstageiosource-location) or [Managed by location slug annotation](https://backstage.io/docs/features/software-catalog/well-known-annotations/#backstageiomanaged-by-location) associated with the Entity. + If no configured Github provider will match, the first one will be used. + + The plugin is designed to work with four Entity kinds, and it behaves a bit differently depending on that kind: + + - Kind: Group/User: plugin renders issues from all repositories for which the Entity is the owner. + - Kind: API/Component: plugin renders issues from only one repository assigned to the Entity + + **Issues are sorted from the recently updated DESC order (the plugin might not render all issues from a single repo next to each other).** + + ## Adding The Plugin To Red Hat Developer Hub + + See the [Red Hat Developer Hub documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub) + for further instructions on how to add, enable, configure, and remove plugins in your instance. + + ## Configuring The Plugin ## + + Plugins often need additional configuration to work correctly - particularly those that integrate with other + systems. See the original source code repository, the software vendor, or the [Red Hat Developer Hub documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub) + for further details regarding the configuration required. + + packages: + - backstage-community-plugin-github-issues +---- + +.User facing attributes +[%header,cols=3*] +|=== +|*Attribute* |*Type* |*Description* +// |3scale |`https://npmjs.com/package/@backstage-community/plugin-3scale-backend/v/3.0.3[@backstage-community/plugin-3scale-backend]` |3.0.3 +// |`./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic` + +// `THREESCALE_BASE_URL` + +// `THREESCALE_ACCESS_TOKEN` + + + +| `metadata.description` | `string` | Short description that is shown on the cards (text). +| `spec.author` | `string` | A single author name, this attribute is automatically converted to authors if specified. +| `spec.authors` | `{ name: string, url?: string }[]` | Authors array if a plugin is developed by multiple authors. +| `spec.categories` | `string[]` | Categories are displayed directly as filter and labels. +| `spec.highlights` | `string[]` | Highlights for the details page. +| `spec.description` | `string` | Full description that is shown on the details page (markdown). +| `spec.installation` | `string` | Full installation description that is shown later on the install page (markdown). +| `spec.icon` | `string` | Icon URL \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-extensions-disabling.adoc b/modules/dynamic-plugins/proc-extensions-disabling.adoc new file mode 100644 index 0000000000..fc0361e0df --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-disabling.adoc @@ -0,0 +1,21 @@ +[id="rhdh-extensions-plugins-disabling_{context}"] += Removing Extensions +The Extensions feature plugins are preinstalled in {product} ({product-very-short}) and enabled by default. If you want to remove Extensions from your {product-very-short} instance, you can disable the relevant plugins. + +.Procedure +. To disable the the Extensions feature plugins, edit your `dynamic-plugins.yaml` with the following content. ++ +.`dynamic-plugins.yaml` fragment +[source,yaml] +---- +plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace + disabled: true + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic + disabled: true + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic + disabled: true +---- + +[NOTE] +If you disable the Extensions feature plugins, the *Catalog* and *Installed* tabs will also be removed. You can still view installed plugins by clicking on *Administration* > *Extensions*. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-extensions-managing.adoc b/modules/dynamic-plugins/proc-extensions-managing.adoc new file mode 100644 index 0000000000..61485e53fe --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-managing.adoc @@ -0,0 +1,27 @@ +[id="rhdh-extensions-plugins-managing_{context}"] += Managing Extensions plugin metadata in {product} + +You must add the Extensions catalog entities to your {product-very-short} container image by updating your `app-config.yaml` file, + +.Prerequisites +* You have installed the `marketplace` plugin. + +.Procedure +. Update the `catalog.locations` definition in your `app-config.yaml` file, as follows: ++ +[source,yaml] +---- +appConfig: + catalog: + rules: + - allow: [Component, System, API, Resource, Location, PluginCollection, Plugin, Package] + locations: + - type: file + target: /marketplace/catalog-entities/plugins/all.yaml + rules: + - allow: [Location, Plugin] + - type: file + target: /marketplace/catalog-entities/packages/all.yaml + rules: + - allow: [Location, Package] +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc b/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc new file mode 100644 index 0000000000..a81c526f1b --- /dev/null +++ b/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc @@ -0,0 +1,52 @@ +[id="proc-icon-displayed-in-the-node"] + += Icon displayed in the node + +To display a runtime icon in the topology nodes, add the following label to workload resources, such as Deployments: + +[source,yaml] +---- +labels: + app.openshift.io/runtime: <RUNTIME_NAME> +---- +Alternatively, you can include the following label to display the runtime icon: + +[source,yaml] +---- +labels: + app.kubernetes.io/name: <RUNTIME_NAME> +---- + +Supported values of `<RUNTIME_NAME>` include: + +* django +* dotnet +* drupal +* go-gopher +* golang +* grails +* jboss +* jruby +* js +* nginx +* nodejs +* openjdk +* perl +* phalcon +* php +* python +* quarkus +* rails +* redis +* rh-spring-boot +* rust +* java +* rh-openjdk +* ruby +* spring +* spring-boot + +[NOTE] +==== +Other values result in icons not being rendered for the node. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc b/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc index f09e8dc015..06119b4da9 100644 --- a/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc +++ b/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc @@ -5,16 +5,16 @@ You can install external plugins in an air-gapped environment by setting up a custom NPM registry. -You can configure the NPM registry URL and authentication information for dynamic plugin packages using a Helm chart. For dynamic plugin packages obtained through `npm pack`, you can use a `.npmrc` file. +You can configure the NPM registry URL and authentication information for dynamic plugin packages using a Helm chart. For dynamic plugin packages obtained through `npm pack`, you can use a `.npmrc` file. -Using the Helm chart, add the `.npmrc` file to the NPM registry by creating a secret named `dynamic-plugins-npmrc` with the following content: +Using the Helm chart, add the `.npmrc` file to the NPM registry by creating a secret. For example: -[source,yaml] +[source,yaml,subs="+quotes,+attributes"] ---- apiVersion: v1 kind: Secret metadata: - name: dynamic-plugins-npmrc + name: `_<release_name>_-dynamic-plugins-npmrc` # <1> type: Opaque stringData: .npmrc: | @@ -22,3 +22,4 @@ stringData: //<registry-url>:_authToken=<auth-token> ... ---- +<1> Replace `_<release_name>_` with your Helm release name. This name is a unique identifier for each chart installation in the Kubernetes cluster. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-installing-and-configuring-redis-cache.adoc b/modules/dynamic-plugins/proc-installing-and-configuring-redis-cache.adoc index 57f6f79442..d92ddc0459 100644 --- a/modules/dynamic-plugins/proc-installing-and-configuring-redis-cache.adoc +++ b/modules/dynamic-plugins/proc-installing-and-configuring-redis-cache.adoc @@ -1,9 +1,7 @@ [id="proc-installing-and-configuring-redis-cache_{context}"] -= Using Redis Cache with dynamic plugins += Configuring the Redis cache for dynamic plugins in {product}. You can use the Redis cache store to improve {product-very-short} performance and reliability. Plugins in {product-very-short} receive dedicated cache connections, which are powered by Keyv. -== Installing Redis Cache in {product} - .Prerequisites * You have installed Red Hat Developer Hub by using either the Operator or Helm chart. * You have an active Redis server. For more information on setting up an external Redis server, see the link:https://www.redis.io/docs/latest/[`Redis official documentation`]. diff --git a/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc new file mode 100644 index 0000000000..3c36157df2 --- /dev/null +++ b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc @@ -0,0 +1,31 @@ +[id="proc-label-selector-query-annotation"] + += Label selector query annotation + +You can write your own custom label, 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' +---- + +If you have multiple entities while Red Hat Dev Spaces is configured and want multiple entities to support the edit code decorator that redirects to the Red Hat Dev Spaces instance, you can add the backstage.io/kubernetes-label-selector annotation to the catalog-info.yaml file for each entity. + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-label-selector: 'component in (<BACKSTAGE_ENTITY_NAME>,che)' +---- + +If you are using the previous label selector, you must add the following labels to your resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: + +[source,yaml] +---- +labels: + component: che # add this label to your che cluster instance +labels: + component: <BACKSTAGE_ENTITY_NAME> # add this label to the other resources associated with your entity +---- + +You can also write your own custom query for the label selector with unique labels to differentiate your entities. However, you need to ensure that you add those labels to the resources associated with your entities including your CheCluster instance. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc new file mode 100644 index 0000000000..417e1af3d8 --- /dev/null +++ b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc @@ -0,0 +1,33 @@ +[id="proc-linking-to-source-code-editor-or-source"] + += Linking to the source code editor or the source + +Add the following annotations to workload resources, such as Deployments to navigate to the Git repository of the associated application using the source code editor: + +[source,yaml] +---- +annotations: + app.openshift.io/vcs-uri: <GIT_REPO_URL> +---- + +Add the following annotation to navigate to a specific branch: + +[source,yaml] +---- +annotations: + app.openshift.io/vcs-ref: <GIT_REPO_BRANCH> +---- + +[NOTE] +==== +If Red Hat OpenShift Dev Spaces is installed and configured and Git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. +==== + +[NOTE] +==== +When you deploy your application using the OCP Git import flows, then you do not need to add the labels as import flows do that. Otherwise, you need to add the labels manually to the workload YAML file. +==== + +//The labels are not similar to `backstage.io/edit-url` annotations as it points to the catalog entity metadata source file and is applied to RHDH catalog entity metadata YAML file, but not Kubernetes resources. + +You can also add the `app.openshift.io/edit-url` annotation with the edit URL that you want to access using the decorator. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-load-plugin-js-package.adoc b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc index 9412336da8..7c04817174 100644 --- a/modules/dynamic-plugins/proc-load-plugin-js-package.adoc +++ b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc @@ -43,25 +43,26 @@ registry=<registry-url> . When using {ocp-short} or Kubernetes: + -- -* Create a secret with the `.npmrc` content as follows: +* Use the Helm chart to add the `.npmrc` file by creating a secret. For example: + .Example secret configuration -[source,yaml] +[source,yaml,subs="+quotes,+attributes"] ---- apiVersion: v1 kind: Secret metadata: - name: dynamic-plugins-npmrc + name: `_<release_name>_-dynamic-plugins-npmrc` # <1> type: Opaque stringData: .npmrc: | registry=<registry-url> //<registry-url>:_authToken=<auth-token> ---- +<1> Replace `_<release_name>_` with your Helm release name. This name is a unique identifier for each chart installation in the Kubernetes cluster. * For {product-very-short} Helm chart, name the secret using the following format for automatic mounting: + -`<release-name>-dynamic-plugins-npmrc` +`_<release_name>_-dynamic-plugins-npmrc` -- . To apply the changes, restart the {product-very-short} application. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-namespace-annotation.adoc b/modules/dynamic-plugins/proc-namespace-annotation.adoc new file mode 100644 index 0000000000..22d296db83 --- /dev/null +++ b/modules/dynamic-plugins/proc-namespace-annotation.adoc @@ -0,0 +1,16 @@ +[id="proc-namespace-annotation"] + += Namespace annotation + +.Procedure +* To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: ++ +[source,yaml] +---- +annotations: + backstage.io/kubernetes-namespace: <RESOURCE_NS> +---- ++ +The Red Hat OpenShift Dev Spaces instance is not accessible using the source code editor if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file. ++ +To retrieve the instance URL, you require the CheCluster custom resource (CR). As the CheCluster CR is created in the openshift-devspaces namespace, the instance URL is not retrieved if the namespace annotation value is not openshift-devspaces. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-node-connector.adoc b/modules/dynamic-plugins/proc-node-connector.adoc new file mode 100644 index 0000000000..961857e174 --- /dev/null +++ b/modules/dynamic-plugins/proc-node-connector.adoc @@ -0,0 +1,12 @@ +[id="proc-node-connector"] + += Node connector + +.Procedure +To display the workload resources such as deployments or pods with a visual connector, add the following annotation: ++ +[source,yaml] +---- +annotations: + app.openshift.io/connects-to: '[{"apiVersion": <RESOURCE_APIVERSION>,"kind": <RESOURCE_KIND>,"name": <RESOURCE_NAME>}]' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc new file mode 100644 index 0000000000..37da22ea01 --- /dev/null +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -0,0 +1,100 @@ +[id="overriding-core-backend-services_{context}"] += Overriding Core Backend Service Configuration + +The {product} ({product-very-short}) backend platform consists of a number of core services that are well encapsulated. +The {product-very-short} backend installs these default core services statically during initialization. + +Customize a core service by installing it as a `BackendFeature` by using the dynamic plugin functionality. + +.Procedure +. Configure {product-short} to allow a core service override, by setting the corresponding core service ID environment variable to `true` in the {product-short} `{my-app-config-file}` configuration file. ++ +.Environment variables and core service IDs +[cols="50%,50%",frame="all",options="header"] +|=== +|Variable +|Overrides the related service + +|`ENABLE_CORE_AUTH_OVERRIDE` +|`core.auth` + +| `ENABLE_CORE_CACHE_OVERRIDE` +| `core.cache` + +| `ENABLE_CORE_ROOTCONFIG_OVERRIDE` +| `core.rootConfig` + +| `ENABLE_CORE_DATABASE_OVERRIDE` +| `core.database` + +| `ENABLE_CORE_DISCOVERY_OVERRIDE` +| `core.discovery` + +| `ENABLE_CORE_HTTPAUTH_OVERRIDE` +| `core.httpAuth` + +| `ENABLE_CORE_HTTPROUTER_OVERRIDE` +| `core.httpRouter` + +| `ENABLE_CORE_LIFECYCLE_OVERRIDE` +| `core.lifecycle` + +| `ENABLE_CORE_LOGGER_OVERRIDE` +| `core.logger` + +| `ENABLE_CORE_PERMISSIONS_OVERRIDE` +| `core.permissions` + +| `ENABLE_CORE_ROOTHEALTH_OVERRIDE` +| `core.rootHealth` + +| `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` +| `core.rootHttpRouter` + +| `ENABLE_CORE_ROOTLIFECYCLE_OVERRIDE` +| `core.rootLifecycle` + +| `ENABLE_CORE_SCHEDULER_OVERRIDE` +| `core.scheduler` + +| `ENABLE_CORE_USERINFO_OVERRIDE` +| `core.userInfo` + +| `ENABLE_CORE_URLREADER_OVERRIDE` +| `core.urlReader` + +| `ENABLE_EVENTS_SERVICE_OVERRIDE` +| `events.service` +|=== + +. Install your custom core service as a `BackendFeature` as shown in the following example: + +.Example of a `BackendFeature` middleware function to handle incoming `HTTP` requests +[source,javascript] +---- +// Create the BackendFeature +export const customRootHttpServerFactory: BackendFeature = + rootHttpRouterServiceFactory({ + configure: ({ app, routes, middleware, logger }) => { + logger.info( + 'Using custom root HttpRouterServiceFactory configure function', + ); + app.use(middleware.helmet()); + app.use(middleware.cors()); + app.use(middleware.compression()); + app.use(middleware.logging()); + // Add a the custom middleware function before all + // of the route handlers + app.use(addTestHeaderMiddleware({ logger })); + app.use(routes); + app.use(middleware.notFound()); + app.use(middleware.error()); + }, + }); + +// Export the BackendFeature as the default entrypoint +export default customRootHttpServerFactory; +---- ++ +In the previous example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. + diff --git a/modules/dynamic-plugins/proc-topology-configure.adoc b/modules/dynamic-plugins/proc-topology-configure.adoc deleted file mode 100644 index 96781c5fd6..0000000000 --- a/modules/dynamic-plugins/proc-topology-configure.adoc +++ /dev/null @@ -1,333 +0,0 @@ -= Configuration - -== Viewing OpenShift routes -To view OpenShift routes, you must grant read access to the routes resource in the Cluster Role: - -[source,yaml] ----- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - route.openshift.io - resources: - - routes - verbs: - - get - - list ----- - -You must also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'route.openshift.io' - apiVersion: 'v1' - plural: 'routes' ----- - -== Viewing pod logs -To view pod logs, you must grant the following permission to the `ClusterRole`: - -[source,yaml] ----- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - '' - resources: - - pods - - pods/log - verbs: - - get - - list - - watch ----- - -== Viewing Tekton PipelineRuns -To view the Tekton PipelineRuns you must grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - tekton.dev - resources: - - pipelines - - pipelineruns - - taskruns - verbs: - - get - - list ----- - -To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, you must add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'pipelines' - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'pipelineruns' - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'taskruns' ----- - -== Viewing virtual machines -To view virtual machines, the OpenShift Virtualization operator must be installed and configured on a Kubernetes cluster. -You must also grant read access to the `VirtualMachines` resource in the `ClusterRole`: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - kubevirt.io - resources: - - virtualmachines - - virtualmachineinstances - verbs: - - get - - list ----- - -To view the virtual machine nodes on the topology plugin, you must add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'kubevirt.io' - apiVersion: 'v1' - plural: 'virtualmachines' - - group: 'kubevirt.io' - apiVersion: 'v1' - plural: 'virtualmachineinstances' ----- - -== Enabling the source code editor -To enable the source code editor, you must grant read access to the CheClusters resource in the `ClusterRole` as shown in the following example code: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - org.eclipse.che - resources: - - checlusters - verbs: - - get - - list ----- - -To use the source code editor, you must add the following configuration to the `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- - kubernetes: - ... - customResources: - - group: 'org.eclipse.che' - apiVersion: 'v2' - plural: 'checlusters' ----- - -== Labels and annotations -=== Linking to the source code editor or the source -Add the following annotations to workload resources, such as Deployments to navigate to the Git repository of the associated application using the source code editor: - -[source,yaml] ----- -annotations: - app.openshift.io/vcs-uri: <GIT_REPO_URL> ----- - -Add the following annotation to navigate to a specific branch: - -[source,yaml] ----- -annotations: - app.openshift.io/vcs-ref: <GIT_REPO_BRANCH> ----- - -[NOTE] -==== -If Red Hat OpenShift Dev Spaces is installed and configured and git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. -==== - -[NOTE] -==== -When you deploy your application using the OCP Git import flows, then you do not need to add the labels as import flows do that. Otherwise, you need to add the labels manually to the workload YAML file. -==== - -//The labels are not similar to `backstage.io/edit-url` annotations as it points to the catalog entity metadata source file and is applied to RHDH catalog entity metadata YAML file, but not Kubernetes resources. - -You can also add the `app.openshift.io/edit-url` annotation with the edit URL that you want to access using the decorator. - -=== Entity annotation/label -For RHDH to detect that an entity has Kubernetes components, add the following annotation to the entity's `catalog-info.yaml`: - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME> ----- - -The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity, add the following label to the resources: - -[source,yaml] ----- -labels: - backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>` ----- - -[NOTE] -==== -When using the label selector, the mentioned labels must be present on the resource. -==== - -=== Namespace annotation -To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-namespace: <RESOURCE_NS> ----- - -The Red Hat OpenShift Dev Spaces instance is not accessible using the source code editor if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file. - -To retrieve the instance URL, you require the CheCluster custom resource (CR). As the CheCluster CR is created in the openshift-devspaces namespace, the instance URL is not retrieved if the namespace annotation value is not openshift-devspaces. - -=== Label selector query annotation -You can write your own custom label, which RHDH 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' ----- - -If you have multiple entities while Red Hat Dev Spaces is configured and want multiple entities to support the edit code decorator that redirects to the Red Hat Dev Spaces instance, you can add the backstage.io/kubernetes-label-selector annotation to the catalog-info.yaml file for each entity. - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-label-selector: 'component in (<BACKSTAGE_ENTITY_NAME>,che)' ----- - -If you are using the previous label selector, you must add the following labels to your resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: - -[source,yaml] ----- -labels: - component: che # add this label to your che cluster instance -labels: - component: <BACKSTAGE_ENTITY_NAME> # add this label to the other resources associated with your entity ----- - -You can also write your own custom query for the label selector with unique labels to differentiate your entities. However, you need to ensure that you add those labels to the resources associated with your entities including your CheCluster instance. - -=== Icon displayed in the node -To display a runtime icon in the topology nodes, add the following label to workload resources, such as Deployments: - -[source,yaml] ----- -labels: - app.openshift.io/runtime: <RUNTIME_NAME> ----- -Alternatively, you can include the following label to display the runtime icon: - -[source,yaml] ----- -labels: - app.kubernetes.io/name: <RUNTIME_NAME> ----- - -Supported values of `<RUNTIME_NAME>` include: - -* django -* dotnet -* drupal -* go-gopher -* golang -* grails -* jboss -* jruby -* js -* nginx -* nodejs -* openjdk -* perl -* phalcon -* php -* python -* quarkus -* rails -* redis -* rh-spring-boot -* rust -* java -* rh-openjdk -* ruby -* spring -* spring-boot - -[NOTE] -==== -Other values result in icons not being rendered for the node. -==== - -=== App grouping -To display workload resources such as deployments or pods in a visual group, add the following label: - -[source,yaml] ----- -labels: - app.kubernetes.io/part-of: <GROUP_NAME> ----- - -=== Node connector -To display the workload resources such as deployments or pods with a visual connector, add the following annotation: - -[source,yaml] ----- -annotations: - app.openshift.io/connects-to: '[{"apiVersion": <RESOURCE_APIVERSION>,"kind": <RESOURCE_KIND>,"name": <RESOURCE_NAME>}]' ----- - -For more information about the labels and annotations, see _Guidelines for labels and annotations for OpenShift applications_. diff --git a/modules/dynamic-plugins/proc-using-topology-plugin.adoc b/modules/dynamic-plugins/proc-using-topology-plugin.adoc index ab33ae1699..923e470e09 100644 --- a/modules/dynamic-plugins/proc-using-topology-plugin.adoc +++ b/modules/dynamic-plugins/proc-using-topology-plugin.adoc @@ -1,20 +1,11 @@ +[id="using-the-topology-plugin"] = Using the Topology plugin -Topology is a front-end plugin that enables you to view the workloads as nodes that power any service on the Kubernetes cluster. .Prerequisites -* You have installed the Red Hat Developer Hub (RHDH). +* Your {product} instance is installed and running. * You have installed the Topology plugin. //For the installation process, see Installation. -* If the RBAC permission framework is enabled, ensure to add the following permission policies in an external permission policies configuration file named `rbac-policy.csv` to allow the RBAC admins or your desired user(s)/group(s) to access the Topology plugin: -+ -[source,bash] ----- -g, user:default/<YOUR_USERNAME>, role:default/topology-viewer -p, role:default/topology-viewer, topology.view.read, read, allow -p, role:default/topology-viewer, kubernetes.proxy, use, allow -p, role:default/topology-viewer, catalog-entity, read, allow -p, role:default/topology-viewer, topology.view.read, read, allow grants the user the ability to see the Topology panel. p, role:default/topology-viewer, kubernetes.proxy, use, allow grants the user the ability to view the pod logs. p, role:default/topology-viewer, catalog-entity, read, allow grants the user the ability to see the catalog item. ----- +* You have xref:enable-users-to-use-the-topology-plugin[enabled the users to use the Topology plugin]. .Procedure @@ -23,14 +14,14 @@ p, role:default/topology-viewer, topology.view.read, read, allow grants the user + image::rhdh-plugins-reference/topology-tab-user1.png[topology-user-1] -. Select a node and a pop-up appears on the right side, which contains two tabs: *Details* and *Resources*. - -. The *Details* and *Resources* tabs contain the associated information and resources of the node. +. Select a node and a pop-up appears on the right side that contains two tabs: *Details* and *Resources*. ++ +The *Details* and *Resources* tabs contain the associated information and resources for the node. + image::rhdh-plugins-reference/topology-tab-user2.png[topology-user-2] -. Click on the *Open URL* button on the top of a node. +. Click the *Open URL* button on the top of a node. + image::rhdh-plugins-reference/topology-tab-user3.png[topology-user-3] + -When you click on the *Open URL* button, it allows you to access the associated *Ingresses* and runs your application in a new tab. +Click the *Open URL* button to access the associated *Ingresses* and run your application in a new tab. diff --git a/modules/dynamic-plugins/proc-viewing-installed-plugins.adoc b/modules/dynamic-plugins/proc-viewing-installed-plugins.adoc index 9894dbf9c0..fca49def4b 100644 --- a/modules/dynamic-plugins/proc-viewing-installed-plugins.adoc +++ b/modules/dynamic-plugins/proc-viewing-installed-plugins.adoc @@ -11,5 +11,5 @@ Using the Dynamic Plugins Info front-end plugin, you can view plugins that are c .Procedure -. Open your {product-short} application and click *Administration*. -. Go to the *Plugins* tab to view a list of installed plugins and related information. +. Open your {product-short} application and click *Administration* > *Extensions*. +. Go to the *Installed* tab to view a list of installed plugins and related information. diff --git a/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc new file mode 100644 index 0000000000..81322932ea --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc @@ -0,0 +1,33 @@ +[id="proc-viewing-openshift-routes_{context}"] += Viewing OpenShift routes + +.Procedure +. To view OpenShift routes, grant read access to the routes resource in the Cluster Role: ++ +[source,yaml] +---- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - route.openshift.io + resources: + - routes + verbs: + - get + - list +---- +. Also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: ++ +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'route.openshift.io' + apiVersion: 'v1' + plural: 'routes' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-pod-logs.adoc b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc new file mode 100644 index 0000000000..083428bb2c --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc @@ -0,0 +1,24 @@ +[id="proc-viewing-pod-logs_{context}"] += Viewing pod logs + +.Procedure +* To view pod logs, you must grant the following permission to the `ClusterRole`: ++ +[source,yaml] +---- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - '' + resources: + - pods + - pods/log + verbs: + - get + - list + - watch +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc new file mode 100644 index 0000000000..320013681b --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc @@ -0,0 +1,42 @@ +[id="proc-viewing-tekton-pipelineruns_{context}"] += Viewing Tekton PipelineRuns + +.Procedure +. To view the Tekton PipelineRuns, grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: ++ +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - tekton.dev + resources: + - pipelines + - pipelineruns + - taskruns + verbs: + - get + - list +---- +. To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: ++ +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'pipelines' + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'pipelineruns' + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'taskruns' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc new file mode 100644 index 0000000000..a0a51e02e8 --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc @@ -0,0 +1,40 @@ +[id="proc-viewing-virtual-machines_{context}"] += Viewing virtual machines + +.Prerequisites +. The OpenShift Virtualization operator is installed and configured on a Kubernetes cluster. +.Procedure +. Grant read access to the `VirtualMachines` resource in the `ClusterRole`: ++ +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - kubevirt.io + resources: + - virtualmachines + - virtualmachineinstances + verbs: + - get + - list +---- +. To view the virtual machine nodes on the topology plugin, add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: ++ +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'kubevirt.io' + apiVersion: 'v1' + plural: 'virtualmachines' + - group: 'kubevirt.io' + apiVersion: 'v1' + plural: 'virtualmachineinstances' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/ref-catalog-plugin.adoc b/modules/dynamic-plugins/ref-catalog-plugin.adoc new file mode 100644 index 0000000000..2d213c1e3e --- /dev/null +++ b/modules/dynamic-plugins/ref-catalog-plugin.adoc @@ -0,0 +1,33 @@ += Plugin cards +For each plugin card, the following details are displayed: + +Badge:: The following badges are defined: +* Certified by Red Hat: Plugins that are produced and supported by Red Hat's partners. +* Verified by Red Hat: Production ready plugins that are supported by Red Hat +* Custom plugin: Plugins are created and added by the customer. ++ +[NOTE] +No badge is displayed if a plugin does not match any of these definitions. + +Icon:: The plugin icon (base64). +Name:: The plugin name. +Author(s):: A single author name or multiple author names if a plugin is developed by multiple authors. +Category:: The categories that are displayed in the filter and labels. Only one category is shown on the card but any other categories that you select will apply when you use the category filter. +Short description:: Short description that is shown on the cards (text). +Read more link:: Clickable link to open the plugin details page. + += Plugin details +When you click on the *Read more* link on a plugin card, the following details are displayed: + +Icon:: The plugin icon (base64). +Name:: The plugin name. +Author(s):: A single author name or multiple author names if a plugin is developed by multiple authors. +Highlights:: A list of plugin features. +Install button:: Button to install the plugin (disabled). +Long description:: Full description of the plugin (Markdown). +Links:: Clickable links providing additional information about the plugin. +Versions:: Displays the plugin's name, version, role, supported version, and installation status based on the plugin's package name. + +For example: + +image::rhdh-plugins-reference/extensions-catalog-sidebar.png[Extensions Catalog sidebar] \ No newline at end of file diff --git a/modules/dynamic-plugins/ref-community-plugins.adoc b/modules/dynamic-plugins/ref-community-plugins.adoc index 64a94911b3..47b3081b90 100644 --- a/modules/dynamic-plugins/ref-community-plugins.adoc +++ b/modules/dynamic-plugins/ref-community-plugins.adoc @@ -10,9 +10,17 @@ Details on how {company-name} provides support for bundled community dynamic plugins are available on the https://access.redhat.com/policy/developerhub-support-policy[Red Hat Developer Support Policy] page. ==== -{product-very-short} includes the following 0 community plugins: +{product-very-short} includes the following 2 community plugins: [%header,cols=4*] |=== |*Name* |*Plugin* |*Version* |*Path and required variables* +|Argo CD |`https://npmjs.com/package/@roadiehq/backstage-plugin-argo-cd/v/2.8.4[@roadiehq/backstage-plugin-argo-cd]` |2.8.4 +|`./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd` + + +|Global Floating Action Button |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-floating-action-button/v/1.0.0[@red-hat-developer-hub/backstage-plugin-global-floating-action-button]` |1.0.0 +|`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button` + + |=== diff --git a/modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc b/modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc index 773d51f359..0d0159d0cd 100644 --- a/modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc +++ b/modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc @@ -2,9 +2,9 @@ = Example Helm chart configurations for dynamic plugin installations -The following examples demonstrate how to configure the Helm chart for specific types of dynamic plugin installations. +The following examples demonstrate how to configure the Helm chart for specific types of dynamic plugin installations. -.Configuring a local plugin and an external plugin when the external plugin requires a specific app-config +.Configuring a local plugin and an external plugin when the external plugin requires a specific configuration [source,yaml] ---- global: diff --git a/modules/dynamic-plugins/ref-rh-compatible-plugins.adoc b/modules/dynamic-plugins/ref-rh-compatible-plugins.adoc index cf8740ca12..5cca90f229 100644 --- a/modules/dynamic-plugins/ref-rh-compatible-plugins.adoc +++ b/modules/dynamic-plugins/ref-rh-compatible-plugins.adoc @@ -26,9 +26,9 @@ The following Technology Preview plugins are not preinstalled and must be instal |=== -[NOTE] -==== - -* The above Red Hat Ansible Automation Platform (RHAAP) plugins, can be used as a replacement for the older plugin listed in the link:{LinkPluginsGuide}#rhdh-tech-preview-plugins[Technology Preview plugins] section of the _{NameOfPluginsGuide} guide_. -==== +//[NOTE] +//==== +// +//* The above Red Hat Ansible Automation Platform (RHAAP) plugins, can be used as a replacement for the older plugin listed in the link:{configuring-dynamic-plugins-book-url}#rhdh-tech-preview-plugins[Technology Preview plugins] section of _{configuring-dynamic-plugins-book-title}_. +//==== diff --git a/modules/dynamic-plugins/ref-rh-supported-plugins.adoc b/modules/dynamic-plugins/ref-rh-supported-plugins.adoc index b65a52aef1..8ecea82a94 100644 --- a/modules/dynamic-plugins/ref-rh-supported-plugins.adoc +++ b/modules/dynamic-plugins/ref-rh-supported-plugins.adoc @@ -3,12 +3,12 @@ = {company-name} supported plugins -{company-name} supports the following 20 plugins: +{company-name} supports the following 21 plugins: [%header,cols=4*] |=== |*Name* |*Plugin* |*Version* |*Path and required variables* -|Analytics Provider Segment |`https://npmjs.com/package/@backstage-community/plugin-analytics-provider-segment/v/1.10.2[@backstage-community/plugin-analytics-provider-segment]` |1.10.2 +|Analytics Provider Segment |`https://npmjs.com/package/@backstage-community/plugin-analytics-provider-segment/v/1.12.0[@backstage-community/plugin-analytics-provider-segment]` |1.12.0 |`./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment` `SEGMENT_WRITE_KEY` @@ -16,10 +16,6 @@ `SEGMENT_TEST_MODE` -|Argo CD |`https://npmjs.com/package/@roadiehq/backstage-plugin-argo-cd/v/2.8.4[@roadiehq/backstage-plugin-argo-cd]` |2.8.4 -|`./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd` - - |Argo CD |`https://npmjs.com/package/@roadiehq/backstage-plugin-argo-cd-backend/v/3.2.3[@roadiehq/backstage-plugin-argo-cd-backend]` |3.2.3 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd-backend-dynamic` @@ -36,17 +32,17 @@ `ARGOCD_AUTH_TOKEN2` -|Dynamic Home Page |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-dynamic-home-page/v/1.0.1[@red-hat-developer-hub/backstage-plugin-dynamic-home-page]` |1.0.1 +|Dynamic Home Page |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-dynamic-home-page/v/1.1.0[@red-hat-developer-hub/backstage-plugin-dynamic-home-page]` |1.1.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-dynamic-home-page` -|GitHub |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github/v/0.7.6[@backstage/plugin-catalog-backend-module-github]` |0.7.6 +|GitHub |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github/v/0.7.9[@backstage/plugin-catalog-backend-module-github]` |0.7.9 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic` `GITHUB_ORG` -|GitHub Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github-org/v/0.3.3[@backstage/plugin-catalog-backend-module-github-org]` |0.3.3 +|GitHub Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github-org/v/0.3.6[@backstage/plugin-catalog-backend-module-github-org]` |0.3.6 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic` `GITHUB_URL` @@ -54,7 +50,11 @@ `GITHUB_ORG` -|Keycloak |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-keycloak/v/3.2.2[@backstage-community/plugin-catalog-backend-module-keycloak]` |3.2.2 +|Global Header |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-header/v/1.0.0[@red-hat-developer-hub/backstage-plugin-global-header]` |1.0.0 +|`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header` + + +|Keycloak |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-keycloak/v/3.7.0[@backstage-community/plugin-catalog-backend-module-keycloak]` |3.7.0 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic` `KEYCLOAK_BASE_URL` @@ -68,7 +68,7 @@ `KEYCLOAK_CLIENT_SECRET` -|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes-backend/v/0.18.7[@backstage/plugin-kubernetes-backend]` |0.18.7 +|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes-backend/v/0.19.2[@backstage/plugin-kubernetes-backend]` |0.19.2 |`./dynamic-plugins/dist/backstage-plugin-kubernetes-backend-dynamic` `K8S_CLUSTER_NAME` @@ -78,15 +78,15 @@ `K8S_CLUSTER_TOKEN` -|Kubernetes |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-kubernetes/v/2.2.2[@backstage-community/plugin-scaffolder-backend-module-kubernetes]` |2.2.2 +|Kubernetes |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-kubernetes/v/2.5.0[@backstage-community/plugin-scaffolder-backend-module-kubernetes]` |2.5.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic` -|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm/v/5.2.4[@backstage-community/plugin-ocm]` |5.2.4 +|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm/v/5.3.0[@backstage-community/plugin-ocm]` |5.3.0 |`./dynamic-plugins/dist/backstage-community-plugin-ocm` -|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm-backend/v/5.2.3[@backstage-community/plugin-ocm-backend]` |5.2.3 +|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm-backend/v/5.4.0[@backstage-community/plugin-ocm-backend]` |5.4.0 |`./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic` `OCM_HUB_NAME` @@ -96,39 +96,43 @@ `OCM_SA_TOKEN` -|Quay |`https://npmjs.com/package/@backstage-community/plugin-quay/v/1.14.4[@backstage-community/plugin-quay]` |1.14.4 +|Quay |`https://npmjs.com/package/@backstage-community/plugin-quay/v/1.18.1[@backstage-community/plugin-quay]` |1.18.1 |`./dynamic-plugins/dist/backstage-community-plugin-quay` -|Quay |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-quay/v/2.2.2[@backstage-community/plugin-scaffolder-backend-module-quay]` |2.2.2 +|Quay |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-quay/v/2.4.0[@backstage-community/plugin-scaffolder-backend-module-quay]` |2.4.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-quay-dynamic` -|RBAC |`https://npmjs.com/package/@backstage-community/plugin-rbac/v/1.33.4[@backstage-community/plugin-rbac]` |1.33.4 +|RBAC |`https://npmjs.com/package/@backstage-community/plugin-rbac/v/1.38.2[@backstage-community/plugin-rbac]` |1.38.2 |`./dynamic-plugins/dist/backstage-community-plugin-rbac` -|Regex |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-regex/v/2.2.3[@backstage-community/plugin-scaffolder-backend-module-regex]` |2.2.3 +|Regex |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-regex/v/2.4.0[@backstage-community/plugin-scaffolder-backend-module-regex]` |2.4.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-regex-dynamic` -|Signals |`https://npmjs.com/package/@backstage/plugin-signals-backend/v/0.2.2[@backstage/plugin-signals-backend]` |0.2.2 +|Signals |`https://npmjs.com/package/@backstage/plugin-signals-backend/v/0.3.0[@backstage/plugin-signals-backend]` |0.3.0 |`./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic` -|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs/v/1.11.0[@backstage/plugin-techdocs]` |1.11.0 +|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs/v/1.12.2[@backstage/plugin-techdocs]` |1.12.2 |`./dynamic-plugins/dist/backstage-plugin-techdocs` -|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs-backend/v/1.11.1[@backstage/plugin-techdocs-backend]` |1.11.1 +|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs-backend/v/1.11.5[@backstage/plugin-techdocs-backend]` |1.11.5 |`./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic` -|Tekton |`https://npmjs.com/package/@backstage-community/plugin-tekton/v/3.17.0[@backstage-community/plugin-tekton]` |3.17.0 +|TechDocs Module Addons Contrib |`https://npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib/v/1.1.20[@backstage/plugin-techdocs-module-addons-contrib]` |1.1.20 +|`./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib` + + +|Tekton |`https://npmjs.com/package/@backstage-community/plugin-tekton/v/3.19.0[@backstage-community/plugin-tekton]` |3.19.0 |`./dynamic-plugins/dist/backstage-community-plugin-tekton` -|Topology |`https://npmjs.com/package/@backstage-community/plugin-topology/v/1.29.7[@backstage-community/plugin-topology]` |1.29.7 +|Topology |`https://npmjs.com/package/@backstage-community/plugin-topology/v/1.32.0[@backstage-community/plugin-topology]` |1.32.0 |`./dynamic-plugins/dist/backstage-community-plugin-topology` diff --git a/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc b/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc index 7aaa1eb738..170383fdd5 100644 --- a/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc +++ b/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc @@ -3,12 +3,12 @@ = {company-name} Technology Preview plugins -{company-name} provides Technology Preview support for the following 54 plugins: +{company-name} provides Technology Preview support for the following 56 plugins: [%header,cols=4*] |=== |*Name* |*Plugin* |*Version* |*Path and required variables* -|3scale |`https://npmjs.com/package/@backstage-community/plugin-3scale-backend/v/3.0.3[@backstage-community/plugin-3scale-backend]` |3.0.3 +|3scale |`https://npmjs.com/package/@backstage-community/plugin-3scale-backend/v/3.2.0[@backstage-community/plugin-3scale-backend]` |3.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic` `THREESCALE_BASE_URL` @@ -16,19 +16,15 @@ `THREESCALE_ACCESS_TOKEN` -|Ansible Automation Platform (AAP) |`https://npmjs.com/package/@janus-idp/backstage-plugin-aap-backend/v/2.2.0[@janus-idp/backstage-plugin-aap-backend]` |2.2.0 -|`./dynamic-plugins/dist/janus-idp-backstage-plugin-aap-backend-dynamic` - -`AAP_BASE_URL` - -`AAP_AUTH_TOKEN` +|ACR |`https://npmjs.com/package/@backstage-community/plugin-acr/v/1.11.0[@backstage-community/plugin-acr]` |1.11.0 +|`./dynamic-plugins/dist/backstage-community-plugin-acr` -|ACR |`https://npmjs.com/package/@backstage-community/plugin-acr/v/1.8.5[@backstage-community/plugin-acr]` |1.8.5 -|`./dynamic-plugins/dist/backstage-community-plugin-acr` +|Argo CD (Red Hat) |`https://npmjs.com/package/@backstage-community/plugin-redhat-argocd/v/1.14.0[@backstage-community/plugin-redhat-argocd]` |1.14.0 +|`./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd` -|Argo CD |`https://npmjs.com/package/@roadiehq/scaffolder-backend-argocd/v/1.2.0[@roadiehq/scaffolder-backend-argocd]` |1.2.0 +|Argo CD |`https://npmjs.com/package/@roadiehq/scaffolder-backend-argocd/v/1.5.0[@roadiehq/scaffolder-backend-argocd]` |1.5.0 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-argocd-dynamic` `ARGOCD_USERNAME` @@ -44,19 +40,15 @@ `ARGOCD_AUTH_TOKEN2` -|Argo CD (Red Hat) |`https://npmjs.com/package/@backstage-community/plugin-redhat-argocd/v/1.11.0[@backstage-community/plugin-redhat-argocd]` |1.11.0 -|`./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd` - - -|Azure |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-azure/v/0.2.2[@backstage/plugin-scaffolder-backend-module-azure]` |0.2.2 +|Azure |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-azure/v/0.2.5[@backstage/plugin-scaffolder-backend-module-azure]` |0.2.5 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic` -|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops/v/0.6.2[@backstage-community/plugin-azure-devops]` |0.6.2 +|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops/v/0.9.0[@backstage-community/plugin-azure-devops]` |0.9.0 |`./dynamic-plugins/dist/backstage-community-plugin-azure-devops` -|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops-backend/v/0.8.0[@backstage-community/plugin-azure-devops-backend]` |0.8.0 +|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops-backend/v/0.11.0[@backstage-community/plugin-azure-devops-backend]` |0.11.0 |`./dynamic-plugins/dist/backstage-community-plugin-azure-devops-backend-dynamic` `AZURE_TOKEN` @@ -68,75 +60,75 @@ |`./dynamic-plugins/dist/parfuemerie-douglas-scaffolder-backend-module-azure-repositories-dynamic` -|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-cloud/v/0.4.1[@backstage/plugin-catalog-backend-module-bitbucket-cloud]` |0.4.1 +|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-cloud/v/0.4.4[@backstage/plugin-catalog-backend-module-bitbucket-cloud]` |0.4.4 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-cloud-dynamic` `BITBUCKET_WORKSPACE` -|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-cloud/v/0.2.2[@backstage/plugin-scaffolder-backend-module-bitbucket-cloud]` |0.2.2 +|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-cloud/v/0.2.5[@backstage/plugin-scaffolder-backend-module-bitbucket-cloud]` |0.2.5 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-cloud-dynamic` -|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-server/v/0.2.3[@backstage/plugin-catalog-backend-module-bitbucket-server]` |0.2.3 +|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-server/v/0.3.1[@backstage/plugin-catalog-backend-module-bitbucket-server]` |0.3.1 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-server-dynamic` `BITBUCKET_HOST` -|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-server/v/0.2.2[@backstage/plugin-scaffolder-backend-module-bitbucket-server]` |0.2.2 +|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-server/v/0.2.5[@backstage/plugin-scaffolder-backend-module-bitbucket-server]` |0.2.5 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-server-dynamic` -|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import/v/1.10.3[@red-hat-developer-hub/backstage-plugin-bulk-import]` |1.10.3 +|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import/v/1.11.0[@red-hat-developer-hub/backstage-plugin-bulk-import]` |1.11.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import` -|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import-backend/v/5.2.0[@red-hat-developer-hub/backstage-plugin-bulk-import-backend]` |5.2.0 +|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import-backend/v/5.3.0[@red-hat-developer-hub/backstage-plugin-bulk-import-backend]` |5.3.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic` -|Datadog |`https://npmjs.com/package/@roadiehq/backstage-plugin-datadog/v/2.4.0[@roadiehq/backstage-plugin-datadog]` |2.4.0 +|Datadog |`https://npmjs.com/package/@roadiehq/backstage-plugin-datadog/v/2.4.2[@roadiehq/backstage-plugin-datadog]` |2.4.2 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-datadog` -|Dynatrace |`https://npmjs.com/package/@backstage-community/plugin-dynatrace/v/10.0.8[@backstage-community/plugin-dynatrace]` |10.0.8 +|Dynatrace |`https://npmjs.com/package/@backstage-community/plugin-dynatrace/v/10.2.0[@backstage-community/plugin-dynatrace]` |10.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-dynatrace` -|Gerrit |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gerrit/v/0.2.2[@backstage/plugin-scaffolder-backend-module-gerrit]` |0.2.2 +|Gerrit |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gerrit/v/0.2.5[@backstage/plugin-scaffolder-backend-module-gerrit]` |0.2.5 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gerrit-dynamic` -|GitHub |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-github/v/0.5.2[@backstage/plugin-scaffolder-backend-module-github]` |0.5.2 +|GitHub |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-github/v/0.5.5[@backstage/plugin-scaffolder-backend-module-github]` |0.5.5 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic` -|GitHub Actions |`https://npmjs.com/package/@backstage-community/plugin-github-actions/v/0.6.24[@backstage-community/plugin-github-actions]` |0.6.24 +|GitHub Actions |`https://npmjs.com/package/@backstage-community/plugin-github-actions/v/0.7.1[@backstage-community/plugin-github-actions]` |0.7.1 |`./dynamic-plugins/dist/backstage-community-plugin-github-actions` -|GitHub Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-insights/v/2.5.1[@roadiehq/backstage-plugin-github-insights]` |2.5.1 +|GitHub Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-insights/v/3.1.3[@roadiehq/backstage-plugin-github-insights]` |3.1.3 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-github-insights` -|GitHub Issues |`https://npmjs.com/package/@backstage-community/plugin-github-issues/v/0.4.8[@backstage-community/plugin-github-issues]` |0.4.8 +|GitHub Issues |`https://npmjs.com/package/@backstage-community/plugin-github-issues/v/0.6.0[@backstage-community/plugin-github-issues]` |0.6.0 |`./dynamic-plugins/dist/backstage-community-plugin-github-issues` -|GitHub Pull Requests |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-pull-requests/v/2.6.0[@roadiehq/backstage-plugin-github-pull-requests]` |2.6.0 +|GitHub Pull Requests |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-pull-requests/v/3.2.1[@roadiehq/backstage-plugin-github-pull-requests]` |3.2.1 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-github-pull-requests` -|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab/v/6.6.1[@immobiliarelabs/backstage-plugin-gitlab]` |6.6.1 +|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab/v/6.8.0[@immobiliarelabs/backstage-plugin-gitlab]` |6.8.0 |`./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab` -|GitLab |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab/v/0.4.4[@backstage/plugin-catalog-backend-module-gitlab]` |0.4.4 +|GitLab |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab/v/0.6.2[@backstage/plugin-catalog-backend-module-gitlab]` |0.6.2 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic` -|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab-backend/v/6.7.0[@immobiliarelabs/backstage-plugin-gitlab-backend]` |6.7.0 +|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab-backend/v/6.8.0[@immobiliarelabs/backstage-plugin-gitlab-backend]` |6.8.0 |`./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic` `GITLAB_HOST` @@ -144,23 +136,23 @@ `GITLAB_TOKEN` -|GitLab |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gitlab/v/0.6.1[@backstage/plugin-scaffolder-backend-module-gitlab]` |0.6.1 +|GitLab |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gitlab/v/0.7.1[@backstage/plugin-scaffolder-backend-module-gitlab]` |0.7.1 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gitlab-dynamic` -|GitLab Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab-org/v/0.2.2[@backstage/plugin-catalog-backend-module-gitlab-org]` |0.2.2 +|GitLab Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab-org/v/0.2.5[@backstage/plugin-catalog-backend-module-gitlab-org]` |0.2.5 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic` -|Http Request |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request/v/5.0.0[@roadiehq/scaffolder-backend-module-http-request]` |5.0.0 +|Http Request |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request/v/5.3.0[@roadiehq/scaffolder-backend-module-http-request]` |5.3.0 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-http-request-dynamic` -|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins/v/0.12.0[@backstage-community/plugin-jenkins]` |0.12.0 +|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins/v/0.16.0[@backstage-community/plugin-jenkins]` |0.16.0 |`./dynamic-plugins/dist/backstage-community-plugin-jenkins` -|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins-backend/v/0.6.2[@backstage-community/plugin-jenkins-backend]` |0.6.2 +|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins-backend/v/0.11.0[@backstage-community/plugin-jenkins-backend]` |0.11.0 |`./dynamic-plugins/dist/backstage-community-plugin-jenkins-backend-dynamic` `JENKINS_URL` @@ -170,43 +162,55 @@ `JENKINS_TOKEN` -|JFrog Artifactory |`https://npmjs.com/package/@backstage-community/plugin-jfrog-artifactory/v/1.10.2[@backstage-community/plugin-jfrog-artifactory]` |1.10.2 +|JFrog Artifactory |`https://npmjs.com/package/@backstage-community/plugin-jfrog-artifactory/v/1.13.0[@backstage-community/plugin-jfrog-artifactory]` |1.13.0 |`./dynamic-plugins/dist/backstage-community-plugin-jfrog-artifactory` -|Jira |`https://npmjs.com/package/@roadiehq/backstage-plugin-jira/v/2.8.0[@roadiehq/backstage-plugin-jira]` |2.8.0 +|Jira |`https://npmjs.com/package/@roadiehq/backstage-plugin-jira/v/2.8.2[@roadiehq/backstage-plugin-jira]` |2.8.2 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-jira` -|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes/v/0.11.16[@backstage/plugin-kubernetes]` |0.11.16 +|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes/v/0.12.3[@backstage/plugin-kubernetes]` |0.12.3 |`./dynamic-plugins/dist/backstage-plugin-kubernetes` -|Ldap |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-ldap/v/0.9.1[@backstage/plugin-catalog-backend-module-ldap]` |0.9.1 +|Ldap |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-ldap/v/0.11.1[@backstage/plugin-catalog-backend-module-ldap]` |0.11.1 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic` -|Lighthouse |`https://npmjs.com/package/@backstage-community/plugin-lighthouse/v/0.4.24[@backstage-community/plugin-lighthouse]` |0.4.24 +|Lighthouse |`https://npmjs.com/package/@backstage-community/plugin-lighthouse/v/0.6.0[@backstage-community/plugin-lighthouse]` |0.6.0 |`./dynamic-plugins/dist/backstage-community-plugin-lighthouse` -|MS Graph |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-msgraph/v/0.6.3[@backstage/plugin-catalog-backend-module-msgraph]` |0.6.3 +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace/v/0.2.0[@red-hat-developer-hub/backstage-plugin-marketplace]` |0.2.1 +|`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace` + + +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace/v/0.2.0[@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace]` |0.2.2 +|`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic` + + +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace-backend/v/0.2.0[@red-hat-developer-hub/backstage-plugin-marketplace-backend]` |0.2.0 +|`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic` + + +|MS Graph |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-msgraph/v/0.6.6[@backstage/plugin-catalog-backend-module-msgraph]` |0.6.6 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic` -|Nexus Repository Manager |`https://npmjs.com/package/@backstage-community/plugin-nexus-repository-manager/v/1.10.6[@backstage-community/plugin-nexus-repository-manager]` |1.10.6 +|Nexus Repository Manager |`https://npmjs.com/package/@backstage-community/plugin-nexus-repository-manager/v/1.12.0[@backstage-community/plugin-nexus-repository-manager]` |1.12.0 |`./dynamic-plugins/dist/backstage-community-plugin-nexus-repository-manager` -|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications/v/0.3.2[@backstage/plugin-notifications]` |0.3.2 +|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications/v/0.5.1[@backstage/plugin-notifications]` |0.5.1 |`./dynamic-plugins/dist/backstage-plugin-notifications` -|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend/v/0.4.2[@backstage/plugin-notifications-backend]` |0.4.2 +|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend/v/0.5.1[@backstage/plugin-notifications-backend]` |0.5.1 |`./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic` -|Notifications Module Email |`https://npmjs.com/package/@backstage/plugin-notifications-backend-module-email/v/0.3.2[@backstage/plugin-notifications-backend-module-email]` |0.3.2 +|Notifications Module Email |`https://npmjs.com/package/@backstage/plugin-notifications-backend-module-email/v/0.3.5[@backstage/plugin-notifications-backend-module-email]` |0.3.5 |`./dynamic-plugins/dist/backstage-plugin-notifications-backend-module-email-dynamic` `EMAIL_HOSTNAME` @@ -234,19 +238,19 @@ `PAGERDUTY_SUBDOMAIN` -|Pingidentity |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-pingidentity/v/0.1.5[@backstage-community/plugin-catalog-backend-module-pingidentity]` |0.1.5 +|Pingidentity |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-pingidentity/v/0.2.0[@backstage-community/plugin-catalog-backend-module-pingidentity]` |0.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-pingidentity-dynamic` -|Scaffolder Relation Processor |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor/v/2.0.2[@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor]` |2.0.2 +|Scaffolder Relation Processor |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor/v/2.2.0[@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor]` |2.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic` -|Security Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-security-insights/v/2.4.0[@roadiehq/backstage-plugin-security-insights]` |2.4.0 +|Security Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-security-insights/v/3.1.2[@roadiehq/backstage-plugin-security-insights]` |3.1.2 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-security-insights` -|ServiceNow |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-servicenow/v/2.2.3[@backstage-community/plugin-scaffolder-backend-module-servicenow]` |2.2.3 +|ServiceNow |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-servicenow/v/2.4.0[@backstage-community/plugin-scaffolder-backend-module-servicenow]` |2.4.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-servicenow-dynamic` `SERVICENOW_BASE_URL` @@ -256,15 +260,15 @@ `SERVICENOW_PASSWORD` -|Signals |`https://npmjs.com/package/@backstage/plugin-signals/v/0.0.11[@backstage/plugin-signals]` |0.0.11 +|Signals |`https://npmjs.com/package/@backstage/plugin-signals/v/0.0.15[@backstage/plugin-signals]` |0.0.15 |`./dynamic-plugins/dist/backstage-plugin-signals` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube/v/0.8.7[@backstage-community/plugin-sonarqube]` |0.8.7 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube/v/0.10.0[@backstage-community/plugin-sonarqube]` |0.10.0 |`./dynamic-plugins/dist/backstage-community-plugin-sonarqube` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube-backend/v/0.3.0[@backstage-community/plugin-sonarqube-backend]` |0.3.0 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube-backend/v/0.5.0[@backstage-community/plugin-sonarqube-backend]` |0.5.0 |`./dynamic-plugins/dist/backstage-community-plugin-sonarqube-backend-dynamic` `SONARQUBE_URL` @@ -272,21 +276,21 @@ `SONARQUBE_TOKEN` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-sonarqube/v/2.2.2[@backstage-community/plugin-scaffolder-backend-module-sonarqube]` |2.2.2 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-sonarqube/v/2.4.0[@backstage-community/plugin-scaffolder-backend-module-sonarqube]` |2.4.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-sonarqube-dynamic` -|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar/v/1.0.0[@backstage-community/plugin-tech-radar]` |1.0.0 +|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar/v/1.2.0[@backstage-community/plugin-tech-radar]` |1.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-tech-radar` -|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar-backend/v/1.0.0[@backstage-community/plugin-tech-radar-backend]` |1.0.0 +|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar-backend/v/1.2.0[@backstage-community/plugin-tech-radar-backend]` |1.2.0 |`./dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` `TECH_RADAR_DATA_URL` -|Utils |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-utils/v/3.0.0[@roadiehq/scaffolder-backend-module-utils]` |3.0.0 +|Utils |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-utils/v/3.3.0[@roadiehq/scaffolder-backend-module-utils]` |3.3.0 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-utils-dynamic` diff --git a/modules/dynamic-plugins/rhdh-supported-plugins.csv b/modules/dynamic-plugins/rhdh-supported-plugins.csv index 2d1718f94f..8a7d3b3f19 100644 --- a/modules/dynamic-plugins/rhdh-supported-plugins.csv +++ b/modules/dynamic-plugins/rhdh-supported-plugins.csv @@ -1,73 +1,77 @@ "Name","Plugin","Role","Version","Support Level","Path","Required Variables","Default" -"Analytics Provider Segment ","@backstage-community/plugin-analytics-provider-segment","Frontend","1.10.2","Production","./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment","`SEGMENT_WRITE_KEY`;`SEGMENT_TEST_MODE`;","Enabled" -"Argo CD ","@roadiehq/backstage-plugin-argo-cd","Frontend","2.8.4","Production","./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd",";","Disabled" +"Analytics Provider Segment ","@backstage-community/plugin-analytics-provider-segment","Frontend","1.12.0","Production","./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment","`SEGMENT_WRITE_KEY`;`SEGMENT_TEST_MODE`;","Enabled" "Argo CD ","@roadiehq/backstage-plugin-argo-cd-backend","Backend","3.2.3","Production","./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd-backend-dynamic","`ARGOCD_USERNAME`;`ARGOCD_PASSWORD`;`ARGOCD_INSTANCE1_URL`;`ARGOCD_AUTH_TOKEN`;`ARGOCD_INSTANCE2_URL`;`ARGOCD_AUTH_TOKEN2`;","Disabled" -"Dynamic Home Page ","@red-hat-developer-hub/backstage-plugin-dynamic-home-page","Frontend","1.0.1","Production","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-dynamic-home-page",";","Enabled" -"GitHub ","@backstage/plugin-catalog-backend-module-github","Backend","0.7.6","Production","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic","`GITHUB_ORG`;","Disabled" -"GitHub Org ","@backstage/plugin-catalog-backend-module-github-org","Backend","0.3.3","Production","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic","`GITHUB_URL`;`GITHUB_ORG`;","Disabled" -"Keycloak ","@backstage-community/plugin-catalog-backend-module-keycloak","Backend","3.2.2","Production","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic","`KEYCLOAK_BASE_URL`;`KEYCLOAK_LOGIN_REALM`;`KEYCLOAK_REALM`;`KEYCLOAK_CLIENT_ID`;`KEYCLOAK_CLIENT_SECRET`;","Disabled" -"Kubernetes ","@backstage/plugin-kubernetes-backend","Backend","0.18.7","Production","./dynamic-plugins/dist/backstage-plugin-kubernetes-backend-dynamic","`K8S_CLUSTER_NAME`;`K8S_CLUSTER_URL`;`K8S_CLUSTER_TOKEN`;","Disabled" -"Kubernetes ","@backstage-community/plugin-scaffolder-backend-module-kubernetes","Backend","2.2.2","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic",";","Disabled" -"OCM ","@backstage-community/plugin-ocm","Frontend","5.2.4","Production","./dynamic-plugins/dist/backstage-community-plugin-ocm",";","Disabled" -"OCM ","@backstage-community/plugin-ocm-backend","Backend","5.2.3","Production","./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic","`OCM_HUB_NAME`;`OCM_HUB_URL`;`OCM_SA_TOKEN`;","Disabled" -"Quay ","@backstage-community/plugin-quay","Frontend","1.14.4","Production","./dynamic-plugins/dist/backstage-community-plugin-quay",";","Disabled" -"Quay ","@backstage-community/plugin-scaffolder-backend-module-quay","Backend","2.2.2","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-quay-dynamic",";","Enabled" -"RBAC ","@backstage-community/plugin-rbac","Frontend","1.33.4","Production","./dynamic-plugins/dist/backstage-community-plugin-rbac",";","Disabled" -"Regex ","@backstage-community/plugin-scaffolder-backend-module-regex","Backend","2.2.3","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-regex-dynamic",";","Enabled" -"Signals ","@backstage/plugin-signals-backend","Backend","0.2.2","Production","./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic",";","Disabled" -"Tekton ","@backstage-community/plugin-tekton","Frontend","3.17.0","Production","./dynamic-plugins/dist/backstage-community-plugin-tekton",";","Disabled" -"Topology ","@backstage-community/plugin-topology","Frontend","1.29.7","Production","./dynamic-plugins/dist/backstage-community-plugin-topology",";","Disabled" -"3scale ","@backstage-community/plugin-3scale-backend","Backend","3.0.3","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic","`THREESCALE_BASE_URL`;`THREESCALE_ACCESS_TOKEN`;","Disabled" -"Ansible Automation Platform (AAP) ","@janus-idp/backstage-plugin-aap-backend","Backend","2.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/janus-idp-backstage-plugin-aap-backend-dynamic","`AAP_BASE_URL`;`AAP_AUTH_TOKEN`;","Disabled" -"ACR ","@backstage-community/plugin-acr","Frontend","1.8.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-acr",";","Disabled" -"Argo CD ","@roadiehq/scaffolder-backend-argocd","Backend","1.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-argocd-dynamic","`ARGOCD_USERNAME`;`ARGOCD_PASSWORD`;`ARGOCD_INSTANCE1_URL`;`ARGOCD_AUTH_TOKEN`;`ARGOCD_INSTANCE2_URL`;`ARGOCD_AUTH_TOKEN2`;","Disabled" -"Argo CD (Red Hat) ","@backstage-community/plugin-redhat-argocd","Frontend","1.11.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd",";","Disabled" -"Azure ","@backstage/plugin-scaffolder-backend-module-azure","Backend","0.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic",";","Disabled" -"Azure Devops ","@backstage-community/plugin-azure-devops","Frontend","0.6.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-azure-devops",";","Disabled" -"Azure Devops ","@backstage-community/plugin-azure-devops-backend","Backend","0.8.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-azure-devops-backend-dynamic","`AZURE_TOKEN`;`AZURE_ORG`;","Disabled" +"Dynamic Home Page ","@red-hat-developer-hub/backstage-plugin-dynamic-home-page","Frontend","1.1.0","Production","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-dynamic-home-page",";","Enabled" +"GitHub ","@backstage/plugin-catalog-backend-module-github","Backend","0.7.9","Production","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic","`GITHUB_ORG`;","Disabled" +"GitHub Org ","@backstage/plugin-catalog-backend-module-github-org","Backend","0.3.6","Production","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic","`GITHUB_URL`;`GITHUB_ORG`;","Disabled" +"Global Header ","@red-hat-developer-hub/backstage-plugin-global-header","Frontend","1.0.0","Production","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header",";","Enabled" +"Keycloak ","@backstage-community/plugin-catalog-backend-module-keycloak","Backend","3.7.0","Production","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic","`KEYCLOAK_BASE_URL`;`KEYCLOAK_LOGIN_REALM`;`KEYCLOAK_REALM`;`KEYCLOAK_CLIENT_ID`;`KEYCLOAK_CLIENT_SECRET`;","Disabled" +"Kubernetes ","@backstage/plugin-kubernetes-backend","Backend","0.19.2","Production","./dynamic-plugins/dist/backstage-plugin-kubernetes-backend-dynamic","`K8S_CLUSTER_NAME`;`K8S_CLUSTER_URL`;`K8S_CLUSTER_TOKEN`;","Disabled" +"Kubernetes ","@backstage-community/plugin-scaffolder-backend-module-kubernetes","Backend","2.5.0","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic",";","Disabled" +"OCM ","@backstage-community/plugin-ocm","Frontend","5.3.0","Production","./dynamic-plugins/dist/backstage-community-plugin-ocm",";","Disabled" +"OCM ","@backstage-community/plugin-ocm-backend","Backend","5.4.0","Production","./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic","`OCM_HUB_NAME`;`OCM_HUB_URL`;`OCM_SA_TOKEN`;","Disabled" +"Quay ","@backstage-community/plugin-quay","Frontend","1.18.1","Production","./dynamic-plugins/dist/backstage-community-plugin-quay",";","Disabled" +"Quay ","@backstage-community/plugin-scaffolder-backend-module-quay","Backend","2.4.0","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-quay-dynamic",";","Enabled" +"RBAC ","@backstage-community/plugin-rbac","Frontend","1.38.2","Production","./dynamic-plugins/dist/backstage-community-plugin-rbac",";","Disabled" +"Regex ","@backstage-community/plugin-scaffolder-backend-module-regex","Backend","2.4.0","Production","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-regex-dynamic",";","Enabled" +"Signals ","@backstage/plugin-signals-backend","Backend","0.3.0","Production","./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic",";","Disabled" +"Tekton ","@backstage-community/plugin-tekton","Frontend","3.19.0","Production","./dynamic-plugins/dist/backstage-community-plugin-tekton",";","Disabled" +"Topology ","@backstage-community/plugin-topology","Frontend","1.32.0","Production","./dynamic-plugins/dist/backstage-community-plugin-topology",";","Disabled" +"3scale ","@backstage-community/plugin-3scale-backend","Backend","3.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic","`THREESCALE_BASE_URL`;`THREESCALE_ACCESS_TOKEN`;","Disabled" +"ACR ","@backstage-community/plugin-acr","Frontend","1.11.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-acr",";","Disabled" +"Argo CD (Red Hat) ","@backstage-community/plugin-redhat-argocd","Frontend","1.14.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd",";","Disabled" +"Argo CD ","@roadiehq/scaffolder-backend-argocd","Backend","1.5.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-argocd-dynamic","`ARGOCD_USERNAME`;`ARGOCD_PASSWORD`;`ARGOCD_INSTANCE1_URL`;`ARGOCD_AUTH_TOKEN`;`ARGOCD_INSTANCE2_URL`;`ARGOCD_AUTH_TOKEN2`;","Disabled" +"Azure ","@backstage/plugin-scaffolder-backend-module-azure","Backend","0.2.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic",";","Disabled" +"Azure Devops ","@backstage-community/plugin-azure-devops","Frontend","0.9.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-azure-devops",";","Disabled" +"Azure Devops ","@backstage-community/plugin-azure-devops-backend","Backend","0.11.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-azure-devops-backend-dynamic","`AZURE_TOKEN`;`AZURE_ORG`;","Disabled" "Azure Repositories ","@parfuemerie-douglas/scaffolder-backend-module-azure-repositories","Backend","0.3.0","Red Hat Tech Preview","./dynamic-plugins/dist/parfuemerie-douglas-scaffolder-backend-module-azure-repositories-dynamic",";","Disabled" -"Bitbucket Cloud ","@backstage/plugin-catalog-backend-module-bitbucket-cloud","Backend","0.4.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-cloud-dynamic","`BITBUCKET_WORKSPACE`;","Disabled" -"Bitbucket Cloud ","@backstage/plugin-scaffolder-backend-module-bitbucket-cloud","Backend","0.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-cloud-dynamic",";","Disabled" -"Bitbucket Server ","@backstage/plugin-catalog-backend-module-bitbucket-server","Backend","0.2.3","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-server-dynamic","`BITBUCKET_HOST`;","Disabled" -"Bitbucket Server ","@backstage/plugin-scaffolder-backend-module-bitbucket-server","Backend","0.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-server-dynamic",";","Disabled" -"Bulk Import ","@red-hat-developer-hub/backstage-plugin-bulk-import","Frontend","1.10.3","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import",";","Disabled" -"Bulk Import ","@red-hat-developer-hub/backstage-plugin-bulk-import-backend","Backend","5.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic",";","Disabled" -"Datadog ","@roadiehq/backstage-plugin-datadog","Frontend","2.4.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-datadog",";","Disabled" -"Dynatrace ","@backstage-community/plugin-dynatrace","Frontend","10.0.8","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-dynatrace",";","Disabled" -"Gerrit ","@backstage/plugin-scaffolder-backend-module-gerrit","Backend","0.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gerrit-dynamic",";","Disabled" -"GitHub ","@backstage/plugin-scaffolder-backend-module-github","Backend","0.5.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic",";","Disabled" -"GitHub Actions ","@backstage-community/plugin-github-actions","Frontend","0.6.24","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-github-actions",";","Disabled" -"GitHub Insights ","@roadiehq/backstage-plugin-github-insights","Frontend","2.5.1","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-insights",";","Disabled" -"GitHub Issues ","@backstage-community/plugin-github-issues","Frontend","0.4.8","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-github-issues",";","Disabled" -"GitHub Pull Requests ","@roadiehq/backstage-plugin-github-pull-requests","Frontend","2.6.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-pull-requests",";","Disabled" -"GitLab ","@immobiliarelabs/backstage-plugin-gitlab","Frontend","6.6.1","Red Hat Tech Preview","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab",";","Disabled" -"GitLab ","@backstage/plugin-catalog-backend-module-gitlab","Backend","0.4.4","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic",";","Disabled" -"GitLab ","@immobiliarelabs/backstage-plugin-gitlab-backend","Backend","6.7.0","Red Hat Tech Preview","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic","`GITLAB_HOST`;`GITLAB_TOKEN`;","Disabled" -"GitLab ","@backstage/plugin-scaffolder-backend-module-gitlab","Backend","0.6.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gitlab-dynamic",";","Disabled" -"GitLab Org ","@backstage/plugin-catalog-backend-module-gitlab-org","Backend","0.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic",";","Disabled" -"Http Request ","@roadiehq/scaffolder-backend-module-http-request","Backend","5.0.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-http-request-dynamic",";","Disabled" -"Jenkins ","@backstage-community/plugin-jenkins","Frontend","0.12.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jenkins",";","Disabled" -"Jenkins ","@backstage-community/plugin-jenkins-backend","Backend","0.6.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jenkins-backend-dynamic","`JENKINS_URL`;`JENKINS_USERNAME`;`JENKINS_TOKEN`;","Disabled" -"JFrog Artifactory ","@backstage-community/plugin-jfrog-artifactory","Frontend","1.10.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jfrog-artifactory",";","Disabled" -"Jira ","@roadiehq/backstage-plugin-jira","Frontend","2.8.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-jira",";","Disabled" -"Kubernetes ","@backstage/plugin-kubernetes","Frontend","0.11.16","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-kubernetes",";","Disabled" -"Ldap ","@backstage/plugin-catalog-backend-module-ldap","Backend","0.9.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic",";","Disabled" -"Lighthouse ","@backstage-community/plugin-lighthouse","Frontend","0.4.24","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-lighthouse",";","Disabled" -"MS Graph ","@backstage/plugin-catalog-backend-module-msgraph","Backend","0.6.3","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic",";","Disabled" -"Nexus Repository Manager ","@backstage-community/plugin-nexus-repository-manager","Frontend","1.10.6","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-nexus-repository-manager",";","Disabled" -"Notifications ","@backstage/plugin-notifications","Frontend","0.3.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications",";","Disabled" -"Notifications ","@backstage/plugin-notifications-backend","Backend","0.4.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic",";","Disabled" -"Notifications Module Email ","@backstage/plugin-notifications-backend-module-email","Backend","0.3.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications-backend-module-email-dynamic","`EMAIL_HOSTNAME`;`EMAIL_USERNAME`;`EMAIL_PASSWORD`;`EMAIL_SENDER`;","Disabled" +"Bitbucket Cloud ","@backstage/plugin-catalog-backend-module-bitbucket-cloud","Backend","0.4.4","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-cloud-dynamic","`BITBUCKET_WORKSPACE`;","Disabled" +"Bitbucket Cloud ","@backstage/plugin-scaffolder-backend-module-bitbucket-cloud","Backend","0.2.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-cloud-dynamic",";","Disabled" +"Bitbucket Server ","@backstage/plugin-catalog-backend-module-bitbucket-server","Backend","0.3.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-server-dynamic","`BITBUCKET_HOST`;","Disabled" +"Bitbucket Server ","@backstage/plugin-scaffolder-backend-module-bitbucket-server","Backend","0.2.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-server-dynamic",";","Disabled" +"Bulk Import ","@red-hat-developer-hub/backstage-plugin-bulk-import","Frontend","1.11.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import",";","Disabled" +"Bulk Import ","@red-hat-developer-hub/backstage-plugin-bulk-import-backend","Backend","5.3.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic",";","Disabled" +"Datadog ","@roadiehq/backstage-plugin-datadog","Frontend","2.4.2","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-datadog",";","Disabled" +"Dynatrace ","@backstage-community/plugin-dynatrace","Frontend","10.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-dynatrace",";","Disabled" +"Gerrit ","@backstage/plugin-scaffolder-backend-module-gerrit","Backend","0.2.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gerrit-dynamic",";","Disabled" +"GitHub ","@backstage/plugin-scaffolder-backend-module-github","Backend","0.5.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic",";","Disabled" +"GitHub Actions ","@backstage-community/plugin-github-actions","Frontend","0.7.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-github-actions",";","Disabled" +"GitHub Insights ","@roadiehq/backstage-plugin-github-insights","Frontend","3.1.3","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-insights",";","Disabled" +"GitHub Issues ","@backstage-community/plugin-github-issues","Frontend","0.6.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-github-issues",";","Disabled" +"GitHub Pull Requests ","@roadiehq/backstage-plugin-github-pull-requests","Frontend","3.2.1","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-pull-requests",";","Disabled" +"GitLab ","@immobiliarelabs/backstage-plugin-gitlab","Frontend","6.8.0","Red Hat Tech Preview","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab",";","Disabled" +"GitLab ","@backstage/plugin-catalog-backend-module-gitlab","Backend","0.6.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic",";","Disabled" +"GitLab ","@immobiliarelabs/backstage-plugin-gitlab-backend","Backend","6.8.0","Red Hat Tech Preview","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic","`GITLAB_HOST`;`GITLAB_TOKEN`;","Disabled" +"GitLab ","@backstage/plugin-scaffolder-backend-module-gitlab","Backend","0.7.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gitlab-dynamic",";","Disabled" +"GitLab Org ","@backstage/plugin-catalog-backend-module-gitlab-org","Backend","0.2.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic",";","Disabled" +"Http Request ","@roadiehq/scaffolder-backend-module-http-request","Backend","5.3.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-http-request-dynamic",";","Disabled" +"Jenkins ","@backstage-community/plugin-jenkins","Frontend","0.16.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jenkins",";","Disabled" +"Jenkins ","@backstage-community/plugin-jenkins-backend","Backend","0.11.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jenkins-backend-dynamic","`JENKINS_URL`;`JENKINS_USERNAME`;`JENKINS_TOKEN`;","Disabled" +"JFrog Artifactory ","@backstage-community/plugin-jfrog-artifactory","Frontend","1.13.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-jfrog-artifactory",";","Disabled" +"Jira ","@roadiehq/backstage-plugin-jira","Frontend","2.8.2","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-jira",";","Disabled" +"Kubernetes ","@backstage/plugin-kubernetes","Frontend","0.12.3","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-kubernetes",";","Disabled" +"Ldap ","@backstage/plugin-catalog-backend-module-ldap","Backend","0.11.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic",";","Disabled" +"Lighthouse ","@backstage-community/plugin-lighthouse","Frontend","0.6.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-lighthouse",";","Disabled" +"Marketplace ","@red-hat-developer-hub/backstage-plugin-marketplace","Frontend","0.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace",";","Enabled" +"Marketplace ","@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace","Backend","0.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic",";","Enabled" +"Marketplace ","@red-hat-developer-hub/backstage-plugin-marketplace-backend","Backend","0.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic",";","Enabled" +"MS Graph ","@backstage/plugin-catalog-backend-module-msgraph","Backend","0.6.6","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic",";","Disabled" +"Nexus Repository Manager ","@backstage-community/plugin-nexus-repository-manager","Frontend","1.12.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-nexus-repository-manager",";","Disabled" +"Notifications ","@backstage/plugin-notifications","Frontend","0.5.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications",";","Disabled" +"Notifications ","@backstage/plugin-notifications-backend","Backend","0.5.1","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic",";","Disabled" +"Notifications Module Email ","@backstage/plugin-notifications-backend-module-email","Backend","0.3.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-notifications-backend-module-email-dynamic","`EMAIL_HOSTNAME`;`EMAIL_USERNAME`;`EMAIL_PASSWORD`;`EMAIL_SENDER`;","Disabled" "PagerDuty ","@pagerduty/backstage-plugin","Frontend","0.15.2","Red Hat Tech Preview","./dynamic-plugins/dist/pagerduty-backstage-plugin",";","Disabled" "PagerDuty ","@pagerduty/backstage-plugin-backend","Backend","0.9.2","Red Hat Tech Preview","./dynamic-plugins/dist/pagerduty-backstage-plugin-backend-dynamic","`PAGERDUTY_API_BASE`;`PAGERDUTY_CLIENT_ID`;`PAGERDUTY_CLIENT_SECRET`;`PAGERDUTY_SUBDOMAIN`;","Disabled" -"Pingidentity ","@backstage-community/plugin-catalog-backend-module-pingidentity","Backend","0.1.5","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-pingidentity-dynamic",";","Disabled" -"Scaffolder Relation Processor ","@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor","Backend","2.0.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic",";","Disabled" -"Security Insights ","@roadiehq/backstage-plugin-security-insights","Frontend","2.4.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-security-insights",";","Disabled" -"ServiceNow ","@backstage-community/plugin-scaffolder-backend-module-servicenow","Backend","2.2.3","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-servicenow-dynamic","`SERVICENOW_BASE_URL`;`SERVICENOW_USERNAME`;`SERVICENOW_PASSWORD`;","Disabled" -"Signals ","@backstage/plugin-signals","Frontend","0.0.11","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-signals",";","Disabled" -"SonarQube ","@backstage-community/plugin-sonarqube","Frontend","0.8.7","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-sonarqube",";","Disabled" -"SonarQube ","@backstage-community/plugin-sonarqube-backend","Backend","0.3.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-sonarqube-backend-dynamic","`SONARQUBE_URL`;`SONARQUBE_TOKEN`;","Disabled" -"SonarQube ","@backstage-community/plugin-scaffolder-backend-module-sonarqube","Backend","2.2.2","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-sonarqube-dynamic",";","Disabled" -"Tech Radar ","@backstage-community/plugin-tech-radar","Frontend","1.0.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-tech-radar",";","Disabled" -"Tech Radar ","@backstage-community/plugin-tech-radar-backend","Backend","1.0.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic","`TECH_RADAR_DATA_URL`;","Disabled" -"Utils ","@roadiehq/scaffolder-backend-module-utils","Backend","3.0.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-utils-dynamic",";","Disabled" +"Pingidentity ","@backstage-community/plugin-catalog-backend-module-pingidentity","Backend","0.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-pingidentity-dynamic",";","Disabled" +"Scaffolder Relation Processor ","@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor","Backend","2.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic",";","Disabled" +"Security Insights ","@roadiehq/backstage-plugin-security-insights","Frontend","3.1.2","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-backstage-plugin-security-insights",";","Disabled" +"ServiceNow ","@backstage-community/plugin-scaffolder-backend-module-servicenow","Backend","2.4.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-servicenow-dynamic","`SERVICENOW_BASE_URL`;`SERVICENOW_USERNAME`;`SERVICENOW_PASSWORD`;","Disabled" +"Signals ","@backstage/plugin-signals","Frontend","0.0.15","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-plugin-signals",";","Disabled" +"SonarQube ","@backstage-community/plugin-sonarqube","Frontend","0.10.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-sonarqube",";","Disabled" +"SonarQube ","@backstage-community/plugin-sonarqube-backend","Backend","0.5.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-sonarqube-backend-dynamic","`SONARQUBE_URL`;`SONARQUBE_TOKEN`;","Disabled" +"SonarQube ","@backstage-community/plugin-scaffolder-backend-module-sonarqube","Backend","2.4.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-sonarqube-dynamic",";","Disabled" +"Tech Radar ","@backstage-community/plugin-tech-radar","Frontend","1.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-tech-radar",";","Disabled" +"Tech Radar ","@backstage-community/plugin-tech-radar-backend","Backend","1.2.0","Red Hat Tech Preview","./dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic","`TECH_RADAR_DATA_URL`;","Disabled" +"Utils ","@roadiehq/scaffolder-backend-module-utils","Backend","3.3.0","Red Hat Tech Preview","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-utils-dynamic",";","Disabled" +"Argo CD ","@roadiehq/backstage-plugin-argo-cd","Frontend","2.8.4","Community Support","./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd",";","Disabled" +"Global Floating Action Button ","@red-hat-developer-hub/backstage-plugin-global-floating-action-button","Frontend","1.0.0","Community Support","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button",";","Enabled" diff --git a/modules/dynamic-plugins/rhdh-supported-plugins.sh b/modules/dynamic-plugins/rhdh-supported-plugins.sh index 06120df7ef..fbe831c5ad 100755 --- a/modules/dynamic-plugins/rhdh-supported-plugins.sh +++ b/modules/dynamic-plugins/rhdh-supported-plugins.sh @@ -325,7 +325,7 @@ for d in ref-rh-supported-plugins ref-rh-tech-preview-plugins ref-community-plug this_num_plugins=${num_plugins[$index]} echo "[$count] Processing $d ..." adocfile="${0/.sh/.${d}}" - sed -e "/%%TABLE_CONTENT_${count}%%/{r $adocfile" -e 'd}' \ + sed -e "/%%TABLE_CONTENT_${count}%%/{r $adocfile" -e 'd;}' \ -e "s/\%\%COUNT_${count}\%\%/$this_num_plugins/" \ "${0/rhdh-supported-plugins.sh/${d}.template.adoc}" > "${0/rhdh-supported-plugins.sh/${d}.adoc}" rm -f "$adocfile" @@ -333,7 +333,7 @@ for d in ref-rh-supported-plugins ref-rh-tech-preview-plugins ref-community-plug done # inject ENABLED_PLUGINS into con-preinstalled-dynamic-plugins.template.adoc -sed -e "/%%ENABLED_PLUGINS%%/{r $ENABLED_PLUGINS" -e 'd}' \ +sed -e "/%%ENABLED_PLUGINS%%/{r $ENABLED_PLUGINS" -e 'd;}' \ "${0/rhdh-supported-plugins.sh/con-preinstalled-dynamic-plugins.template.adoc}" > "${0/rhdh-supported-plugins.sh/con-preinstalled-dynamic-plugins.adoc}" # summary of changes since last time diff --git a/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc b/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc index 124317ae2c..9f3bc6f80f 100644 --- a/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc +++ b/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc @@ -21,7 +21,7 @@ plugins: disabled: false ---- + -See link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}]. +See link:{installing-and-viewing-plugins-book-url}[{installing-and-viewing-plugins-book-title}]. . Configure the required `bulk.import` RBAC permission for the users who are not administrators as follows: + diff --git a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc b/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc index 9172d9e4c6..65f32d7b58 100644 --- a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc +++ b/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc @@ -73,16 +73,16 @@ data: The `backstage-plugin-kubernetes` plugin is currently in link:https://access.redhat.com/support/offerings/techpreview[Technology Preview]. As an alternative, you can use the `./dynamic-plugins/dist/backstage-plugin-topology-dynamic` plugin, which is Generally Available (GA). ==== -. Set the kubernetes cluster details and configure the catalog sync options in the `app-config-rhdh.yaml` file: +. Set the Kubernetes cluster details and configure the catalog sync options in the link:{configuring-book-url}[`{my-app-config-file}` configuration file]. + -[source,yaml] +[source,yaml,subs="+attributes"] ---- kind: ConfigMap apiVersion: v1 metadata: - name: app-config-rhdh + name: {my-app-config-config-map} data: - "app-config-rhdh.yaml": | + "{my-app-config-file}": | # ...   catalog:     rules: @@ -119,8 +119,8 @@ data: <1> The base URL to the Kubernetes control plane. You can run the `kubectl cluster-info` command to get the base URL. <2> Set the value of this parameter to `false` to enable the verification of the TLS certificate. <3> Optional: The link to the Kubernetes dashboard managing the ARO cluster. -<4> Optional: Pass the service account token using a `K8S_SERVICE_ACCOUNT_TOKEN` environment variable that you can define in your `my-rhdh-secrets` secret. -<5> Pass the CA data using a `K8S_CONFIG_CA_DATA` environment variable that you can define in your `my-rhdh-secrets` secret. +<4> Optional: Pass the service account token using a `K8S_SERVICE_ACCOUNT_TOKEN` environment variable that you define in your `_<my_product_secrets>_` secret. +<5> Pass the CA data using a `K8S_CONFIG_CA_DATA` environment variable that you define in your `_<my_product_secrets>_` secret. . Save the configuration changes. diff --git a/modules/installation/proc-deploy-rhdh-instance-eks.adoc b/modules/installation/proc-deploy-rhdh-instance-eks.adoc index 8f4646deb6..25a272fad6 100644 --- a/modules/installation/proc-deploy-rhdh-instance-eks.adoc +++ b/modules/installation/proc-deploy-rhdh-instance-eks.adoc @@ -17,7 +17,7 @@ .Procedure -. Create a ConfigMap named `app-config-rhdh` containing the {product-short} configuration using the following template: +. Create a `{my-app-config-config-map}` config map containing the `{my-app-config-file}` {product-short} configuration file by using the following template: + -- [source,yaml,subs="attributes+"] @@ -25,9 +25,9 @@ apiVersion: v1 kind: ConfigMap metadata: - name: app-config-rhdh + name: {my-app-config-config-map} data: - "app-config-rhdh.yaml": | + "{my-app-config-file}": | app: title: {product} baseUrl: https://<rhdh_dns_name> @@ -44,7 +44,7 @@ data: ---- -- -. Create a Secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value: +. Create a {product} secret and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value: + -- [source,yaml,subs="+attributes,+quotes"] @@ -52,11 +52,12 @@ data: apiVersion: v1 kind: Secret metadata: - name: {my-product-secrets} + name: `_<my_product_secrets>_` <1> stringData: # TODO: See https://backstage.io/docs/auth/service-to-service-auth/#setup BACKEND_SECRET: "xxx" ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the unique identifier for your secret configuration within {product-short}. [IMPORTANT] ==== @@ -100,11 +101,12 @@ spec: enabled: false appConfig: configMaps: - - name: "app-config-rhdh" + - name: {my-app-config-config-map} extraEnvs: secrets: - - name: {my-product-secrets} + - name: `_<my_product_secrets>_` <1> ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the identifier for your secret configuration within {product-short}. -- . Create an Ingress resource using the following template, ensuring to customize the names as needed: diff --git a/modules/installation/proc-deploy-rhdh-instance-gke.adoc b/modules/installation/proc-deploy-rhdh-instance-gke.adoc index d50e9cc611..c3439bd13c 100644 --- a/modules/installation/proc-deploy-rhdh-instance-gke.adoc +++ b/modules/installation/proc-deploy-rhdh-instance-gke.adoc @@ -17,18 +17,18 @@ You need to create an `A` record with the value equal to the IP address. This pr ==== .Procedure -. Create a ConfigMap named `app-config-rhdh` containing the {product-short} configuration using the following template: +. Create a `{my-app-config-file}` config map containing the `{my-app-config-file}` {product-short} configuration file by using the following template: + -- -.`app-config-rhdh.yaml` fragment +.`{my-app-config-file}` fragment [source,yaml,subs="attributes+"] ---- apiVersion: v1 kind: ConfigMap metadata: - name: app-config-rhdh + name: {my-app-config-config-map} data: - "app-config-rhdh.yaml": | + "{my-app-config-file}": | app: title: Red Hat Developer Hub baseUrl: https://<rhdh_domain_name> @@ -45,20 +45,20 @@ data: ---- -- -. Create a Secret named `my-rhdh-secrets` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value: +. Create a `_<my_product_secrets>_` secret and add a key named `BACKEND_SECRET` with a `Base64-encoded` string value as shown in the following example: + -- -.`my-rhdh-secrets` fragment -[source,yaml] +[source,yaml,subs="+quotes,+attributes"] ---- apiVersion: v1 kind: Secret metadata: - name: my-rhdh-secrets + name: `_<my_product_secrets>_` <1> stringData: # TODO: See https://backstage.io/docs/auth/service-to-service-auth/#setup BACKEND_SECRET: "xxx" ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the identifier for your secret configuration within {product-short}. [IMPORTANT] ==== @@ -88,7 +88,7 @@ kubectl patch serviceaccount default \ + -- .Custom resource fragment -[source,yaml,subs="attributes+"] +[source,yaml,subs="+quotes,+attributes"] ---- apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage @@ -103,17 +103,17 @@ spec: enabled: false appConfig: configMaps: - - name: "app-config-rhdh" + - name: {my-app-config-config-map} extraEnvs: secrets: - - name: "my-rhdh-secrets" + - name: `_<my_product_secrets>_` <1> ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the identifier for your secret configuration within {product-short}. -- -. Set up a Google-managed certificate by creating a `ManagedCertificate` object which you must attach to the Ingress. +. Set up a Google-managed certificate by creating a `ManagedCertificate` object which you must attach to the Ingress as shown in the following example: + -- -.Example of a `ManagedCertificate` object [source,yaml,subs="attributes+"] ---- apiVersion: networking.gke.io/v1 diff --git a/modules/installation/proc-install-operator.adoc b/modules/installation/proc-install-operator.adoc index 884b2000fa..bae5470a1e 100644 --- a/modules/installation/proc-install-operator.adoc +++ b/modules/installation/proc-install-operator.adoc @@ -5,13 +5,7 @@ [id="proc-install-operator_{context}"] = Installing the {product} Operator -As an administrator, you can install the {product} Operator. Authorized users can use the Operator to install {product} on the following platforms: - -* {ocp-brand-name} ({ocp-short}) -* {eks-brand-name} ({eks-short}) -* {aks-brand-name} ({aks-short}) - -For more information on {ocp-short} supported versions, see the link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle]. +As an administrator, you can install the {product} Operator. Authorized users can use the Operator to install {product} on {ocp-brand-name} ({ocp-short}) and supported Kubernetes platforms. For more information on supported platforms and versions, see the link:https://access.redhat.com/support/policy/updates/developerhub[{product} Life Cycle] page. Containers are available for the following CPU architectures: diff --git a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc b/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc deleted file mode 100644 index a6f8214802..0000000000 --- a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// no assembly - -[id="proc-install-rhdh-airgapped-environment-ocp-helm_{context}"] -= Installing {product} in an air-gapped environment with the Helm Chart - -An air-gapped environment, also known as an air-gapped network or isolated network, ensures security by physically segregating the system or network. This isolation is established to prevent unauthorized access, data transfer, or communication between the air-gapped system and external sources. - -You can install {product} in an air-gapped environment to ensure security and meet specific regulatory requirements. - -To install {product-short} in an air-gapped environment, you must have access to the `registry.redhat.io` and the registry for the air-gapped environment. - -.Prerequisites - -* You have installed an {ocp-brand-name} {ocp-version-min} or later. -* You have access to the `registry.redhat.io`. -* You have access to the {ocp-brand-name} image registry of your cluster. For more information about exposing the image registry, see the {ocp-brand-name} documentation about https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. -* You have installed the {openshift-cli} on your workstation. -* You have installed the `podman` command line tools on your workstation. -* You you have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. - -.Procedure - -. Log in to your {ocp-short} account using the {openshift-cli}, by running the following command: -+ -[source,terminal] ----- -oc login -u <user> -p <password> https://api.<hostname>:6443 ----- - -. Log in to the {ocp-short} image registry using the `podman` command line tool, by running the following command: -+ -[source,terminal] ----- -podman login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.<hostname> ----- -+ -[NOTE] -==== -You can run the following commands to get the full host name of the {ocp-short} image registry, and then use the host name in a command to log in: - -[source,terminal] ----- -REGISTRY_HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}') ----- - -[source,terminal] ----- -podman login -u kubeadmin -p $(oc whoami -t) $REGISTRY_HOST ----- -==== - -. Log in to the `registry.redhat.io` in `podman` by running the following command: -+ -[source,terminal] ----- -podman login registry.redhat.io ----- -+ -For more information about registry authentication, see https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. - -. Pull {product-short} and PostgreSQL images from https://catalog.redhat.com/software/containers/search[{company-name} Image registry] to your workstation, by running the following commands: -+ -[source,terminal,source,subs="attributes+"] ----- -podman pull registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-version} ----- -+ -[source,terminal,source,subs="attributes+"] ----- -podman pull registry.redhat.io/rhel9/postgresql-15:latest ----- - -. Push both images to the internal {ocp-short} image registry by running the following commands: -+ -[source,terminal,source,subs="attributes+"] ----- -podman push --remove-signatures registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-version} default-route-openshift-image-registry.<hostname>/<project_name>/rhdh-hub-rhel9:{product-version} ----- -+ -[source,terminal] ----- -podman push --remove-signatures registry.redhat.io/rhel9/postgresql-15:latest default-route-openshift-image-registry.<hostname>/<project_name>/postgresql-15:latest ----- -+ -For more information about pushing images directly to the {ocp-short} image registry, see https://access.redhat.com/solutions/6959306[How do I push an Image directly into the OpenShift 4 registry]. -+ -[IMPORTANT] -==== -If an x509 error occurs, verify that you have link:https://access.redhat.com/solutions/6088891[installed the CA certificate used for {ocp-short} routes on your system]. -==== - -. Use the following command to verify that both images are present in the internal {ocp-short} registry: -+ -[source,terminal] ----- -oc get imagestream -n {my-product-namespace} ----- - -. Enable local image lookup for both images by running the following commands: -+ -[source,terminal] ----- -oc set image-lookup postgresql-15 ----- -+ -[source,terminal] ----- -oc set image-lookup rhdh-hub-rhel9 ----- - -. Go to *YAML view* and update the `image` section for `backstage` and `postgresql` using the following values: -+ --- -.Example values for Developer Hub image -[source,yaml] ----- -upstream: - backstage: - image: - registry: "" - repository: rhdh-hub-rhel9 - tag: latest ----- - -.Example values for PostgreSQL image -[source,yaml] ----- -upstream: - postgresql: - image: - registry: "" - repository: postgresql-15 - tag: latest ----- --- - -. Install the {product} using Helm chart. diff --git a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-operator.adoc b/modules/installation/proc-install-rhdh-airgapped-environment-ocp-operator.adoc deleted file mode 100644 index 815c61bd3a..0000000000 --- a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-operator.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// no assembly - -:_mod-docs-content-type: PROCEDURE -[id="proc-install-rhdh-airgapped-environment-ocp-operator_{context}"] -= Installing {product} in an air-gapped environment with the Operator - -On an {ocp-short} cluster operating on a restricted network, public resources are not available. However, deploying the {product} Operator and running {product-short} requires the following public resources: - -* Operator images (bundle, operator, catalog) -* Operands images ({product-very-short}, PostgreSQL) - -To make these resources available, replace them with their equivalent resources in a mirror registry accessible to the {ocp-short} cluster. - -You can use a helper script that mirrors the necessary images and provides the necessary configuration to ensure those images will be used when installing the {product} Operator and creating {product-short} instances. - -[NOTE] -==== -This script requires a target mirror registry which you should already have installed if your {ocp-short} cluster is ready to operate on a restricted network. However, if you are preparing your cluster for disconnected usage, you can use the script to deploy a mirror registry in the cluster and use it for the mirroring process. -==== - -.Prerequisites -* You have an active {openshift-cli} session with administrative permissions to the {ocp-short} cluster. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-getting-started[Getting started with the OpenShift CLI]. -* You have an active `oc registry` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. See link:https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. -* The `opm` CLI tool is installed. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#olm-about-opm_cli-opm-install[Installing the opm CLI]. -* The jq package is installed. See link:https://jqlang.github.io/jq/download/[Download jq]. -* Podman is installed. See link:https://podman.io/docs/installation[Podman Installation Instructions]. -* Skopeo version 1.14 or higher is installed. link:https://github.com/containers/skopeo/blob/main/install.md[See Installing Skopeo]. -* If you already have a mirror registry for your cluster, an active Skopeo session with administrative access to this registry is required. See link:https://github.com/containers/skopeo#authenticating-to-a-registry[Authenticating to a registry] and link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/disconnected_installation_mirroring/index#prerequisites_installing-mirroring-installation-images[Mirroring images for a disconnected installation]. - -[NOTE] -==== -The internal {ocp-short} cluster image registry cannot be used as a target mirror registry. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/disconnected_installation_mirroring/index#installation-about-mirror-registry_installing-mirroring-installation-images[About the mirror registry]. -==== - -* If you prefer to create your own mirror registry, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/disconnected_installation_mirroring/index#installing-mirroring-creating-registry[Creating a mirror registry with mirror registry for Red Hat OpenShift]. - -* If you do not already have a mirror registry, you can use the helper script to create one for you and you need the following additional prerequisites: -+ -** The cURL package is installed. For {rhel}, the curl command is available by installing the curl package. To use curl for other platforms, see the link:https://curl.se/[cURL website]. -** The `htpasswd` command is available. For {rhel}, the `htpasswd` command is available by installing the `httpd-tools` package. - -.Procedure -. Download and run the mirroring script to install a custom Operator catalog and mirror the related images: `prepare-restricted-environment.sh` (link:https://github.com/redhat-developer/rhdh-operator/blob/release-{product-version}/.rhdh/scripts/prepare-restricted-environment.sh[source]). -+ -[source,yaml,subs="attributes+"] ----- -curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/{product-version}.x/.rhdh/scripts/prepare-restricted-environment.sh - -# if you do not already have a target mirror registry -# and want the script to create one for you -# use the following example: -bash prepare-restricted-environment.sh \ - --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v{ocp-version}" \ - --prod_operator_package_name "rhdh" \ - --prod_operator_bundle_name "rhdh-operator" \ - --prod_operator_version "v{product-bundle-version}" - -# if you already have a target mirror registry -# use the following example: -bash prepare-restricted-environment.sh \ - --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v{ocp-version}" \ - --prod_operator_package_name "rhdh" \ - --prod_operator_bundle_name "rhdh-operator" \ - --prod_operator_version "v{product-bundle-version}" \ - --use_existing_mirror_registry "my_registry" ----- -+ -[NOTE] -==== -The script can take several minutes to complete as it copies multiple images to the mirror registry. -==== diff --git a/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc b/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc new file mode 100644 index 0000000000..5ad3a6b9b5 --- /dev/null +++ b/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc @@ -0,0 +1,149 @@ +[id="proc-install-rhdh-helm-airgapped-full.adoc_{context}"] += Installing {product} on {ocp-short} in a fully disconnected environment with the Helm chart + +If your network has access to the registry through a bastion host, you can use the Helm chart to install {product} by mirroring specified resources to disk and transferring them to your air-gapped environment without any connection to the internet. + +.Prerequisites + +* You have set up your workstation. +** You have access to the registry.redhat.io. +** You have access to the charts.openshift.io Helm chart repository. +** You have installed the {openshift-cli} on your workstation. +** You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin]. +** You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. +* You have set up your intermediary host. +** Your host has access to the disconnected cluster and to the target mirror registry, for example, the {ocp-brand-name} image registry. For more information about exposing the {ocp-short} image registry, see https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. +** You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin]. +** You have installed {ocp-brand-name} {ocp-version-min} or later. +** You have installed the {openshift-cli} on your workstation. + +.Procedure +. Create an `ImageSetConfiguration` file to specify the resources that you want to mirror. For example: ++ +[source,terminal,subs="+quotes"] +---- +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + helm: + repositories: + - name: _<repository_name>_ (1) + url: _<repository_url>_ (2) + charts: + - name: _<chart_name>_ (3) + version: "_<rhdh_version>_" (4) +---- +<1> The name of the repository that you want to mirror, for example, `openshift-charts`. +<2> The URL for the repository that you want to mirror, for example, `https://charts.openshift.io`. +<3> The name of the Helm chart that you want to mirror, for example, `redhat-developer-hub`. +<4> The version of {product} that you want to use, for example, `{product-version}` + +. Mirror the resources specified in the `ImageSetConfiguration.yaml` file by running the `oc-mirror` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +oc-mirror --config=_<mirror_config_directory>_/ImageSetConfiguration.yaml _<mirror_archive_directory>_/ +---- ++ +-- +where: + +`<mirror_config_directory>` :: Specifies the location of your image set configuration file on your system, for example, `.user`. + +`<mirror_configuration_file>` :: Specifies the name of your mirror configuration yaml file, for example, `mirror-config.yaml` + +`<mirror_archive_directory>` :: Specifies the location of your directory where the mirror archive will be created, for example,`file://.user`. +-- ++ +[NOTE] +==== +Running the `oc-mirror` command generates a local workspace containing the mirror archive file, the Helm chart, and a `ImageContentSourcePolicy` (ICSP) manifest. The ICSP manifest contains an `imageContentSourcePolicy.yaml` file that you must apply against the cluster in a later step. +==== ++ +.Example output +[source,terminal,subs="+quotes"] +---- +Creating archive /path/to/mirror-archive/mirror_seq1_000000.tar +---- ++ +. Transfer the generated archive file (for example, `mirror_seq1_000000.tar`) to the air-gapped environment. +. Connect to your air-gapped environment and make sure that you are also connected to the following objects: ++ +* The local target registry +* The target {ocp-short} cluster ++ +. From your air-gapped environment, mirror the resources from the archive to the target registry by running the `oc-mirror` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +oc-mirror --from _<mirror-archive-file>_ _<target-registry>_ +---- ++ +-- +where: + +`<mirror_archive_file>` :: Specifies the name of the file containing the resources that you want to mirror, for example,`mirror_seq1_0000.tar`. + +`<target_registry>` :: Specifies the name of the target registry that you want to push the mirrored images to, for example, `docker://registry.localhost:5000`. +-- ++ +.Example output +[source,terminal,subs="+quotes"] +---- +Wrote release signatures to oc-mirror-workspace/results-1738075410 +Writing image mapping to oc-mirror-workspace/results-1738075410/mapping.txt +Writing ICSP manifests to oc-mirror-workspace/results-1738075410 +---- ++ +. In your workspace, locate the `imageContentSourcePolicy.yaml` file by running the `ls` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +ls _<workspace_directory>_/_<results_directory>_ +---- ++ +-- +where: + +`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. +-- ++ +. To mirror the Helm chart, deploy the `imageContentSourcePolicy.yaml` file in the disconnected cluster by running the `oc apply` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +oc apply -f _<workspace_directory>_/_<results_directory>_/ImageContentSourcePolicy.yaml +---- ++ +-- +where: + +`<workspace-directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results-directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. +-- +. In your air-gapped environment, deploy the Helm chart to the namespace that you want to use by running the `helm install` command with `namespace` and `set` options. For example: ++ +[source,terminal,subs="+quotes"] +---- +CLUSTER_ROUTER_BASE=$(oc get route console -n openshift-console -o=jsonpath='{.spec.host}' | sed 's/^[^.]*\.//') + +helm install _<rhdh_instance>_ _<workspace_directory>_/_<results_directory>_/charts/_<archive_file>_ --namespace _<your_namespace>_ --create-namespace \ + --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE" +---- ++ +-- +where: + +`<rhdh_instance>` :: Specifies the name of your {product} instance, for example, `my-rhdh`. + +`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. + +`<archive_file>` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. + +`<your_namespace>` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`. +-- \ No newline at end of file diff --git a/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc b/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc new file mode 100644 index 0000000000..f6d75e2634 --- /dev/null +++ b/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc @@ -0,0 +1,125 @@ +[id="proc-install-rhdh-helm-airgapped-partial.adoc_{context}"] += Installing {product} on {ocp-short} in a partially disconnected environment with the Helm chart + +If your network has access to the `registry.redhat.io` registry and the `charts.openshift.io` Helm chart repository, you can deploy your {product} instance in your partially disconnected environment by mirroring the specified resources directly to the target registry. + +.Prerequisites + +* You have installed {ocp-brand-name} {ocp-version-min} or later. +* You have access to the `charts.openshift.io` Helm chart repository. +* You have access to the `registry.redhat.io`. +* You have access to a mirror registry that can be reached from the disconnected cluster, for example, the {ocp-short} image registry. For more information about exposing the {ocp-short} image registry, see https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. +* You are logged in to your target mirror registry and have permissions to push images to it. For more information, see link:https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored]. +* You have installed the {openshift-cli} on your workstation. +* You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin]. +* You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. + +.Procedure +. Log in to your {ocp-short} account using the {openshift-cli} by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +oc login -u <user> -p <password> https://api.<hostname>:6443 +---- + +. From your disconnected cluster, log in to the image registry that you want to mirror, for example, the {ocp-short} image registry. +. Create an `ImageSetConfiguration.yaml` file. +. In your `ImageSetConfiguration.yaml` file, specify the resources that you want to mirror. For example: ++ +[source,terminal,subs="+quotes"] +---- +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + helm: + repositories: + - name: _<repository_name>_ (1) + url: _<repository_url>_ (2) + charts: + - name: _<chart_name>_ (3) + version: "_<rhdh_version>_" (4) +---- +<1> The name of the repository containing the Helm chart that you want to mirror, for example, `openshift-charts`. +<2> The URL for the repository containing the Helm chart that you want to mirror, for example, `https://charts.openshift.io`. +<3> The name of the Helm chart containing the images that you want to mirror, for example, `redhat-developer-hub`. +<4> The {product} version that you want to use, for example, `{product-version}` + +. Mirror the resources specified in the image set configuration file directly to the target registry by running the `oc-mirror` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +oc-mirror --config=_<mirror_config_directory>_/ImageSetConfiguration.yaml _<target-mirror-registry>_ +---- ++ +-- +where: + +`<mirror_config_directory>` :: Specifies the location of your image set configuration file on your system, for example, `.user`. + +`<target_mirror_registry>` :: Specifies the location and name of your target mirror registry, for example,`docker://registry.example:5000`. +-- ++ +[NOTE] +==== +Running the `oc-mirror` command creates a local workspace containing the Helm chart and a `ImageContentSourcePolicy` (ICSP) manifest. The ICSP manifest contains an automatically-generated `imageContentSourcePolicy.yaml` file that you must apply against the cluster in a later step. +==== ++ +.Example output +[source,terminal,subs="+quotes"] +---- +Writing image mapping to oc-mirror-workspace/results-1738070846/mapping.txt +Writing ICSP manifests to oc-mirror-workspace/results-1738070846 +---- ++ +. In your workspace, locate the `imageContentSourcePolicy.yaml` file by running the `ls` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +ls _<workspace_directory>_/_<results_directory>_ +---- ++ +-- +where: + +`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. +-- ++ +. To mirror the Helm chart, deploy the `imageContentSourcePolicy.yaml` file in the disconnected cluster by running the `oc apply` command. For example: ++ +[source,terminal,subs="+quotes"] +---- +oc apply -f _<workspace_directory>_/_<results_directory>_/`ImageContentSourcePolicy.yaml` +---- ++ +-- +where: + +`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. +-- +. In your air-gapped environment, deploy the Helm chart to the namespace that you want to use by running the `helm install` command with `namespace` and `set` options. For example: ++ +[source,terminal,subs="+quotes"] +---- +CLUSTER_ROUTER_BASE=$(oc get route console -n openshift-console -o=jsonpath='{.spec.host}' | sed 's/^[^.]*\.//') + +helm install _<rhdh_instance>_ _<workspace_directory>_/_<results_directory>_/charts/_<archive_file>_ --namespace _<your_namespace>_ --create-namespace \ + --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE" +---- ++ +-- +where: + +`<rhdh_instance>` :: Specifies the name of your {product} instance, for example, `my-rhdh`. + +`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`. + +`<archive_file>` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. + +`<your_namespace>` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`. +-- \ No newline at end of file diff --git a/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc b/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc new file mode 100644 index 0000000000..aacb27585d --- /dev/null +++ b/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc @@ -0,0 +1,84 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-install-rhdh-operator-airgapped-full.adoc_{context}"] += Installing {product} in a fully disconnected environment with the Operator + +In environments without internet access — whether for security, compliance, or operational reasons — a fully disconnected installation ensures that {product} can run reliably without external dependencies. + +If your network has access to the registry through a bastion host, you can use the helper script to install {product} by mirroring the Operator-related images to disk and transferring them to your air-gapped environment without any connection to the internet. + +.Prerequisites + +* You have installed Podman 5.3 or later. For more information, see link:https://podman.io/docs/installation[Podman Installation Instructions]. +* You have installed Skopeo 1.17 or later. +* You have installed `yq` 4.44 or later. +* You have installed the GNU `sed` command line text editor. +* You have installed `umoci` CLI tool. +* You have an active `oc registry`, `podman`, or `skopeo` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. For more information, see link:https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. +* You have installed the `opm` CLI tool. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/cli_tools/opm-cli#olm-about-opm_cli-opm-install[Installing the opm CLI]. + +.Procedure +. Download the mirroring script to disk by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-{product-version}/.rhdh/scripts/prepare-restricted-environment.sh +---- ++ +. Run the mirroring script by using the `bash` command with the appropriate set of options: ++ +[source,terminal,subs="attributes+"] +---- +bash prepare-restricted-environment.sh + --filter-versions "{product-version}" + --to-dir _<my_pulled_image_location>_ <1> + [--use-oc-mirror true] <2> +---- +<1> Specifies the absolute path to a directory where you want to pull all of the necessary images with the `--to-dir` option, for example, `/home/user/rhdh-operator-mirror-dir`. +<2> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. ++ +[NOTE] +==== +The script can take several minutes to complete as it copies multiple images to the mirror registry. +==== ++ +. Transfer the directory specified by the `--to-dir` option to your disconnected environment. +. From a machine in your disconnected environment that has access to both the cluster and the target mirror registry, run the mirroring script by using the `bash` command with the appropriate set of options: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +bash _<my_pulled_image_location>_/install.sh <1> + --from-dir _<my_pulled_image_location>_ <2> + [--to-registry _<my.registry.example.com>_] <3> + [--use-oc-mirror true] <4> +---- +<1> The downloaded image and the absolute path to the directory where it is stored on your system. +<2> Specifies the directory where you want to pull all of the necessary images with the `--to-dir` option. +<3> Specifies the URL for the target mirror registry where you want to mirror the images. +<4> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. ++ +[IMPORTANT] +==== +If you used `oc-mirror` to mirror the images to disk, you must also use `oc-mirror` to mirror the images from disk due to the folder layout that `oc-mirror` uses. +==== ++ +[NOTE] +==== +The script can take several minutes to complete as it automatically installs the {product} Operator. +==== + +.Verification +* If you are using {ocp-brand-name}, the {product} Operator is in the *Installed Operators* list in the web console. +* If you are using a supported Kubernetes platform, you can check the list of pods running in the `rhdh-operator` namespace by running the following command in your terminal: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +kubectl -n rhdh-operator get pods +---- + +.Next steps +* Use the Operator to create a {product} instance on a supported platform. For more information, see the following documentation for the platform that you want to use: +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_container_platform/assembly-install-rhdh-ocp-operator[Installing {product} on {ocp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_amazon_elastic_kubernetes_service/proc-rhdh-deploy-eks-operator_title-install-rhdh-eks[Installing {product-short} on {eks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_microsoft_azure_kubernetes_service/proc-rhdh-deploy-aks-operator_title-install-rhdh-aks[Installing {product-short} on {aks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_dedicated_on_google_cloud_platform/proc-install-rhdh-osd-gcp-operator_title-install-rhdh-osd-gcp[Installing {product-short} on {gcp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_google_kubernetes_engine/proc-rhdh-deploy-gke-operator.adoc_title-install-rhdh-gke#proc-deploy-rhdh-instance-gke.adoc_title-install-rhdh-gke[Deploying {product-short} on {gke-short} with the Operator] diff --git a/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc b/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc new file mode 100644 index 0000000000..725af137f8 --- /dev/null +++ b/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc @@ -0,0 +1,72 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-install-rhdh-operator-airgapped-partial.adoc_{context}"] += Installing {product} in a partially disconnected environment with the Operator + +On an {ocp-short} cluster operating on a restricted network, public resources are not available. However, deploying the {product} Operator and running {product-short} requires the following public resources: + +* Operator images (bundle, operator, catalog) +* Operands images ({product-very-short}, PostgreSQL) + +To make these resources available, replace them with their equivalent resources in a mirror registry accessible to your cluster. + +You can use a helper script that mirrors the necessary images and provides the necessary configuration to ensure those images are used when installing the {product} Operator and creating {product-short} instances. This script requires a target mirror registry. You likely have a target mirror registry if your cluster is already operating on a disconnected network. If you do not already have a target registry, and if you have an {ocp-short} cluster, you might want to expose and leverage the internal cluster registry. + +When connected to a {ocp-short} cluster, the helper script detects it and automatically exposes the cluster registry. If connected to a Kubernetes cluster, you can manually specify the target registry to mirror the images. + +.Prerequisites +* You have installed Podman 5.3 or later. For more information, see link:https://podman.io/docs/installation[Podman Installation Instructions]. +* You have installed Skopeo 1.17 or later. +* You have installed `yq` 4.44 or later. +* You have installed the GNU `sed` command line text editor. +* You have installed `umoci` CLI tool. +* You have an active `oc registry`, `podman`, or `skopeo` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. For more information, see link:https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. +* You have an active `skopeo` session with administrative access to the target mirror registry. For more information, see link:https://github.com/containers/skopeo#authenticating-to-a-registry[Authenticating to a registry]. +* You have installed the `opm` CLI tool. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/cli_tools/opm-cli#olm-about-opm_cli-opm-install[Installing the opm CLI]. +* If you are using an {ocp-short} cluster, you have the following prerequisites: +** (Optional) You have installed the `oc-mirror` {ocp-short} CLI plugin if you want to use it to mirror images. +* If you are using a supported Kubernetes cluster, you have the following prerequisites: +** You have installed the Operator Lifecycle Manager (OLM) on the disconnected cluster. +** You have a mirror registry that is reachable from the disconnected cluster. + +.Procedure +. In your terminal, navigate to the directory where you want to save the mirroring script. +. Download the mirroring script by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-{product-version}/.rhdh/scripts/prepare-restricted-environment.sh +---- ++ +. Run the mirroring script by using the `bash` command with the appropriate set of options: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +bash prepare-restricted-environment.sh \ + --filter-versions "{product-version}" \ + [--to-registry _<my.registry.example.com>_] \ <1> + [--use-oc-mirror true] <2> +---- +<1> Specifies the URL for the target mirror registry where you want to mirror the images. +<2> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. ++ +[NOTE] +==== +The script can take several minutes to complete as it copies multiple images to the mirror registry. +==== + +.Verification +* If you are using {ocp-brand-name}, the {product} Operator is in the *Installed Operators* list in the web console. +* If you are using a supported Kubernetes platform, you can check the list of pods running in the `rhdh-operator` namespace by running the following command in your terminal: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +kubectl -n rhdh-operator get pods +---- + +.Next steps +* Use the Operator to create a {product} instance on a supported platform. For more information, see the following documentation for the platform that you want to use: +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_container_platform/assembly-install-rhdh-ocp-operator[Installing {product} on {ocp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_amazon_elastic_kubernetes_service/proc-rhdh-deploy-eks-operator_title-install-rhdh-eks[Installing {product-short} on {eks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_microsoft_azure_kubernetes_service/proc-rhdh-deploy-aks-operator_title-install-rhdh-aks[Installing {product-short} on {aks-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_openshift_dedicated_on_google_cloud_platform/proc-install-rhdh-osd-gcp-operator_title-install-rhdh-osd-gcp[Installing {product-short} on {gcp-short} with the Operator] +** link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_red_hat_developer_hub_on_google_kubernetes_engine/proc-rhdh-deploy-gke-operator.adoc_title-install-rhdh-gke#proc-deploy-rhdh-instance-gke.adoc_title-install-rhdh-gke[Deploying {product-short} on {gke-short} with the Operator] \ No newline at end of file diff --git a/modules/installation/proc-rhdh-deploy-aks-operator.adoc b/modules/installation/proc-rhdh-deploy-aks-operator.adoc index 0bc3fc9478..3ca2cb4bcb 100644 --- a/modules/installation/proc-rhdh-deploy-aks-operator.adoc +++ b/modules/installation/proc-rhdh-deploy-aks-operator.adoc @@ -87,17 +87,17 @@ kubectl -n <your_namespace> apply -f rhdh-ingress.yaml ---- -- -. Create a ConfigMap named `app-config-rhdh` containing the {product-short} configuration using the following example: +. Create a `{my-app-config-config-map}` config map containing the `{my-app-config-file}` {product-short} configuration file by using the following example: + -- -[source,yaml] +[source,yaml,subs="+attributes"] ---- apiVersion: v1 kind: ConfigMap metadata: - name: app-config-rhdh + name: {my-app-config-config-map} data: - "app-config-rhdh.yaml": | + "{my-app-config-file}": | app: title: Red Hat Developer Hub baseUrl: https://<app_address> @@ -114,40 +114,42 @@ data: ---- -- -. Create a Secret named `my-rhdh-secrets` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string value as shown in the following example: +. Create a `_<my_product_secrets>_` secret and add a key named `BACKEND_SECRET` with a `Base64-encoded` string value as shown in the following example: + -- -[source,yaml] +[source,yaml,subs="+attributes,+quotes"] ---- apiVersion: v1 kind: Secret metadata: - name: my-rhdh-secrets + name: `_<my_product_secrets>_` <1> stringData: BACKEND_SECRET: "xxx" ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the identifier for your secret configuration within {product-short}. -- -. Create your `{product-custom-resource-type}` custom resource (CR) manifest file named `rhdh.yaml` and include the previously created `rhdh-pull-secret` as follows: +. Create your `{product-custom-resource-type}` custom resource (CR) manifest file named `_<your-rhdh-cr>_` and include the previously created `rhdh-pull-secret` as follows: + -- -[source,yaml] +[source,yaml,subs="+quotes,+attributes"] ---- apiVersion: rhdh.redhat.com/v1alpha3 kind: Backstage metadata: - name: <your-rhdh-cr> + name: `_<your-rhdh-cr>_` spec: application: imagePullSecrets: - rhdh-pull-secret appConfig: configMaps: - - name: "app-config-rhdh" + - name: {my-app-config-config-map} extraEnvs: secrets: - - name: "my-rhdh-secrets" + - name: `_<my_product_secrets>_` <1> ---- +<1> `_<my_product_secrets>_` is your preferred {product-short} secret name, where `_<my_product_secrets>_` specifies the identifier for your secret configuration within {product-short}. -- . Apply the CR manifest to your namespace: diff --git a/modules/installation/proc-rhdh-deploy-eks-operator.adoc b/modules/installation/proc-rhdh-deploy-eks-operator.adoc index 0e4c0eed94..22671c3d97 100644 --- a/modules/installation/proc-rhdh-deploy-eks-operator.adoc +++ b/modules/installation/proc-rhdh-deploy-eks-operator.adoc @@ -2,14 +2,8 @@ // assembly-install-rhdh-eks.adoc [id='proc-rhdh-deploy-eks-operator_{context}'] -= Installing {product-short} on {eks-short} with the Operator -The {product} Operator installation requires the Operator Lifecycle Manager (OLM) framework. - -.Additional resources -* For information about the OLM, see link:https://olm.operatorframework.io/docs/[Operator Lifecycle Manager(OLM)] documentation. - -== Installing the {product-short} Operator with the OLM framework += Installing the {product-short} Operator with the OLM framework You can install the {product-short} Operator on {eks-short} using the https://olm.operatorframework.io[Operator Lifecycle Manager (OLM) framework]. Following that, you can proceed to deploy your {product-short} instance in {eks-short}. diff --git a/modules/observe/adoption-insights/con-about-adoption-insights.adoc b/modules/observe/adoption-insights/con-about-adoption-insights.adoc new file mode 100644 index 0000000000..5cec347e60 --- /dev/null +++ b/modules/observe/adoption-insights/con-about-adoption-insights.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: CONCEPT +[id="con-about-adoption-insights_{context}"] += About Adoption Insights + +As organizations generate an increasing number of data events, there is a growing need for detailed insights into the adoption and engagement metrics of the internal developer portal. These insights help platform engineers make data-driven decisions to improve its performance, usability, and translate them into actionable insights. + +You can use Adoption Insights in {product} to visualize key metrics and trends to get information about the usage of {product-short} in your organization. The information provided by Adoption Insights in {product-short} pinpoints areas of improvement, highlights popular features, and evaluates progress toward adoption goals. You can also monitor user growth against license users and identify trends over time. + +[NOTE] +==== +Currently, the Adoption Insights plugin cannot be used alongside the built-in `plugin-analytics-provider-segment` plugin. For a workaround, see link:{release-notes-book-url}#developer-preview-rhdhpai-510[Adoption Insights in {product}.] +==== + +The Adoption Insights dashboard in {product-short} includes the following cards: + +* *Active users* +* *Total nuber of users* +* *Top catalog entities* +* *Top 3 templates* +* *Top 3 techdocs* +* *Top 3 plugins* +* *Portal searches* + +image::rhdh-plugins-reference/adoption-insights.jpg[adoption insights] \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-configure-adoption-insights.adoc b/modules/observe/adoption-insights/proc-configure-adoption-insights.adoc new file mode 100644 index 0000000000..d49a5bbb04 --- /dev/null +++ b/modules/observe/adoption-insights/proc-configure-adoption-insights.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-configure-adoption-insights_{context}"] += Configuring the Adoption Insights plugin in {product} + +You can enable the Adoption Insights plugin by configuring the {product} Helm chart or the {product} Operator ConfigMap. + +.Procedure + +* To configure the Adoption Insights plugin in {product-short}, in your {product} `app-config.yaml` file, add the following code: ++ +.`app-config.yaml` fragment +[source,terminal] +---- +app: + analytics: + adoptionInsights: + maxBufferSize: 20 <1> + flushInterval: 5000 <2> + debug: false <3> + licensedUsers: 2000 <4> +---- +<1> (Optional) Specifies the maximum buffer size for event batching. The default value is `20`. +<2> (Optional) Specifies the flush interval in milliseconds for event batching. The default value is `5000ms`. +<3> (Optional) The default value is `false`. +<4> (Optional) Specifies the maximum number of licensed users who can access the RHDH instance. The default value is `100`. \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-filter-records-to-display-spec.adoc b/modules/observe/adoption-insights/proc-filter-records-to-display-spec.adoc new file mode 100644 index 0000000000..ce03b23d71 --- /dev/null +++ b/modules/observe/adoption-insights/proc-filter-records-to-display-spec.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-filter-records-to-display-spec_{context}"] += Filtering records to display specific catalog entities in Top catalog entities + +You can use the dropdown filter in the title to filter the table display by any of the items. By default, the *Top catalog entities* card displays all of the items in your {product-short} instance. + +.Procedure + +To view a specific catalog entity in the table, complete the following step: + +* Go to *Administration -> Adoption Insights*, click the dropdown filter on the *Top catalog entities* card, and select the item that you want to view. \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-install-adoption-insights.adoc b/modules/observe/adoption-insights/proc-install-adoption-insights.adoc new file mode 100644 index 0000000000..0cc384837b --- /dev/null +++ b/modules/observe/adoption-insights/proc-install-adoption-insights.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-rhdh-observability.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-install-adoption-insights_{context}"] += Installing the Adoption Insights plugin in {product} + +For the {product} Adoption Insights plugin, you must manually install the plugin. + +.Procedure + +* To enable the Adoption Insights plugin, set the `disabled` property to `false` in your `app-config-dynamic.yaml` file as shown in the following example: ++ +[source,yaml] +---- +- package: oci://quay.io/_<your_rhdh_plugins_repo>_/adoption-insights:latest!red-hat-developer-hub-backstage-plugin-adoption-insights + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-adoption-insights: + appIcons: + - name: adoptionInsightsIcon + importName: AdoptionInsightsIcon + dynamicRoutes: + - path: /adoption-insights + importName: AdoptionInsightsPage + menuItem: + icon: adoptionInsightsIcon + text: Adoption Insights + menuItems: + adoption-insights: + parent: admin + icon: adoptionInsightsIcon + +- package: oci://quay.io/_<your_rhdh_plugins_repo>_/adoption-insights:latest!red-hat-developer-hub-backstage-plugin-adoption-insights-backend + disabled: false + +- package: oci://quay.io/_<your_rhdh_plugins_repo>_/adoption-insights:latest!red-hat-developer-hub-backstage-plugin-analytics-module-adoption-insights + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-analytics-module-adoption-insights: + apiFactories: + - importName: AdoptionInsightsAnalyticsApiFactory +---- \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-modify-number-of-displayed-records.adoc b/modules/observe/adoption-insights/proc-modify-number-of-displayed-records.adoc new file mode 100644 index 0000000000..762eda4057 --- /dev/null +++ b/modules/observe/adoption-insights/proc-modify-number-of-displayed-records.adoc @@ -0,0 +1,65 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-modify-number-of-displayed-records_{context}"] += Modifying the number of displayed records + +== Modifying the number of displayed records in Top catalog entities + +You can modify the number of records that are displayed in the *Top catalog entities* card. You can select any of the following number of records for display: + +* *Top 3* +* *Top 5* +* *Top 10* +* *Top 20* + +By default, the top three most viewed catalog entities are displayed. + +.Procedure + +* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records. + +image::rhdh-plugins-reference/adoption-insights-catalog-entities.jpg[Catalog Entities dropdown] + +== Modifying the number of displayed records in Top 3 templates + +You can modify the number of records that are displayed in the *Top 3 templates* card. You can select any of the following number of records for display: + +* *Top 3* +* *Top 5* +* *Top 10* +* *Top 20* + +By default, the top three most viewed templates are displayed. + +.Procedure + +* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records. + +== Modifying the number of displayed records in Top 3 techdocs + +You can modify the number of records that are displayed in the *Top 3 techdocs* card. You can select any of the following number of records for display: + +* *Top 3* +* *Top 5* +* *Top 10* +* *Top 20* + +By default, the top three most viewed TechDocs are displayed. + +.Procedure + +* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records. + +== Modifying the number of displayed records in Top 3 plugins + +You can modify the number of records that are displayed in the *Top 3 plugins* card. You can select any of the following number of records for display: + +* *Top 3* +* *Top 5* +* *Top 10* +* *Top 20* + +By default, the top three most viewed plugins are displayed. + +.Procedure + +* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records. \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-setting-duration-of-data-metrics.adoc b/modules/observe/adoption-insights/proc-setting-duration-of-data-metrics.adoc new file mode 100644 index 0000000000..24e256d378 --- /dev/null +++ b/modules/observe/adoption-insights/proc-setting-duration-of-data-metrics.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-setting-duration-of-data-metrics_{context}"] += Setting the duration of data metrics + +You can set the data metrics duration using any of the time ranges, such as *Today*, *Last week*, *Last month*, *Last 28 days* (default), *Last year*, or *Date range...*. + +.Procedure + +. On the top of the screen, click the dropdown list to display the choices. +. Select the duration choice for which you want to see the data metrics. + +image::rhdh-plugins-reference/adoption-insights-daterange.jpg[date range] \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-using-adoption-insights.adoc b/modules/observe/adoption-insights/proc-using-adoption-insights.adoc new file mode 100644 index 0000000000..86f8d4309d --- /dev/null +++ b/modules/observe/adoption-insights/proc-using-adoption-insights.adoc @@ -0,0 +1,5 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-using-adoption-insights_{context}"] += Using Adoption Insights in {product} + +In the {product-short} application, on the navigation menu, click *Administration -> Adoption Insights*. \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-viewing-adoption-insights-card.adoc b/modules/observe/adoption-insights/proc-viewing-adoption-insights-card.adoc new file mode 100644 index 0000000000..fa32130f8f --- /dev/null +++ b/modules/observe/adoption-insights/proc-viewing-adoption-insights-card.adoc @@ -0,0 +1,95 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-viewing-adoption-insights-card_{context}"] += Viewing the Adoption Insights card + +== Viewing the active users + +The *Active users* card displays the total number of active users over a specified time range. It also provides a breakdown comparison of *New users* and *Returning users* in a line/area graph format. You can export the user data in a .csv format. + +*Returning users*: Existing users who have logged into {product-short} + +*New users*: New users who have registered and logged into {product-short} + +image::rhdh-plugins-reference/active-users.jpg[active users] + +.Procedure + +* To view the list of active users in your Developer Hub instance, go to *Administration -> Adoption Insights*, see the Active users card. + +* To view the exact number of users for a particular day, hover over the corresponding date in the *Active users* card. + +* To export the user data in a .csv format, click the *Export CSV* label. + +== Viewing the total number of users + +This card displays the total number of users that have license to use {product}. It also provides a comparison of the number of *Logged-in users* and *Licensed users* in numeric and percentage form. + +*Logged-in users*: Total number of users, including licensed and unlicensed users, currently logged in {product-short} + +*Licensed users*: Total number of licensed users logged in {product-short}. You can set the number of licensed users in your {product-short} app-config.yaml file. + +.Procedure + +* To view the total number of users in your {product-short} instance in numeric and percentage forms, go to *Administration -> Adoption Insights* and see the *Total number of users* card. + +* To view a percentage representation of the total number of logged-in users among the total number of licensed users, hover over the tooltip in the *Total number of users* card. + +== Viewing the top catalog entities + +This card lists the most viewed catalog entities (like components, APIs, and so on) and documentation entries, including usage statistics, in a table. + +Each item displays *Name*, *Kind*, *Last used*, and *Views*. + +*Name*: Name of the catalog +*Kind*: Type of the catalog +*Last used*: The last time the catalog was used +*Views*: The number of times the catalog was viewed + +.Procedure + +* To view the most commonly used catalog entities in your {product-short} instance, go to *Administration -> Adoption Insights* and see the *Top catalog entities* card. + +* To know more about the displayed catalog entity, hover over the catalog entity name. + +== Viewing the top 3 templates + +This card lists the three most commonly used templates in a table. You can click the down arrow next to *3 rows* to view the full list of the commonly used templates. + +*Name*: Name of the template +*Mostly in use by*: Type of user that used this template +*Executions*: Number of times this template was used + +.Procedure + +* To view the most commonly used templates in your {product-short} instance, go to *Administration -> Adoption Insights* and see the *Top 3 templates* card. + +* To know more about the displayed template, hover over the template name. + +== Viewing the top 3 techdocs + +This card lists the most viewed documentation entries, including the total views, in a table. + +*Name*: Name of the TechDoc +*Entity*: Type of the TechDoc +*Last used*: The last time the TechDoc was viewed +*Views*: Number of times the TechDocs was visited + +.Procedure + +* To view the most commonly used templates in your {product-short} instance, go to *Administration -> Adoption Insights* and see the *Top 3 techdocs* card. + +* To know more about the displayed techdocs, hover over the techdocs name. + +== Viewing the top 3 plugins + +This card lists the three most commonly used plugins in a table. You can click the down arrow next to *3 rows* to view the full list of the commonly used plugins. + +*Name*: Name of the plugin +*Trend*: Popularity of the plugin as a graph +*Views*: Number of times this plugin was seen + +.Procedure + +* To view the most commonly used plugins and the plugin page visit trends in your {product-short} instance, go to *Administration -> Adoption Insights* and see the *Top 3 plugins* card. + +* To know more about the displayed plugin, hover over the plugin name. \ No newline at end of file diff --git a/modules/observe/adoption-insights/proc-viewing-searches.adoc b/modules/observe/adoption-insights/proc-viewing-searches.adoc new file mode 100644 index 0000000000..56c0beae39 --- /dev/null +++ b/modules/observe/adoption-insights/proc-viewing-searches.adoc @@ -0,0 +1,9 @@ +:_mod-docs-content-type: PROCEDURE +[id="proc-viewing-searches_{context}"] += Viewing Searches + +In the *searches* card, you can view the following data: + +* Visualizes the number of portal searches and trends over time as a graph +* Displays the total for the period in the card title +* Clarifies the average number each hour/day/week/month depending on the time period chosen diff --git a/modules/observe/con-audit-log-track-changes-catalog.adoc b/modules/observe/con-audit-log-track-changes-catalog.adoc index 28784117b1..b913cbc83c 100644 --- a/modules/observe/con-audit-log-track-changes-catalog.adoc +++ b/modules/observe/con-audit-log-track-changes-catalog.adoc @@ -4,4 +4,4 @@ [id="con-audit-log-track-changes-catalog_{context}"] = {product-short} catalog database changes -In {product} {ocp-version-min} and later, changes to the catalog database are forwarded to a central log management system, such as ElasticSearch or Splunk by default. Administrators can view changes that add, remove, or update data in the catalog database to help ensure accountability and transparency of user actions. +In {product} {ocp-version-min} and later, changes to the catalog database are forwarded to a central log management system, such as ElasticSearch or Splunk by default. Administrators can view changes that add, remove, or update data in the catalog database to help ensure accountability and transparency of user actions. \ No newline at end of file diff --git a/modules/observe/proc-admin-enabling-metrics-ocp-helm.adoc b/modules/observe/proc-admin-enabling-metrics-ocp-helm.adoc index 9222762631..bd5b2a71d1 100644 --- a/modules/observe/proc-admin-enabling-metrics-ocp-helm.adoc +++ b/modules/observe/proc-admin-enabling-metrics-ocp-helm.adoc @@ -41,4 +41,4 @@ image::rhdh/upgrade-helm-metrics.png[] .Verification . From the *Developer* perspective in the {ocp-short} web console, select the *Observe* view. -. Click the *Metrics* tab to view metrics for {product} pods. +. Click the *Metrics* tab to view metrics for {product} pods. \ No newline at end of file diff --git a/modules/observe/proc-admin-enabling-metrics-ocp-operator.adoc b/modules/observe/proc-admin-enabling-metrics-ocp-operator.adoc index f169e2f3a0..921ed4d11b 100644 --- a/modules/observe/proc-admin-enabling-metrics-ocp-operator.adoc +++ b/modules/observe/proc-admin-enabling-metrics-ocp-operator.adoc @@ -25,24 +25,34 @@ Currently, the {product} Operator does not support creating a `ServiceMonitor` c apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: - name: <custom_resource_name> # <1> - namespace: {my-product-namespace} # <2> + name: _<developer_hub_service_monitor_name>_ <1> + namespace: _<rhdh_namespace_name>_ <2> labels: - app.kubernetes.io/instance: <custom_resource_name> - app.kubernetes.io/name: backstage + app.kubernetes.io/instance: _<rhdh_cr_name>_ <3> + app.kubernetes.io/name: {product-custom-resource-type} spec: namespaceSelector: matchNames: - - {my-product-namespace} + - _<rhdh_namespace_name>_ <4> selector: matchLabels: - rhdh.redhat.com/app: backstage-<custom_resource_name> + app.kubernetes.io/instance: _<deployment_name>_ <5> + app.kubernetes.io/name: _<rhdh_cr_type>_ <6> endpoints: - port: http-metrics path: '/metrics' ---- -<1> Replace `<custom_resource_name>` with the name of your `{product-custom-resource-type}` custom resource. -<2> Replace `<project_name>` with the name of the {ocp-short} project where your {product} instance is running. +<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`. ++ +[NOTE] +==== +`spec.selector.matchLabels` configuration must match the labels of your {product-very-short} installation. +==== . Apply the `ServiceMonitor` CR by running the following command: + @@ -55,3 +65,4 @@ oc apply -f <filename> . From the *Developer* perspective in 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`. diff --git a/modules/observe/proc-audit-log-view.adoc b/modules/observe/proc-audit-log-view.adoc index 3a77b8249e..2fd0ddf1f3 100644 --- a/modules/observe/proc-audit-log-view.adoc +++ b/modules/observe/proc-audit-log-view.adoc @@ -5,7 +5,7 @@ [id="proc-audit-log-view_{context}"] = Viewing audit logs in {product-short} -Administrators can view, search, filter, and manage the log data from the {ocp-brand-name} web console. You can filter audit logs from other log types by using the `isAuditLog` field. +Administrators can view, search, filter, and manage the log data from the {ocp-brand-name} web console. You can filter audit logs from other log types by using the `isAuditEvent` field. .Prerequisites * You are logged in as an administrator in the {ocp-short} web console. @@ -16,4 +16,4 @@ Administrators can view, search, filter, and manage the log data from the {ocp-b . From the *Topology* view, click the pod that you want to view audit log data for. . From the pod panel, click the *Resources* tab. . From the *Pods* section of the *Resources* tab, click *View logs*. -. From the *Logs* view, enter `isAuditLog` into the *Search* field to filter audit logs from other log types. You can use the arrows to browse the logs containing the `isAuditLog` field. +. From the *Logs* view, enter `isAuditEvent` into the *Search* field to filter audit logs from other log types. You can use the arrows to browse the logs containing the `isAuditEvent` field. diff --git a/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-helm-chart.adoc b/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-helm-chart.adoc new file mode 100644 index 0000000000..14ba807798 --- /dev/null +++ b/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-helm-chart.adoc @@ -0,0 +1,34 @@ +[id="configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-helm-chart_{context}"] += Configuring annotations for monitoring with Amazon Prometheus by using the {product} Helm chart + +To enable logging to Amazon Prometheus, you can configure the required pod annotations by using the {product} Helm chart. + +.Procedure +* To annotate the backstage pod for monitoring, update your `values.yaml` file as follows: ++ +[source,yaml] +---- +upstream: + backstage: + # --- TRUNCATED --- + podAnnotations: + prometheus.io/scrape: 'true' + prometheus.io/path: '/metrics' + prometheus.io/port: '9464' + prometheus.io/scheme: 'http' +---- + +.Verification +To verify if the scraping works: + +. Use `kubectl` to port-forward the Prometheus console to your local machine as follows: ++ +[source,bash] +---- +kubectl --namespace=prometheus port-forward deploy/prometheus-server 9090 +---- + +. Open your web browser and navigate to `pass:c[http://localhost:9090]` to access the Prometheus console. + +. Monitor relevant metrics, such as `process_cpu_user_seconds_total`. + diff --git a/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-operator.adoc b/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-operator.adoc new file mode 100644 index 0000000000..2caaeb535b --- /dev/null +++ b/modules/observe/proc-configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-operator.adoc @@ -0,0 +1,51 @@ +[id="configuring-annotations-for-monitoring-with-amazon-prometheus-by-using-the-operator_{context}"] += Configuring annotations for monitoring with Amazon Prometheus by using the {product} Operator + +To enable logging to Amazon Prometheus, you can configure the required pod annotations by using the {product} Operator. + +.Procedure +. As an administrator of the {product} Operator, edit the default configuration to add Prometheus annotations as follows: ++ +---- +# Update OPERATOR_NS accordingly +$ OPERATOR_NS=rhdh-operator +$ kubectl edit configmap backstage-default-config -n "${OPERATOR_NS}" +---- + +. Find the `deployment.yaml` key in the config map and add the annotations to the `spec.template.metadata.annotations` field as follows: ++ +[source,yaml] +---- +deployment.yaml: |- + apiVersion: apps/v1 + kind: Deployment + # --- truncated --- + spec: + template: + # --- truncated --- + metadata: + labels: + rhdh.redhat.com/app: # placeholder for 'backstage-<cr-name>' + # --- truncated --- + annotations: + prometheus.io/scrape: 'true' + prometheus.io/path: '/metrics' + prometheus.io/port: '9464' + prometheus.io/scheme: 'http' + # --- truncated --- +---- + +. Save your changes. + +.Verification +To verify if the scraping works: + +. Use `kubectl` to port-forward the Prometheus console to your local machine as follows: ++ +---- +$ kubectl --namespace=prometheus port-forward deploy/prometheus-server 9090 +---- + +. Open your web browser and navigate to `pass:c[http://localhost:9090]` to access the Prometheus console. +. Monitor relevant metrics, such as `process_cpu_user_seconds_total`. + diff --git a/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-helm-chart.adoc b/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-helm-chart.adoc new file mode 100644 index 0000000000..40349b7a1b --- /dev/null +++ b/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-helm-chart.adoc @@ -0,0 +1,17 @@ +[id="configuring-the-application-log-level-by-using-the-helm-chart_{context}"] += Configuring the application log level by using the {product} Helm chart + +You can configure the application log level by using the {product} Helm chart. + +.Procedure +* Modify the logging level by adding the environment variable `LOG_LEVEL` to your Helm chart `values.yaml` file: ++ +[source,yaml] +---- +upstream: + backstage: + # --- Truncated --- + extraEnvVars: + - name: LOG_LEVEL + value: debug +---- diff --git a/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-operator.adoc b/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-operator.adoc new file mode 100644 index 0000000000..7a6ea6a531 --- /dev/null +++ b/modules/observe/proc-configuring-the-application-log-level-for-logging-with-amazon-cloudwatch-logs-by-using-the-operator.adoc @@ -0,0 +1,18 @@ +[id="configuring-the-application-log-level-by-using-the-operator_{context}"] += Configuring the application log level by using the {product} Operator + +You can configure the application log level by using the {product} Operator. + +.Procedure +* Modify the logging level by including the environment variable `LOG_LEVEL` in your custom resource as follows: ++ +[source,yaml] +---- +spec: + # Other fields omitted + application: + extraEnvs: + envs: + - name: LOG_LEVEL + value: debug +---- diff --git a/modules/observe/proc-forward-audit-log-splunk.adoc b/modules/observe/proc-forward-audit-log-splunk.adoc index cfa5272d19..f3ebe394d4 100644 --- a/modules/observe/proc-forward-audit-log-splunk.adoc +++ b/modules/observe/proc-forward-audit-log-splunk.adoc @@ -130,7 +130,7 @@ filters: drop: - test: - field: .message - notMatches: isAuditLog + notMatches: isAuditEvent ---- For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html-single/logging/index#logging-content-filtering[Filtering logs by content] in {ocp-short} documentation. -- diff --git a/modules/observe/proc-retrieving-logs-from-amazon-cloudwatch.adoc b/modules/observe/proc-retrieving-logs-from-amazon-cloudwatch.adoc new file mode 100644 index 0000000000..e1eb6c37ae --- /dev/null +++ b/modules/observe/proc-retrieving-logs-from-amazon-cloudwatch.adoc @@ -0,0 +1,25 @@ +[id="retrieving-logs-from-amazon-cloudwatch_{context}"] += Retrieving logs from Amazon CloudWatch + +.Prerequisites +* CloudWatch Container Insights is used to capture logs and metrics for {eks-brand-name}. +For more information, see https://docs.aws.amazon.com/prescriptive-guidance/latest/implementing-logging-monitoring-cloudwatch/kubernetes-eks-logging.html[Logging for {eks-brand-name}] documentation. + +* To capture the logs and metrics, link:https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-setup-EKS-addon.html[install the Amazon CloudWatch Observability EKS add-on] in your cluster. +Following the setup of Container Insights, you can access container logs using Logs Insights or Live Tail views. + +* CloudWatch names the log group where all container logs are consolidated in the following manner: ++ +[subs="+quotes"] +---- +/aws/containerinsights/_<cluster_name>_/application +---- + +.Procedure +* To retrieve logs from the {product-short} instance, run a query such as: ++ +[source,sql] +---- +fields @timestamp, @message, kubernetes.container_name +| filter kubernetes.container_name in ["install-dynamic-plugins", "backstage-backend"] +---- diff --git a/modules/observe/proc-rhdh-monitoring-logging-aws.adoc b/modules/observe/proc-rhdh-monitoring-logging-aws.adoc deleted file mode 100644 index 822688a08e..0000000000 --- a/modules/observe/proc-rhdh-monitoring-logging-aws.adoc +++ /dev/null @@ -1,149 +0,0 @@ -[id='proc-rhdh-monitoring-logging-aws_{context}'] -= Monitoring and logging with Amazon Web Services (AWS) in {product} - -In the {product}, monitoring and logging are facilitated through Amazon Web Services (AWS) integration. With features like Amazon CloudWatch for real-time monitoring and Amazon Prometheus for comprehensive logging, you can ensure the reliability, scalability, and compliance of your {product-short} application hosted on AWS infrastructure. - -This integration enables you to oversee, diagnose, and refine your applications in the Red Hat ecosystem, leading to an improved development and operational journey. - -== Monitoring with Amazon Prometheus - -{product} provides Prometheus metrics related to the running application. For more information about enabling or deploying Prometheus for EKS clusters, see https://docs.aws.amazon.com/eks/latest/userguide/prometheus.html[Prometheus metrics] in the Amazon documentation. - -To monitor {product-short} using https://aws.amazon.com/prometheus/[Amazon Prometheus], you need to create an Amazon managed service for the Prometheus workspace and configure the ingestion of the Developer Hub Prometheus metrics. For more information, see https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-create-workspace.html[Create a workspace] and https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-ingest-metrics.html[Ingest Prometheus metrics to the workspace] sections in the Amazon documentation. - -After ingesting Prometheus metrics into the created workspace, you can configure the metrics scraping to extract data from pods based on specific pod annotations. - -=== Configuring annotations for monitoring - -You can configure the annotations for monitoring in both Helm deployment and Operator-backed deployment. - -Helm deployment:: -+ --- -To annotate the backstage pod for monitoring, update your `values.yaml` file as follows: - -[source,yaml] ----- -upstream: - backstage: - # --- TRUNCATED --- - podAnnotations: - prometheus.io/scrape: 'true' - prometheus.io/path: '/metrics' - prometheus.io/port: '9464' - prometheus.io/scheme: 'http' ----- --- - -Operator-backed deployment:: -+ --- -.Procedure - -. As an administrator of the operator, edit the default configuration to add Prometheus annotations as follows: -+ -[source,bash] ----- -# Update OPERATOR_NS accordingly -OPERATOR_NS=rhdh-operator -kubectl edit configmap backstage-default-config -n "${OPERATOR_NS}" ----- - -. Find the `deployment.yaml` key in the ConfigMap and add the annotations to the `spec.template.metadata.annotations` field as follows: -+ -[source,yaml] ----- -deployment.yaml: |- - apiVersion: apps/v1 - kind: Deployment - # --- truncated --- - spec: - template: - # --- truncated --- - metadata: - labels: - rhdh.redhat.com/app: # placeholder for 'backstage-<cr-name>' - # --- truncated --- - annotations: - prometheus.io/scrape: 'true' - prometheus.io/path: '/metrics' - prometheus.io/port: '9464' - prometheus.io/scheme: 'http' - # --- truncated --- ----- - -. Save your changes. --- - -.Verification - -To verify if the scraping works: - -. Use `kubectl` to port-forward the Prometheus console to your local machine as follows: -+ -[source,bash] ----- -kubectl --namespace=prometheus port-forward deploy/prometheus-server 9090 ----- - -. Open your web browser and navigate to `pass:c[http://localhost:9090]` to access the Prometheus console. -. Monitor relevant metrics, such as `process_cpu_user_seconds_total`. - -== Logging with Amazon CloudWatch logs - -Logging within the {product} relies on the https://github.com/winstonjs/winston[winston library]. By default, logs at the debug level are not recorded. To activate debug logs, you must set the environment variable `LOG_LEVEL` to debug in your {product} instance. - -=== Configuring the application log level - -You can configure the application log level in both Helm deployment and Operator-backed deployment. - -Helm deployment:: -+ --- -To update the logging level, add the environment variable `LOG_LEVEL` to your Helm chart's `values.yaml` file: - -[source,yaml] ----- -upstream: - backstage: - # --- Truncated --- - extraEnvVars: - - name: LOG_LEVEL - value: debug ----- --- - -Operator-backed deployment:: -+ --- -You can modify the logging level by including the environment variable `LOG_LEVEL` in your custom resource as follows: - -[source,yaml] ----- -spec: - # Other fields omitted - application: - extraEnvs: - envs: - - name: LOG_LEVEL - value: debug ----- --- - -=== Retrieving logs from Amazon CloudWatch - -The CloudWatch Container Insights are used to capture logs and metrics for Amazon EKS. For more information, see https://docs.aws.amazon.com/prescriptive-guidance/latest/implementing-logging-monitoring-cloudwatch/kubernetes-eks-logging.html[Logging for Amazon EKS] documentation. - -To capture the logs and metrics, https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-setup-EKS-addon.html[install the Amazon CloudWatch Observability EKS add-on] in your cluster. Following the setup of Container Insights, you can access container logs using Logs Insights or Live Tail views. - -CloudWatch names the log group where all container logs are consolidated in the following manner: - -`/aws/containerinsights/<ClusterName>/application` - -Following is an example query to retrieve logs from the Developer Hub instance: - -[source,sql] ----- -fields @timestamp, @message, kubernetes.container_name -| filter kubernetes.container_name in ["install-dynamic-plugins", "backstage-backend"] ----- diff --git a/modules/observe/ref-audit-log-catalog-events.adoc b/modules/observe/ref-audit-log-catalog-events.adoc deleted file mode 100644 index b47a7847ce..0000000000 --- a/modules/observe/ref-audit-log-catalog-events.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// assembly-audit-log.adoc - -:_mod-docs-content-type: REFERENCE -[id="ref-audit-log-catalog-events.adoc_{context}"] -= Catalog events - -{product-short} audit logs can include the following catalog events: - -`CatalogEntityAncestryFetch`:: Tracks `GET` requests to the `/entities/by-name/:kind/:namespace/:name/ancestry` endpoint, which returns the ancestry of an entity -`CatalogEntityBatchFetch`:: Tracks `POST` requests to the `/entities/by-refs` endpoint, which returns a batch of entities -`CatalogEntityDeletion`:: Tracks `DELETE` requests to the `/entities/by-uid/:uid` endpoint, which deletes an entity - -[NOTE] -==== -If the parent location of the deleted entity is still present in the catalog, then the entity is restored in the catalog during the next processing cycle. -==== - -`CatalogEntityFacetFetch`:: Tracks `GET` requests to the `/entity-facets` endpoint, which returns the facets of an entity -`CatalogEntityFetch`:: Tracks `GET` requests to the `/entities` endpoint, which returns a list of entities -`CatalogEntityFetchByName`:: Tracks `GET` requests to the `/entities/by-name/:kind/:namespace/:name` endpoint, which returns an entity matching the specified entity reference, for example, `<kind>:<namespace>/<name>` -`CatalogEntityFetchByUid`:: Tracks `GET` requests to the `/entities/by-uid/:uid` endpoint, which returns an entity matching the unique ID of the specified entity -`CatalogEntityRefresh`:: Tracks `POST` requests to the `/entities/refresh` endpoint, which schedules the specified entity to be refreshed -`CatalogEntityValidate`:: Tracks `POST` requests to the `/entities/validate` endpoint, which validates the specified entity -`CatalogLocationCreation`:: Tracks `POST` requests to the `/locations` endpoint, which creates a location - -[NOTE] -==== -A location is a marker that references other places to look for catalog data. -==== - -`CatalogLocationAnalyze`:: Tracks `POST` requests to the `/locations/analyze` endpoint, which analyzes the specified location -`CatalogLocationDeletion`:: Tracks `DELETE` requests to the `/locations/:id` endpoint, which deletes a location and all child entities associated with it -`CatalogLocationFetch`:: Tracks `GET` requests to the `/locations` endpoint, which returns a list of locations -`CatalogLocationFetchByEntityRef`:: Tracks `GET` requests to the `/locations/by-entity` endpoint, which returns a list of locations associated with the specified entity reference -`CatalogLocationFetchById`:: Tracks `GET` requests to the `/locations/:id` endpoint, which returns a location matching the specified location ID -`QueriedCatalogEntityFetch`:: Tracks `GET` requests to the `/entities/by-query` endpoint, which returns a list of entities matching the specified query diff --git a/modules/observe/ref-audit-log-fields.adoc b/modules/observe/ref-audit-log-fields.adoc deleted file mode 100644 index 0e6de692e1..0000000000 --- a/modules/observe/ref-audit-log-fields.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// assembly-audit-log.adoc - -:_mod-docs-content-type: REFERENCE -[id="ref-audit-log-fields.adoc_{context}"] -= Audit log fields - -{product-short} audit logs can include the following fields: - -`eventName`:: The name of the audited event. -`actor`:: An object containing information about the actor that triggered the audited event. Contains the following fields: -`actorId`::: The name/id/`entityRef` of the associated user or service. Can be `null` if an unauthenticated user accesses the endpoints and the default authentication policy is disabled. -`ip`::: The IP address of the actor (optional). -`hostname`::: The hostname of the actor (optional). -`client`::: The user agent of the actor (optional). -`stage`:: The stage of the event at the time that the audit log was generated, for example, `initiation` or `completion`. -`status`:: The status of the event, for example, `succeeded` or `failed`. -`meta`:: An optional object containing event specific data, for example, `taskId`. -`request`:: An optional field that contains information about the HTTP request sent to an endpoint. Contains the following fields: -`method`::: The HTTP method of the request. -`query`::: The `query` fields of the request. -`params`::: The `params` fields of the request. -`body`::: The request `body`. The `secrets` provided when creating a task are redacted and appear as `***`. -`url`::: The endpoint URL of the request. -`response`:: An optional field that contains information about the HTTP response sent from an endpoint. Contains the following fields: -`status`::: The status code of the HTTP response. -`body`::: The contents of the request body. -`isAuditLog`:: A flag set to `true` to differentiate audit logs from other log types. -`errors`:: A list of errors containing the `name`, `message` and potentially the `stack` field of the error. Only appears when `status` is `failed`. diff --git a/modules/observe/ref-audit-log-scaffolder-events.adoc b/modules/observe/ref-audit-log-scaffolder-events.adoc deleted file mode 100644 index 19422794b9..0000000000 --- a/modules/observe/ref-audit-log-scaffolder-events.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// assembly-audit-log.adoc - -:_mod-docs-content-type: REFERENCE -[id="ref-audit-log-scaffolder-events.adoc_{context}"] -= Scaffolder events - -{product-short} audit logs can include the following scaffolder events: - -`ScaffolderParameterSchemaFetch`:: Tracks `GET` requests to the `/v2/templates/:namespace/:kind/:name/parameter-schema` endpoint which return template parameter schemas -`ScaffolderInstalledActionsFetch`:: Tracks `GET` requests to the `/v2/actions` endpoint which grabs the list of installed actions -`ScaffolderTaskCreation`:: Tracks `POST` requests to the `/v2/tasks` endpoint which creates tasks that the scaffolder executes -`ScaffolderTaskListFetch`:: Tracks `GET` requests to the `/v2/tasks` endpoint which fetches details of all tasks in the scaffolder. -`ScaffolderTaskFetch`:: Tracks `GET` requests to the `/v2/tasks/:taskId` endpoint which fetches details of a specified task `:taskId` -`ScaffolderTaskCancellation`:: Tracks `POST` requests to the `/v2/tasks/:taskId/cancel` endpoint which cancels a running task -`ScaffolderTaskStream`:: Tracks `GET` requests to the `/v2/tasks/:taskId/eventstream` endpoint which returns an event stream of the task logs of task `:taskId` -`ScaffolderTaskEventFetch`:: Tracks `GET` requests to the `/v2/tasks/:taskId/events` endpoint which returns a snapshot of the task logs of task `:taskId` -`ScaffolderTaskDryRun`:: Tracks `POST` requests to the `/v2/dry-run` endpoint which creates a dry-run task. All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`. -`ScaffolderStaleTaskCancellation`:: Tracks automated cancellation of stale tasks -`ScaffolderTaskExecution`:: Tracks the `initiation` and `completion` of a real scaffolder task execution (will not occur during dry runs) -`ScaffolderTaskStepExecution`:: Tracks `initiation` and `completion` of a scaffolder task step execution -`ScaffolderTaskStepSkip`:: Tracks steps skipped due to `if` conditionals not being met -`ScaffolderTaskStepIteration`:: Tracks the step execution of each iteration of a task step that contains the `each` field. diff --git a/modules/observe/ref-customizing-telemetry-segment.adoc b/modules/observe/ref-customizing-telemetry-segment.adoc deleted file mode 100644 index 9ee7698713..0000000000 --- a/modules/observe/ref-customizing-telemetry-segment.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="customizing-telemetry-segment_{context}"] -= Customizing telemetry Segment source - - -The `analytics-provider-segment` plugin sends the collected telemetry data to {company-name} by default. However, you can configure a new Segment source that receives telemetry data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source. - -[NOTE] -==== -By configuring a new Segment source, you can collect and analyze the same set of data that is mentioned in link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. You might also require to create your own telemetry data collection notice for your application users. -==== - - diff --git a/modules/observe/ref-disabling-telemetry.adoc b/modules/observe/ref-disabling-telemetry.adoc deleted file mode 100644 index 66bf4470e1..0000000000 --- a/modules/observe/ref-disabling-telemetry.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="disabling-telemetry-data-collection_{context}"] -= Disabling telemetry data collection in {product-very-short} - -To disable telemetry data collection, you must disable the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator configuration. - - diff --git a/modules/release-notes/README.adoc b/modules/release-notes/README.adoc new file mode 100644 index 0000000000..ba51ef017d --- /dev/null +++ b/modules/release-notes/README.adoc @@ -0,0 +1,46 @@ += Single-sourcing release notes + +== Single-sourcing general purpose release notes + +The general purpose release notes content is single-sourced from link:https://issues.redhat.com/browse/RHIDP[the JIRA project]. + +.Prerequisites +* In link:https://issues.redhat.com/secure/Dashboard.jspa?selectPageId=12364101#SIGwKWmOqDCVBoapBCJiDqhoiKInaroYEg9j2PldSYMUcQVVVdrFHVDUxs1uBtQolXVZgDTdZwjXSCNOA1u11Xeog9Xjb100DUNCh2jwi0TVgzWteeg2FC1TmbT1TUrftGiFHa2CjQtp2TX1DnIGgGCIgEKI+iQfrUlV2AvkJQA[the JIRA project]: +** *Fix Version/s* is set. +** *Release Notes Text* is set using following format: a level 0 title followed by descriptive content, such as: ++ +.*Release Notes Text* sample +---- += Configurable PVC mounting for containers + +Previously, the default Persistent Volume Claim (PVC) could only be mounted to the Backstage container. With this update, you can now configure which container(s) the PVC should be mounted to, providing greater flexibility in storage management. +---- +** *Release Notes Type* is set to `Enhancement`, `Feature`, `Removed Functionality`, `Deprecated Functionality`, `Developer Preview`, `Technology Preview`, `Known Issue`, or `Bug Fix`. +** *Release Notes Status* is set to `Done`. + +* On the single-sourcing environment: Bash, Git, Python, and Pip are installed. + +.Procedure +. Verify the `product-version` and `product-bundle-version` attributes values in the `artifacts/attributes.adoc` file. + +. Open a terminal and change directory to the Git repository root. + +. Install required python modules. ++ +---- +$ pip3 install --requirement requirements.txt +---- + +. Single-source content from JIRA. ++ +---- +$ python modules/release-notes/single-source-release-notes.py +---- + +.Verification +* Verify the changed content: ++ +---- +$ git diff +---- + diff --git a/modules/release-notes/list-fixed-security-issues-in-product-1.3.0.txt b/modules/release-notes/list-fixed-security-issues-in-product-1.3.0.txt deleted file mode 100644 index 36e91d9a09..0000000000 --- a/modules/release-notes/list-fixed-security-issues-in-product-1.3.0.txt +++ /dev/null @@ -1,6 +0,0 @@ -CVE-2024-24790 -CVE-2024-24791 -CVE-2024-35255 -CVE-2024-37891 -CVE-2024-39008 -CVE-2024-39249 diff --git a/modules/release-notes/list-fixed-security-issues-in-rpm-1.3.0.txt b/modules/release-notes/list-fixed-security-issues-in-rpm-1.3.0.txt deleted file mode 100644 index bbd5596eeb..0000000000 --- a/modules/release-notes/list-fixed-security-issues-in-rpm-1.3.0.txt +++ /dev/null @@ -1,26 +0,0 @@ -CVE-2023-52439 -CVE-2023-52884 -CVE-2024-6119 -CVE-2024-26739 -CVE-2024-26929 -CVE-2024-26930 -CVE-2024-26931 -CVE-2024-26947 -CVE-2024-26991 -CVE-2024-27022 -CVE-2024-35895 -CVE-2024-36016 -CVE-2024-36899 -CVE-2024-38562 -CVE-2024-38570 -CVE-2024-38573 -CVE-2024-38601 -CVE-2024-38615 -CVE-2024-39331 -CVE-2024-40984 -CVE-2024-41071 -CVE-2024-42225 -CVE-2024-42246 -CVE-2024-45490 -CVE-2024-45491 -CVE-2024-45492 diff --git a/modules/release-notes/ref-release-notes-breaking-changes.adoc b/modules/release-notes/ref-release-notes-breaking-changes.adoc index f2310b4f6c..077e2f43c2 100644 --- a/modules/release-notes/ref-release-notes-breaking-changes.adoc +++ b/modules/release-notes/ref-release-notes-breaking-changes.adoc @@ -4,6 +4,59 @@ This section lists breaking changes in {product} {product-version}. +[id="removed-functionality-rhidp-6215"] +== The Topology-specific permission `topology.view.read` is removed + +Previously, the Topology plugin used `topology.view.read` permission to control access. Users were unable to configure Topology permissions using the RBAC UI. With this update, users can configure Kubernetes plugin permissions using the RBAC UI, which now governs the access to the Topology plugin. You can now use Kubernetes plugin permissions `kubernetes.clusters.read` and `kubernetes.resources.read` for the Topology plugin, as the topology-specific permission `topology.view.read` is removed. + +If you are using a CSV permission file, update the following line: + +.Old topology permission definition +[source,csv] +---- +p, role:default/topology-viewer, topology.view.read, read, allow +---- + +.New topology permission definition +[source,csv] +---- +p, role:default/topology-viewer, kubernetes.clusters.read, read, allow +p, role:default/topology-viewer, kubernetes.resources.read, read, allow +---- + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6215[RHIDP-6215] + +[id="removed-functionality-rhidp-7365"] +== Migration to the core Auditor service + +The Auditor format, including audit fields and event names, and IDs, has been updated to align with the new Auditor service conventions defined by the upstream Backstage Auditor Service. Filtering queries based on the old format may fail to work as expected. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-7365[RHIDP-7365] + +[id="removed-functionality-rhidp-7373"] +== {product} introduces the Backstage Audit Log Service + +{product} {product-version} introduces the Backstage Audit Log Service, which replaces the custom audit logging system. This is a significant structural and behavioral change to how audit events are generated and consumed. + +The key changes introduced by this transition include the following: + +* Audit logging is now delegated to Backstage plugins. Each plugin in Backstage is responsible for implementing and emitting its own audit events. + +* Audit event names, structure, and content may differ per plugin. Audit events are scoped and designed independently within each plugin using the standardized upstream mechanism, which automatically captures actor details and plugin context. + +* New Event Structure and Naming: Audit event names now follow Backstage’s conventions (for example, lowercase, kebab-case names), and include structured metadata such as `actionType`. Legacy {product-short} event names (for example, `ScaffolderTaskCreation`, `CatalogEntityDeletion`) are no longer used. + +* Enhanced Log Context: Each audit event includes the plugin context, making it easier to filter logs for specific functional areas. You can filter by the event IDs or metadata associated with that plugin. + + + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-7373[RHIDP-7373] + -None. diff --git a/modules/release-notes/ref-release-notes-deprecated-functionalities.adoc b/modules/release-notes/ref-release-notes-deprecated-functionalities.adoc index 56892e69a7..2b8b36891d 100644 --- a/modules/release-notes/ref-release-notes-deprecated-functionalities.adoc +++ b/modules/release-notes/ref-release-notes-deprecated-functionalities.adoc @@ -4,6 +4,16 @@ This section lists deprecated functionalities in {product} {product-version}. +[id="deprecated-functionality-rhidp-6368"] +== Deprecation of dynamic imports with `import(...)` + +The use of dynamic imports with `import(...)` has been deprecated and is no longer supported. The Backstage CLI supports native ESM in Node.js code, giving access to the importing of ESM-only packages. Therefore, you must now use `require(...)` as typeof `import(...)` when working with ESM or CommonJS packages. + + + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6368[RHIDP-6368] + -None. diff --git a/modules/release-notes/ref-release-notes-developer-preview.adoc b/modules/release-notes/ref-release-notes-developer-preview.adoc new file mode 100644 index 0000000000..bf2fd4f53d --- /dev/null +++ b/modules/release-notes/ref-release-notes-developer-preview.adoc @@ -0,0 +1,16 @@ +:_content-type: REFERENCE +[id="developer-preview"] += Developer Preview + +This section lists Developer Preview features in {product} {product-version}. + +[IMPORTANT] +==== +Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see link:https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== + + +None. + diff --git a/modules/release-notes/ref-release-notes-fixed-issues.adoc b/modules/release-notes/ref-release-notes-fixed-issues.adoc index dad582fc5a..3b6c5adf45 100644 --- a/modules/release-notes/ref-release-notes-fixed-issues.adoc +++ b/modules/release-notes/ref-release-notes-fixed-issues.adoc @@ -2,8 +2,66 @@ [id="fixed-issues"] = Fixed issues -This section lists issues fixed in {product} {product-version}. +This section lists issues fixed in {product} {product-version} that have a significant impact on users. + +== Fixed issues in 1.6.0 + +[id="bug-fix-rhidp-5731"] +=== Updated the air-gapped installation guide for non-OpenShift platforms + +Previously, {product} documentation did not highlight the {product-short} installation using Helm Chart in fully and partially air-gapped environments on supported Kubernetes platforms. + +With this update, the documentation provides instructions for mirroring required container images, updating Helm values, and installing the chart, without relying on internet access. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-5731[RHIDP-5731] + + +[id="bug-fix-rhidp-6010"] +=== Line wrapping enabled for long menu heading labels + +Previously, menu items with long text such as _Platform Engineer Services_ were cut off in the sidebar menu. With this update, line wrapping has been enabled for long menu heading labels, preventing the trimming and ensuring full text visibility. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6010[RHIDP-6010] + + +[id="bug-fix-rhidp-6015"] +=== Dynamic favicon configuration in `app-config.yaml` is not displayed on the login page + +Before this update, the app-config configuration `app.branding.iconLogo` was not applied as the favicon in the browser. + +This issue has been fixed, and the app-config configuration `app.branding.iconLogo` now correctly sets the favicon in the browser. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6015[RHIDP-6015] + + +[id="bug-fix-rhidp-6042"] +=== Floating Action Button (FAB) positioned in the 'Bottom-Left' slot on {product-short} + +Previously, the Floating Action Button (FAB) appeared over the navigation sidebar when the slot was set to 'bottom-left'. This placement obstructed access to navigation elements, potentially hindering user interaction. + +With this update, the FAB's position is adjusted to render adjacent to the navigation for the 'bottom-left' slot position. As a result, users can access navigation options without obstruction. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6042[RHIDP-6042] + + +[id="bug-fix-rhidp-6448"] +=== Manually added resolutions override resolutions added by `--suppress-native-package` + +Earlier, the `export-dynamic-plugin` command did not overwrite manually added resolutions, which could result in incorrect package dependencies in the exported dynamic plugin. + +With this update, the `package export-dynamic-plugin` overwrites manually added resolutions, ensuring backstage dependencies are hoisted and native dependencies are suppressed from the exported dynamic plugin. + + +.Additional resources +* link:https://issues.redhat.com/browse/RHIDP-6448[RHIDP-6448] -None. diff --git a/modules/release-notes/ref-release-notes-fixed-security-issues.adoc b/modules/release-notes/ref-release-notes-fixed-security-issues.adoc new file mode 100644 index 0000000000..b68cbfaa4c --- /dev/null +++ b/modules/release-notes/ref-release-notes-fixed-security-issues.adoc @@ -0,0 +1,5 @@ +:_content-type: REFERENCE +[id="fixed-security-issues"] += Fixed security issues + +You can view the security issues fixed in {product} {product-version} at link:https://access.redhat.com/security/security-updates/cve?q=red+hat+developer+hub&p=1&sort=cve_publicDate+desc,allTitle+desc&rows=10&documentKind=Cve[Red Hat Security Updates]. \ No newline at end of file diff --git a/modules/release-notes/ref-release-notes-new-features.adoc b/modules/release-notes/ref-release-notes-new-features.adoc index a9fe742256..d3c9620d48 100644 --- a/modules/release-notes/ref-release-notes-new-features.adoc +++ b/modules/release-notes/ref-release-notes-new-features.adoc @@ -4,5 +4,156 @@ This section highlights new features in {product} {product-version}. -None. +[id="feature-rhidp-3597"] +== OpenTelemetry metrics support added to the Keycloak backend plugin + +With this update, the Keycloak backend plugin supports OpenTelemetry metrics, which monitors fetch operations and diagnoses potential issues. + +The available counters include the following: + +* `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.​ + +These counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task, and allows you to trace failures back to individual task executions. + +Example configuration: + +```text +backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1 +``` + +You can export metrics using any OpenTelemetry-compatible backend, such as **Prometheus**. + + +[id="enhancement-rhidp-5039"] +== Enhanced session duration control and refresh token cookie policy + +With this update, the maximum age of the refresh token cookie has been reduced to 400 days to align with the modern web browser policies. Additionally, a new configurable field, `sessionDuration`, has been introduced in the supported authentication providers. This allows administrators to specify custom user session durations, enabling better control over session timeouts and enforced logouts. + +For more information, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.5/html-single/authentication_in_red_hat_developer_hub/index#idm140459408106672[Authentication in {product}]. + +[id="enhancement-rhidp-5987"] +== Updated Auditor Service + +{product} {product-version} introduces an enhancement to the RBAC and Bulk Import plugins, enabling users to utilize Backstage's new Auditor service. The key features include: ​ + +* Audit log format update: + +The audit log format has been updated to align with the new Auditor service conventions. Audit fields and event identifiers have been updated. Filtering queries based on the old format may no longer function as expected.​ + +* Backend Plugin API integration: + +The audit log is now backed by the `@backstage/backend-plugin-api` package.​ + +* Audit events Grouping: + +The Bulk Import backend plugin emits audit events for various operations, with the events are grouped logically by `eventId`.​ + + + + +[id="feature-rhidp-6158"] +== Renamed `Create` to `Self-service` + +The term `Create` has been renamed to `Self-service` across key UI areas to better align with the self-service functionality provided through the Backstage scaffolder, enhancing clarity for users. + +This change applies to the following areas: + +* Sidebar navigation +* Global header +* Catalog page +* Scaffolder page + +[id="enhancement-rhidp-6173"] +== Simplify Operator-backed deployments on OpenShift with automatic `baseUrl` configuration + +Previously, deploying {product-short} using the Operator required manually configuring the `baseUrl` settings in the custom app-config ConfigMap. + +With this update, the Operator can now automatically compute the default application URL based on the OpenShift cluster ingress domain and the custom Route settings in the `Backstage` Custom Resource. It will then populate this as the default `baseUrl` in the app-config ConfigMap that it generates for the {product-short} instance. This functionality is specific to OpenShift. The Operator fills the following fields in the default app-config ConfigMap: `app.baseUrl`, `backend.baseUrl`, and `backend.cors.origin`. As a result, this eliminates the need to manually set such values for most Operator-backed deployments on OpenShift, though you can still override these settings in your custom app-config ConfigMap. + +[id="enhancement-rhidp-6184"] +== New sidebar item visibility configuration + +{product} now supports a clean and flexible way to hide sidebar items using a new enabled key in the sidebar menu configuration. If set to false, the specified sidebar item will no longer appear in the UI, while maintaining full backward compatibility with existing configurations. + +Example configuration: +[source,yaml] +---- +dynamicPlugins: + frontend: + default.main-menu-items: + menuItems: + default.home: + title: Home + icon: home + enabled: false + default.list: + title: References + icon: bookmarks + default.my-group: + parent: default.list + default.learning-path: + parent: default.list + title: '' + default.homepage: + title: HomePage 123 + icon: home + enabled: false + default.create: + title: Create + icon: add + parent: default.homepage +---- + +You can now also toggle visibility of core sidebar elements like the logo, search, settings, and administration as shown: + +[source,yaml] +---- +app: + sidebar: + search: false # hides sidebar search + logo: false # hides sidebar logo + settings: false # hides settings item + administration: false # hides administration item +---- + +[id="feature-rhidp-6253"] +== {product-short} community plugins updated to Backstage 1.36 + +The {product-short} community plugins have been updated to Backstage version 1.36. + +[id="feature-rhidp-6269"] +== Added a new RBAC conditional rule `IS_OWNER` to RBAC plugin + +{product} introduces a new RBAC conditional rule, `IS_OWNER`, that allows administrators to assign ownership to roles and control access to the RBAC plugin. This enhancement enables more granular access control by allowing ownership-based filtering of roles, permission policies, and conditional policies. + +This enhancement removes the resource type from the `policy.entity.create` permission, preventing conditional rules from being applied to the permission. You can update all permission policies that utilize the resource type `policy-entity` with the action `create` (for example `role:default/some_role, policy-entity, create, allow` to `role:default/some_role, policy.entity.create, create, allow`) to prevent degradation in the future. + + +[id="feature-rhidp-6555"] +== Support for high availability in {aks-brand-name} + +{product} now supports high availability setups in {aks-brand-name} ({aks-short}). This enhancement allows the deployment to scale beyond a single replica, ensuring the application remains operational and accessible even in the event of failures or disruptions. + +For more information, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.5/html-single/configuring_red_hat_developer_hub/index#HighAvailability[_Configuring high availability in Red Hat Developer Hub_]. + +[id="feature-rhidp-6764"] +== Added `@backstage/plugin-scaffolder-backend-module-github` plugin for {product-short} + +{product} now supports the `@backstage/plugin-scaffolder-backend-module-github` plugin, enabling GitHub Actions within software templates. With this integration, you can securely create and manage repositories, open pull requests, trigger GitHub Actions workflows, and more, all directly from the software template. This plugin empowers users to automate GitHub interactions and workflows with ease. + +[id="enhancement-rhidp-6882"] +== Default OIDC sign-in resolver updated + +With this update, the default resolver for OIDC sign-in is set to `oidcSubClaimMatchingKeycloakUserId` to enhance security. This resolver is now also available as a configurable option under the sign-in resolver settings. + +[id="feature-rhidp-7424"] +== New dynamic plugin for Kubernetes scaffolder actions + +With this update, {product-short} introduces the @backstage-community/plugin-scaffolder-backend-module-kubernetes plugin as a dynamic plugin, enabling Backstage template actions for Kubernetes. Currently, it includes the create-namespace action. This dynamic plugin is disabled by default. + +For more information, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.5/html-single/dynamic_plugins_reference/index#red-hat-supported-plugins[{company-name} supported plugins]. + + diff --git a/modules/release-notes/single-source-fixed-security-issues.sh b/modules/release-notes/single-source-fixed-security-issues.sh deleted file mode 100755 index 4fa0864f95..0000000000 --- a/modules/release-notes/single-source-fixed-security-issues.sh +++ /dev/null @@ -1,62 +0,0 @@ -#!/bin/bash -# -# Copyright (c) 2024 Red Hat, Inc. -# This program, and the accompanying materials are made -# available under the terms of the Apache Public License 2.0, -# available at http://www.apache.org/licenses/ -# -# SPDX-License-Identifier: Apache-2.0 - -# Single-source the release notes Fixed security issues section from Red Hat Security Data API. -# See: https://docs.redhat.com/en/documentation/red_hat_security_data_api/1.0/html/red_hat_security_data_api/cve - -# Fail and stop on first error -set -e - -# get the z-stream version from the bundle-version attribute. Note that while chart-version could be larger, this is the correct value for CVE tracking -product_version="$(grep ':product-bundle-version:' artifacts/attributes.adoc | cut -d' ' -f2 )" - -single_source_from_security_data () { - sectionname="fixed-security-issues-in-${section}-${product_version}" - dirname=$(dirname ${BASH_SOURCE}) - destination="${dirname}/snip-${sectionname}.adoc" - list="${dirname}/list-${sectionname}.txt" - # Assert that the list file exists. - if [ ! -f ${list} ] - then - echo "ERROR: The ${list} file is missing. You must create it to proceed. For a given version, can collect the list of CVEs from a JIRA query like https://issues.redhat.com/issues/?jql=labels%3DSecurityTracking+and+project%3DRHIDP+and+fixversion%3D1.3.1 or list of Erratas from https://errata.devel.redhat.com/advisory/filters/4213" - exit 1 - fi - # Cleanup the destination files. - rm -f "$destination" - # Send output to the destination file. - exec 3>&1 1>> "$destination" - echo "= ${title}" - for cve in $(cat ${list} | sort | uniq) - do - # Start the list. - echo "link:https://access.redhat.com/security/cve/$cve[$cve]::" - # Call the API to return a list of details. - # Red Hat is last if there is one. - # Red Hat details is single line. - # MITRE details are multiline. - # We keep Red Hat details if present. - # We keep only the first two lines on MITRE details. - curl -s "https://access.redhat.com/hydra/rest/securitydata/cve/$cve.json" | jq -r '.details[-1]' | head -n 2 - # Add a separation - echo "" - done - # Stop sending output to the destination file - exec 1>&3 3>&- - echo "include::${destination}[leveloffset=+2]" -} - -title="{product} dependency updates" -section="product" -single_source_from_security_data - -title="RHEL 9 platform RPM updates" -section="rpm" -single_source_from_security_data - -echo "INFO: Verify that the assemblies/assembly-release-notes-fixed-security-issues.adoc file contains aforementioned required include statements." diff --git a/modules/release-notes/single-source-release-notes-template.adoc.jinja b/modules/release-notes/single-source-release-notes-template.adoc.jinja index df688e75f1..c7fa9a3a3a 100644 --- a/modules/release-notes/single-source-release-notes-template.adoc.jinja +++ b/modules/release-notes/single-source-release-notes-template.adoc.jinja @@ -10,11 +10,11 @@ == {{ title }} in {{ fixversion }} {% endif %} [id="{{ issue.fields.customfield_12320850 | lower | replace(" ", "-") }}-{{ issue.key | lower }}"] -=== {{ issue.fields.summary }} -{% else -%} +== +{%- else -%} [id="{{ issue.fields.customfield_12320850 | lower | replace(" ", "-") }}-{{ issue.key | lower }}"] -== {{ issue.fields.summary }} -{% endif %} += +{%- endif -%} {{ issue.fields.customfield_12317313 }} {% if template == "with-jira-link" or template == "with-z-stream-section" %} diff --git a/modules/release-notes/single-source-release-notes.jira2asciidoc.yml b/modules/release-notes/single-source-release-notes.jira2asciidoc.yml index 69fb977143..222f03e137 100644 --- a/modules/release-notes/single-source-release-notes.jira2asciidoc.yml +++ b/modules/release-notes/single-source-release-notes.jira2asciidoc.yml @@ -61,7 +61,28 @@ sections: AND "Release Note Status" = "Done" AND level is EMPTY AND status in (Closed, "Release Pending") - AND "Release Note Type" in ("Developer Preview", "Technology Preview") + AND "Release Note Type" in ("Technology Preview") + AND fixVersion >= "{version_minor}" + AND fixVersion <= "{version_patch}" + ORDER BY key + template: with-jira-link + - id: developer-preview + title: Developer Preview + description: | + This section lists Developer Preview features in {product} {product-version}. + + [IMPORTANT] + ==== + Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + + For more information about the support scope of Red Hat Developer Preview features, see link:https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. + ==== + query: > + project = "Red Hat Internal Developer Platform" + AND "Release Note Status" = "Done" + AND level is EMPTY + AND status in (Closed, "Release Pending") + AND "Release Note Type" in ("Developer Preview") AND fixVersion >= "{version_minor}" AND fixVersion <= "{version_patch}" ORDER BY key diff --git a/modules/release-notes/single-source-release-notes.py b/modules/release-notes/single-source-release-notes.py index 1e2bf22ff1..94be9e5bcc 100755 --- a/modules/release-notes/single-source-release-notes.py +++ b/modules/release-notes/single-source-release-notes.py @@ -47,11 +47,8 @@ items = lines.rsplit(':', 2) attributes[items[1]] = items[2].strip() -product_version_minor = attributes["product-version"] +product_version_minor = attributes["product-version"] + ".0" product_version_patch = attributes["product-bundle-version"] -# Until 1.4 at least, Jira has no z-stream 0. Use the y-stream instead. -if re.search('.0$',product_version_patch): - product_version_patch = product_version_minor # Load the configuration file to get the sections and their Jira queries. with open(config_file) as file: diff --git a/modules/release-notes/snip-fixed-security-issues-in-product-1.3.0.adoc b/modules/release-notes/snip-fixed-security-issues-in-product-1.3.0.adoc deleted file mode 100644 index 9de02ac2b4..0000000000 --- a/modules/release-notes/snip-fixed-security-issues-in-product-1.3.0.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= {product} dependency updates -link:https://access.redhat.com/security/cve/CVE-2024-24790[CVE-2024-24790]:: -A flaw was found in the Go language standard library net/netip. The method Is*() (IsPrivate(), IsPublic(), etc) doesn't behave properly when working with IPv6 mapped to IPv4 addresses. The unexpected behavior can lead to integrity and confidentiality issues, specifically when these methods are used to control access to resources or data. - -link:https://access.redhat.com/security/cve/CVE-2024-24791[CVE-2024-24791]:: -A flaw was found in Go. The net/http module mishandles specific server responses from HTTP/1.1 client requests. This issue may render a connection invalid and cause a denial of service. - -link:https://access.redhat.com/security/cve/CVE-2024-35255[CVE-2024-35255]:: -A flaw was found in the Azure identity library at github.com/Azure/azure-sdk-for-go/sdk/azidentity. This issue allows an elevation of privileges. - -link:https://access.redhat.com/security/cve/CVE-2024-37891[CVE-2024-37891]:: -A flaw was found in urllib3, an HTTP client library for Python. In certain configurations, urllib3 does not treat the `Proxy-Authorization` HTTP header as one carrying authentication material. This issue results in not stripping the header on cross-origin redirects. - -link:https://access.redhat.com/security/cve/CVE-2024-39008[CVE-2024-39008]:: -A flaw was found in the fast-loops Node.js package. This flaw allows an attacker to alter the behavior of all objects inheriting from the affected prototype by passing arguments to the objectMergeDeep function crafted with the built-in property: __proto__. This issue can potentially lead to a denial of service, remote code execution, or Cross-site scripting. - -link:https://access.redhat.com/security/cve/CVE-2024-39249[CVE-2024-39249]:: -A flaw was found in the async Node.js package. A Regular expression Denial of Service (ReDoS) attack can potentially be triggered via the autoinject function while parsing specially crafted input. - diff --git a/modules/release-notes/snip-fixed-security-issues-in-rpm-1.3.0.adoc b/modules/release-notes/snip-fixed-security-issues-in-rpm-1.3.0.adoc deleted file mode 100644 index cf700007bc..0000000000 --- a/modules/release-notes/snip-fixed-security-issues-in-rpm-1.3.0.adoc +++ /dev/null @@ -1,92 +0,0 @@ -= RHEL 9 platform RPM updates -link:https://access.redhat.com/security/cve/CVE-2023-52439[CVE-2023-52439]:: -A flaw was found in the Linux kernel’s uio subsystem. A use-after-free memory flaw in the uio_open functionality allows a local user to crash or escalate their privileges on the system. - -link:https://access.redhat.com/security/cve/CVE-2023-52884[CVE-2023-52884]:: -In the Linux kernel, the following vulnerability has been resolved: -Input: cyapa - add missing input core locking to suspend/resume functions - -link:https://access.redhat.com/security/cve/CVE-2024-26739[CVE-2024-26739]:: -A use-after-free flaw was found in net/sched/act_mirred.c in the Linux kernel. This may result in a crash. - -link:https://access.redhat.com/security/cve/CVE-2024-26929[CVE-2024-26929]:: -In the Linux kernel, the following vulnerability has been resolved: -scsi: qla2xxx: Fix double free of fcport - -link:https://access.redhat.com/security/cve/CVE-2024-26930[CVE-2024-26930]:: -A vulnerability was found in the Linux kernel. A potential double-free in the pointer ha->vp_map exists in the Linux kernel in drivers/scsi/qla2xxx/qla_os.c. - -link:https://access.redhat.com/security/cve/CVE-2024-26931[CVE-2024-26931]:: -In the Linux kernel, the following vulnerability has been resolved: -scsi: qla2xxx: Fix command flush on cable pull - -link:https://access.redhat.com/security/cve/CVE-2024-26947[CVE-2024-26947]:: -A flaw was found in the Linux kernel’s ARM memory management functionality, where certain memory layouts cause a kernel panic. This flaw allows an attacker who can specify or alter memory layouts to cause a denial of service. - -link:https://access.redhat.com/security/cve/CVE-2024-26991[CVE-2024-26991]:: -A flaw was found in the Linux Kernel. A lpage_info overflow can occur when checking attributes. This may lead to a crash. - -link:https://access.redhat.com/security/cve/CVE-2024-27022[CVE-2024-27022]:: -In the Linux kernel, the following vulnerability has been resolved: -fork: defer linking file vma until vma is fully initialized - -link:https://access.redhat.com/security/cve/CVE-2024-35895[CVE-2024-35895]:: -In the Linux kernel, the following vulnerability has been resolved: -bpf, sockmap: Prevent lock inversion deadlock in map delete elem - -link:https://access.redhat.com/security/cve/CVE-2024-36016[CVE-2024-36016]:: -In the Linux kernel, the following vulnerability has been resolved: -tty: n_gsm: fix possible out-of-bounds in gsm0_receive() - -link:https://access.redhat.com/security/cve/CVE-2024-36899[CVE-2024-36899]:: -In the Linux kernel, the following vulnerability has been resolved: -gpiolib: cdev: Fix use after free in lineinfo_changed_notify - -link:https://access.redhat.com/security/cve/CVE-2024-38562[CVE-2024-38562]:: -In the Linux kernel, the following vulnerability has been resolved: -wifi: nl80211: Avoid address calculations via out of bounds array indexing - -link:https://access.redhat.com/security/cve/CVE-2024-38570[CVE-2024-38570]:: -In the Linux kernel, the following vulnerability has been resolved: -gfs2: Fix potential glock use-after-free on unmount - -link:https://access.redhat.com/security/cve/CVE-2024-38573[CVE-2024-38573]:: -A NULL pointer dereference flaw was found in cppc_cpufreq_get_rate() in the Linux kernel. This issue may result in a crash. - -link:https://access.redhat.com/security/cve/CVE-2024-38601[CVE-2024-38601]:: -In the Linux kernel, the following vulnerability has been resolved: -ring-buffer: Fix a race between readers and resize checks - -link:https://access.redhat.com/security/cve/CVE-2024-38615[CVE-2024-38615]:: -In the Linux kernel, the following vulnerability has been resolved: -cpufreq: exit() callback is optional - -link:https://access.redhat.com/security/cve/CVE-2024-39331[CVE-2024-39331]:: -A flaw was found in Emacs. Arbitrary shell commands can be executed without prompting when an Org mode file is opened or when the Org mode is enabled, when Emacs is used as an email client, this issue can be triggered when previewing email attachments. - -link:https://access.redhat.com/security/cve/CVE-2024-40984[CVE-2024-40984]:: -In the Linux kernel, the following vulnerability has been resolved: -ACPICA: Revert "ACPICA: avoid Info: mapping multiple BARs. Your kernel is fine." - -link:https://access.redhat.com/security/cve/CVE-2024-41071[CVE-2024-41071]:: -An out-of-bounds buffer overflow has been found in the Linux kernel’s mac80211 subsystem when scanning for SSIDs. Address calculation using out-of-bounds array indexing could result in an attacker crafting an exploit, resulting in the complete compromise of a system. - -link:https://access.redhat.com/security/cve/CVE-2024-42225[CVE-2024-42225]:: -A potential flaw was found in the Linux kernel’s MediaTek WiFi, where it was reusing uninitialized data. This flaw allows a local user to gain unauthorized access to some data potentially. - -link:https://access.redhat.com/security/cve/CVE-2024-42246[CVE-2024-42246]:: -In the Linux kernel, the following vulnerability has been resolved: -net, sunrpc: Remap EPERM in case of connection failure in xs_tcp_setup_socket - -link:https://access.redhat.com/security/cve/CVE-2024-45490[CVE-2024-45490]:: -A flaw was found in libexpat's xmlparse.c component. This vulnerability allows an attacker to cause improper handling of XML data by providing a negative length value to the XML_ParseBuffer function. - -link:https://access.redhat.com/security/cve/CVE-2024-45491[CVE-2024-45491]:: -An issue was found in libexpat’s internal dtdCopy function in xmlparse.c, It can have an integer overflow for nDefaultAtts on 32-bit platforms where UINT_MAX equals SIZE_MAX. - -link:https://access.redhat.com/security/cve/CVE-2024-45492[CVE-2024-45492]:: -A flaw was found in libexpat's internal nextScaffoldPart function in xmlparse.c. It can have an integer overflow for m_groupSize on 32-bit platforms where UINT_MAX equals SIZE_MAX. - -link:https://access.redhat.com/security/cve/CVE-2024-6119[CVE-2024-6119]:: -A flaw was found in OpenSSL. Applications performing certificate name checks (e.g., TLS clients checking server certificates) may attempt to read an invalid memory address resulting in abnormal termination of the application process. - diff --git a/modules/techdocs/con-techdocs-about.adoc b/modules/techdocs/con-techdocs-about.adoc new file mode 100644 index 0000000000..d8249c3fcd --- /dev/null +++ b/modules/techdocs/con-techdocs-about.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: CONCEPT + +[id="about-techdocs_{context}"] += About TechDocs + +The {product} instance comes with the TechDocs plugin preinstalled and enabled by default. Your organization can use the TechDocs plugin to create, find, and manage documentation in a central location and in a standardized way. You can also enhance your technical documentation experience with built-in TechDocs features and add-ons. For example: + +Docs-like-code approach:: +Write your technical documentation in Markdown files that are stored inside your project repository along with your code. + +Documentation site generation:: +Use MkDocs to create a full-featured, Markdown-based, static HTML site for your documentation that is rendered centrally in {product-short}. + +Documentation site metadata and integrations:: +See additional metadata about the documentation site alongside the static documentation, such as the date of the last update, the site owner, top contributors, open GitHub issues, Slack support channels, and Stack Overflow Enterprise tags. + +Built-in navigation and search:: +Locate the information that you need within a document quickly and easily. + +Add-ons:: +Make your documentation more functional and interactive with supported TechDocs add-ons. Some add-ons are preinstalled and enabled by default. To extend the default functionality, you can dynamically load external and third-party add-ons into your {product} instance. If you want to further customize your TechDocs experience, you can create add-ons that meet specific documentation needs for your organization. diff --git a/modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc b/modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc new file mode 100644 index 0000000000..fd38baf500 --- /dev/null +++ b/modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-add-docs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-add-docs-from-remote-repo_{context}"] += Importing documentation into TechDocs from a remote repository + +Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a remote repository that contains the documentation files that your team uses. + +.Prerequisites + +* Your organization has documentation files stored in a remote repository. +* You have a `mkdocs.yaml` file in the root directory of your repository. +* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository. + +.Procedure + +. In your {product} instance, click *Catalog > Self-service > Register Existing Component*. +. In the *Select URL* box, enter the URL to the `catalog-info.yaml` file that you want to import from your repository using the following format: ++ +`https://github.com/_<project_name>_/_<repo_name>_/blob/_<branch_name>_/_<file_directory>_/catalog-info.yaml` ++ +. Click *Analyze* +. Click *Finish* + +.Verification + +. In the {product} navigation menu, click *Docs*. +. Verify that the documentation that you imported is listed in the table on the *Documentation* page. diff --git a/modules/techdocs/proc-techdocs-addon-create.adoc b/modules/techdocs/proc-techdocs-addon-create.adoc new file mode 100644 index 0000000000..0c452e9932 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-create.adoc @@ -0,0 +1,149 @@ +// Module included in the following assemblies: +// +// [WIP] file created but not currently part of any assembly or title + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-create_{context}"] +== Creating a TechDocs add-on + +If your organization has documentation needs that are not met by the functions of existing TechDocs add-ons, developers can create a new add-on for your TechDocs plugin. + +A TechDocs add-on is a React component that is imported from a front-end plugin. If you do not have an existing plugin that you can use to export your TechDocs add-on, you can create a new plugin by using `backstage-cli` to generate a default front-end plugin structure that you can customize. + +The folder structure of a new plugin that can be used to import TechDocs add-ons into the TechDocs plugin looks similar to the following example: +[source,json,subs="+attributes,+quotes"] +---- +_<new_plugin_for_techdocs_add-on>_/ + dev/ + index.ts + src/ + components/ + _<new_techdocs_add-on_component>_/ + _<new_techdocs_add-on_component>_.test.tsx + _<new_techdocs_add-on_component>_.tsx + index.ts + _<new_techdocs_add-on_fetch-component>_/ + _<new_techdocs_add-on_fetch-component>_.test.tsx + _<new_techdocs_add-on_fetch-component>_.tsx + index.ts + index.ts + plugin.test.ts + plugin.ts + routes.ts + setupTests.ts + .eslintrc.js + package.json + README.md +---- + +.Prerequisites +* The `yarn` package manager is installed. +* Docker v3.2.0 or later or Podman v3.2.0 or later is installed and running. + +.Procedure +. In the terminal, navigate to the root folder of the repository where you want to create your new plugin. +. To create a new front-end plugin, run the following command: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +yarn new +---- +.Example output ++ +[source,terminal,subs="+quotes"] +---- +? What do you want to create? plugin - A new frontend plugin +? Enter the ID of the plugin [required] +---- ++ +. In the terminal prompt, type a name for the new plugin. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +? Enter the ID of the plugin [required] _<new_plugin_for_techdocs_add-on>_ +---- ++ +.Example output ++ +[source,terminal,subs="+attributes,+quotes"] +---- +Successfully created plugin +---- ++ +.Result +In the `plugins` directory, a sub-directory with the same name that you gave to your plugin is automatically generated. The directory contains all of the files that you need to configure to create your new plugin. ++ +. In the terminal, navigate to your new plugin directory. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +cd plugins/_<new_techdocs_add-on_directory>_ +---- +. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +yarn add @backstage/plugin-techdocs-react +---- +. In the directory containing the components of your custom TechDocs add-on, delete any default files or file components that are not required for your add-on, such as the `routes.ts` file or components of the `index.tsx` and `plugins.ts` files. +. In the `plugins.ts` file, add the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +import { createPlugin } from '@backstage/core-plugin-api'; +import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react'; + +export const _<new_plugin_for_techdocs_add-on>_ = createPlugin({ + id: '_<new_techdocs_add-on>_', + }); + + /* + * + * @public + */ +export const _<new_techdocs_add-on>_ = _<new_plugin_for_techdocs_add-on>_.provide( + createTechDocsAddonExtension<_<new_techdocs_addon_props>_>({ + name: '_<new_techdocs_add-on>_', + location: TechDocsAddonLocations.Content, + component: _<new_techdocs_add-on_component>_, + }), +); +---- ++ +where + +_<new_plugin_for_techdocs_add-on>_ :: Specifies the new plugin that you use to import the TechDocs add-on to your {product} instance. +_<new_techdocs_add-on>_ :: Specifies the custom TechDocs add-on that you want to create. +_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable. +_<new_techdocs_add-on_component>_ :: Specifies the React component for the custom TechDocs add-on that you want to create. You will create this component in a `.tsx` file in a later step. +. In the `index.ts` file, export the custom TechDocs add-on that you want to create by adding the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +export { _<new_plugin_for_techdocs_add-on>_, _<new_techdocs_add-on>_ } from './plugin'; +---- +. Create a new `_<new_techdocs_add-on>_.tsx` file and add the code for your new TechDocs add-on component. ++ +//// +[source,java,subs="+attributes,+quotes"] +---- +can add example code for this file, if helpful +can also mention a template that the user can configure, if there is one +---- +//// +. Create a new `index.tsx` file and use it to export your new TechDocs add-on component by adding the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +export { _<new_techdocs_add-on>_, type _<new_techdocs_addon_props>_} from './_<new_techdocs_add-on_directory>_' +---- ++ +where + +_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable. +. In the `plugins.ts` file, import your new TechDocs add-on component. +. Install and configure your new TechDocs add-on by following the steps in link:{techdocs-book-url}#techdocs-addon-installing[Installing and configuring a TechDocs add-on] + +.Verification +. Restart the RHDH application and verify that the plugin is successfully activated and configured. +. Verify the application logs for confirmation and ensure the plugin is functioning as expected. diff --git a/modules/techdocs/proc-techdocs-addon-install-helm.adoc b/modules/techdocs/proc-techdocs-addon-install-helm.adoc new file mode 100644 index 0000000000..68ccbb27c3 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-helm.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-helm_{context}"] +== Installing and configuring an external TechDocs add-on using the Helm chart + +You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Helm chart to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your Helm chart. + +Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file. + +.Prerequisites +* The TechDocs plugin is installed and enabled. + +.Procedure +. In your Helm chart, add the `global.dynamic` parameters required to install a dynamic plugin, as shown in link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about#con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart ] ++ +[NOTE] +==== +The default configuration includes the `dynamic-plugins.default.yaml` file, which contains all of the dynamic plugins, including TechDocs add-ons, that are preinstalled in {product}, whether they are enabled or disabled by default. +==== +. In your Helm chart, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue +---- +. In the `techdocsAddons` section of the Helm chart, add `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to add from the specified plugin package. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`. + +//.Next steps \ No newline at end of file diff --git a/modules/techdocs/proc-techdocs-addon-install-operator.adoc b/modules/techdocs/proc-techdocs-addon-install-operator.adoc new file mode 100644 index 0000000000..ce175771b3 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-operator.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-operator_{context}"] +== Installing and configuring an external TechDocs add-on using the Operator + +You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Operator to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your ConfigMap. + +Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file. + +.Procedure + +. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps* > *Create ConfigMap*. +. From the *Create ConfigMap* page, select the *YAML view* option in the *Configure via* field. +. In the newly created ConfigMap, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue +---- +. In the `techdocsAddons` section of the ConfigMap, add `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to add from the specified plugin package. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`. +. Click *Create*. +. In the web console navigation menu, click *Topology*. +. Click on the overflow menu for the {product} instance that you want to use and select *Edit Backstage* to load the YAML view of the {product} instance. +. In your `{product-custom-resource-type}` CR, add the `dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_` key-value pair. For example: ++ +[source,yaml] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: my-rhdh +spec: + application: +# ... + dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_ +# ... +---- ++ +where: + +_<dynamic_plugins_configmap>_:: Specifies the name of your dynamic plugins ConfigMap for your {product} instance, for example, `dynamic-plugins-rhdh`. +. Click *Save*. +. In the web console navigation menu, click *Topology* and wait for the {product} pod to start. +. Click the *Open URL* icon to start using the {product} platform with the new configuration changes. + +//.Next steps diff --git a/modules/techdocs/proc-techdocs-addon-install-third-party.adoc b/modules/techdocs/proc-techdocs-addon-install-third-party.adoc new file mode 100644 index 0000000000..650b136917 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-third-party.adoc @@ -0,0 +1,86 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-third-party_{context}"] +== Installing and configuring a third-party TechDocs add-on + +You can install compatible third-party TechDocs add-on on your {product} instance as a front-end dynamic plugin. + +.Prerequisites +* The third-party TechDocs add-on has a valid `package.json` file in its root directory, containing all required metadata and dependencies. +* The third-party plugin is packaged as a dynamic plugin in an OCI image. For alternative package types, see link:https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/release-1.5/plugins-rhdh-install/#assembly-install-third-party-plugins-rhdh[Installing third-party plugins in Red Hat Developer Hub]. +* You have installed the `yarn` package manager. +* The third-party plugin is packaged as a dynamic plugin in an OCI image.* You have installed and configured Node.js and NPM. + +.Procedure +. Install the third-party plugin that you want to use to import your third-party add-on by entering the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +yarn install +---- +. Obtain the source code for the third-party TechDocs add-on that you want to use. +. Export the TechDocs add-on as a dynamic plugin using the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +npx @janus-idp/cli@latest package export-dynamic-plugin +---- ++ +[NOTE] +==== +The `@latest` tag pulls the latest version of the @janus-idp/cli package, which is compatible with the most recent features and fixes. Use a version that is compatible with your {product} version. +==== +. To package the third-party TechDocs add-on as a dynamic plugin, navigate to the root directory where the plugin is stored (not the dist-dynamic directory) and run the `npx` command with the `--tag` option to specify the image name and tag. For example: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest +---- ++ +[NOTE] +==== +The output of the package-dynamic-plugins command provides the file path to the plugin for use in the `dynamic-plugin-config.yaml` file. +==== ++ +. To publish the third-party TechDocs add-on to a Quay repository, push the image to a registry using one of the following commands, depending on your virtualization tool: +* To use `podman`, enter the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +podman push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest +---- +* To use `docker`, enter the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +docker push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest +---- +. Open your `dynamic-plugins.yaml` file to view or modify the configuration for the third-party TechDocs add-on. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +plugins: + - package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest!_<techdocs_add-on_package>_ + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + _<techdocs_add-on_package>_ + techdocsAddons: + - importName: _<third-party_add-on_name>_ + config: + props: + _<techdocs_add-on_property_key>_: _<techdocs_add-on_property_value>_ +---- ++ +where + +_<user_name>_ :: Specifies your Quay user name or organization name. +_<techdocs_add-on_image>_ :: Specifies the name of the image for the third-party add-on that you want to use, for example, `mermaid`. +_<techdocs_add-on_package>_ :: Specifies the , for example, `backstage-plugin-techdocs-addon-mermaid`. +_<third-party_add-on_name>_ :: Specifies the name of the third-party add-on that you want to use, for example, `Mermaid`. +_<techdocs_add-on_property_key>_ :: Specifies the name of the custom property that can be passed to the third-party add-on, for example, `themeVariables`. Properties are specific to each add-on. You can list multiple properties for an add-on. +_<techdocs_add-on_property_value>_ :: Specifies the value of a property key for the third-party add-on, for example, `lineColor: #000000`. diff --git a/modules/techdocs/proc-techdocs-addon-remove-helm.adoc b/modules/techdocs/proc-techdocs-addon-remove-helm.adoc new file mode 100644 index 0000000000..3c0a6dc112 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-remove-helm.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-removing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-remove-helm_{context}"] +== Removing an external TechDocs add-on from your Helm chart + +If you no longer want to use the functionality of a TechDocs add-on that is imported from a particular plugin that you installed on your {product} instance with the Helm chart, you can temporarily disable it or permanently remove it from your Helm chart. The `disabled` status is controlled at the plugin level, therefore, disabling the plugin disables all of the TechDocs add-ons in the disabled plugin package. + +.Procedure +* In the `plugins` section of the Helm chart, do one of the following actions based on whether you want to disable or remove a TechDocs add-on: +** To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the `disabled` field to `true`. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: true + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +** To remove one or more TechDocs add-ons from your {product} instance, delete `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to remove from the `techdocsAddons` section of your Helm chart. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. + +//.Next steps \ No newline at end of file diff --git a/modules/techdocs/proc-techdocs-addon-remove-operator.adoc b/modules/techdocs/proc-techdocs-addon-remove-operator.adoc new file mode 100644 index 0000000000..5ed5685463 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-remove-operator.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-removing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-remove-operator_{context}"] +== Removing an external TechDocs add-on from your ConfigMap + +If you no longer want to use the functionality of a TechDocs add-on that is imported from a particular plugin that you installed on your {product} instance with the Operator, you can temporarily disable it or permanently remove it from your ConfigMap. The `disabled` status is controlled at the plugin level, therefore, disabling the plugin disables all of the TechDocs add-ons in the disabled plugin package. + +.Procedure + +. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps*. +. From the *ConfigMaps* page, click the ConfigMap that contains the TechDocs add-on that you want to remove. +. Select the *YAML view* option in the *Configure via* field. +. In the `plugins` section of the ConfigMap, do one of the following actions based on whether you want to disable or remove a TechDocs add-on: +** To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the `disabled` field to `true`. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: true + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +** To remove one or more TechDocs add-ons from your {product} instance, delete `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to remove from the `techdocsAddons` section of your ConfigMap. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: _<external_techdocs_add-on>_ +---- ++ +where: + +_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +. Click *Save*. +. In the web console navigation menu, click *Topology* and wait for the {product} pod to start. +. Click the *Open URL* icon to start using the {product} platform with the new configuration changes. + +//.Next steps diff --git a/modules/techdocs/proc-techdocs-addon-use-light-box.adoc b/modules/techdocs/proc-techdocs-addon-use-light-box.adoc new file mode 100644 index 0000000000..6d5f547d03 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-light-box.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-light-box_{context}"] +== Using the LightBox TechDocs add-on + +If your TechDocs documentation contains an image, you can use the `LightBox` add-on to view an enlarged version of the image in a lightbox, or overlay window. You can also zoom to change the size the lightbox image. If a single documentation page contains multiple images, you can navigate between images in the lightbox. + +.Prerequisites +* The `LightBox` add-on is installed and enabled in your TechDocs plugin. + +.Procedure +. In your TechDocs documentation, click on the image that you want to view in a lightbox. +. In the lightbox, you can do any of the following actions: +* Click the image or scroll to zoom in or zoom out. +* Click the arrow to navigate between images. diff --git a/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc b/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc new file mode 100644 index 0000000000..0d4ccb6d0f --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-report-issue_{context}"] +== Using the ReportIssue TechDocs add-on + +If you find an error in your organization's TechDocs documentation, you can use the `ReportIssue` add-on to open a new GitHub or GitLab issue directly from the documentation. `ReportIssue` automatically imports the text that you highlight in the document into a new issue template in your repository. + +.Prerequisites +* The `ReportIssue` add-on is installed and enabled in your TechDocs plugin. +* You have permissions to create issues in the repository where documentation issues are reported. + +.Procedure +. In your TechDocs documentation, highlight the text that you want to report an issue for. +. Click the text in the `ReportIssue` box, for example, *Open new GitHub issue*. +. From the new issue page in your repository, use the template to create the issue that you want to report. ++ +[NOTE] +==== +The default issue title is *Documentation feedback: _<highlighted_text>_*, where _<highlighted_text>_ is the text that you highlighted in your TechDocs documentation. + +In the issue description, _<highlighted_text>_ is the default value for the *The highlighted text* field. +==== + +.Verification +* The issue that you created is listed on the issues page in your repository. diff --git a/modules/techdocs/proc-techdocs-addon-use-text-size.adoc b/modules/techdocs/proc-techdocs-addon-use-text-size.adoc new file mode 100644 index 0000000000..dda295bf52 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-text-size.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-text-size_{context}"] +== Using the TextSize TechDocs add-on + +You can use the `TextSize` add-on to change the size of the text on either the TechDocs Reader page or an Entity page. + +.Prerequisites +* The `TextSize` add-on is installed and enabled in your TechDocs plugin. + +.Procedure +. In your TechDocs header, click the *Settings* icon. +. Use the sliding scale to adjust the size of your documentation text. ++ +[NOTE] +==== +* The default text size is 100% +* The minimize text size is 90% +* The maximum text size is 150% +==== diff --git a/modules/techdocs/proc-techdocs-edit-docs.adoc b/modules/techdocs/proc-techdocs-edit-docs.adoc new file mode 100644 index 0000000000..e93a38f03c --- /dev/null +++ b/modules/techdocs/proc-techdocs-edit-docs.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-edit-docs_{context}"] += Editing documentation in TechDocs + +You can edit a document in your TechDocs plugin directly from the document book page. Any authorized user in your organization can edit a document regardless of whether or not they are the owner of the document. + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. In the *Documentation* table, click the name of the document that you want to edit. +. In the document, click the *Edit this page* icon to open the document in your remote repository. +. In your remote repository, edit the document as needed. +. Use the repository provider UI and your usual team processes to commit and merge your changes. diff --git a/modules/techdocs/proc-techdocs-find-docs.adoc b/modules/techdocs/proc-techdocs-find-docs.adoc new file mode 100644 index 0000000000..56252f8c73 --- /dev/null +++ b/modules/techdocs/proc-techdocs-find-docs.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-find-docs_{context}"] += Finding documentation in TechDocs + +By default, the TechDocs plugin *Documentation* page shows all of the documentation that your organization has imported into your {product} instance. You can use any combination of the following methods to find the documentation that you want to view: + +* Enter a keyword in the search bar to see all documents that contain the keyword anywhere in the document. +* Filter by *Owner* to see only documents that are owned by a particular user or group in your organization. +* Filter by *Tags* to see only documents that contain a particular tag. +* Filter by *Owned* to see only documents that are owned by you or by a group that you belong +* Filter by *Starred* to see only documents that you have added to favorites. + +By default, the *All* field shows the total number of documents that have been imported into TechDocs. If you search or use filters, the *All* field shows the number of documents that meet the search and filter criteria that you applied. + +.Prerequisites + +* The TechDocs plugin in enabled and configured +* Documentation is imported into TechDocs +* You have the required roles and permissions to add and view documentation to TechDocs + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. On the *Documentation* page, use the search bar, filters, or both to locate the document that you want to view. diff --git a/modules/techdocs/proc-techdocs-view-docs.adoc b/modules/techdocs/proc-techdocs-view-docs.adoc new file mode 100644 index 0000000000..6ec272a148 --- /dev/null +++ b/modules/techdocs/proc-techdocs-view-docs.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-view-docs_{context}"] += Viewing documentation in TechDocs + +In TechDocs, a document might be part of a book that contains other documents that are related to the same topic. + +Clicking the name of a document in the table on the *Documentation* page opens the document in a book page. The name of the book is displayed on book the page. The book page contains the following elements: + +* The contents of the document. +* A search bar that you can use to search for keywords within the document. +* A navigation menu that you can use to navigate to other documents in the book. +* A *Table of contents* that you can use to navigate to other sections of the document. +* A *Next* button that you can use to navigate to the next sequential document in the book. + +You can use the elements on the book page to search, view, and navigate the documentation in the book. + +.Prerequisites + +* The TechDocs plugin in enabled and configured +* Documentation is imported into TechDocs +* You have the required roles and permissions to add and view documentation to TechDocs +* Optional: TechDocs add-ons are installed and configured + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. In the *Documentation* table, click the name of the document that you want to view. +. On the book page, you can do any of the following optional actions: +* Use installed add-ons that extend the functionality of the default TechDocs plugin. +* Use the search bar to find keywords within the document. +* Use any of the following methods to navigate the documentation in the book: +** Use the *Table of contents* to navigate the any section of the document. +** Use the navigation menu to navigate to any document in the book. +** Click *Next* to navigate to the next sequential document in the book. + +.Additional resources +* xref:techdocs-addon[TechDocs add-ons] diff --git a/modules/using-kubernetes-custom-actions/proc-enable-kubernetes-custom-actions-plugin.adoc b/modules/using-kubernetes-custom-actions/proc-enable-kubernetes-custom-actions-plugin.adoc new file mode 100644 index 0000000000..9c8c735569 --- /dev/null +++ b/modules/using-kubernetes-custom-actions/proc-enable-kubernetes-custom-actions-plugin.adoc @@ -0,0 +1,32 @@ +[id='proc-enable-kubernetes-custom-actions-plugin_{context}'] += Enabling Kubernetes custom actions plugin in {product} + +In {product}, the Kubernetes custom actions are provided as a preinstalled plugin, which is disabled by default. You can enable the Kubernetes custom actions plugin by updating the `disabled` key value in your Helm chart. + +.Prerequisites + +* You have installed {product} with the Helm chart. + +.Procedure + +To enable the Kubernetes custom actions plugin, complete the following step: + +* In your Helm chart, add a `package` with the Kubernetes custom action plugin name and update the `disabled` field. For example: ++ +-- +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic + disabled: false +---- + +[NOTE] +==== +The default configuration for a plugin is extracted from the `dynamic-plugins.default.yaml` file, however, you can use a `pluginConfig` entry to override the default configuration. +==== +-- diff --git a/modules/using-kubernetes-custom-actions/proc-using-kubernetes-custom-actions-plugin.adoc b/modules/using-kubernetes-custom-actions/proc-using-kubernetes-custom-actions-plugin.adoc new file mode 100644 index 0000000000..716386d75c --- /dev/null +++ b/modules/using-kubernetes-custom-actions/proc-using-kubernetes-custom-actions-plugin.adoc @@ -0,0 +1,29 @@ +[id='proc-using-kubernetes-custom-actions-plugin_{context}'] += Using Kubernetes custom actions plugin in {product} + +In {product}, the Kubernetes custom actions enable you to run template actions for Kubernetes. + +.Procedure + +* To use a Kubernetes custom action in your custom template, add the following Kubernetes actions to your template: ++ + +[source,yaml,subs="+attributes"] +---- +action: kubernetes:create-namespace +id: create-kubernetes-namespace +name: Create kubernetes namespace +input: + namespace: {my-product-namespace} + clusterRef: bar + token: TOKEN + skipTLSVerify: false + caData: Zm9v + labels: app.io/type=ns; app.io/managed-by=org; + +---- + +[role="_additional-resources"] +.Additional resource + +* link:{customizing-book-url#configuring-templates}[Configuring templates]. \ No newline at end of file diff --git a/modules/using-kubernetes-custom-actions/ref-creating-a-template-using-kubernetes-custom-actions.adoc b/modules/using-kubernetes-custom-actions/ref-creating-a-template-using-kubernetes-custom-actions.adoc new file mode 100644 index 0000000000..fd37a2494d --- /dev/null +++ b/modules/using-kubernetes-custom-actions/ref-creating-a-template-using-kubernetes-custom-actions.adoc @@ -0,0 +1,77 @@ +[id='ref-creating-a-template-using-Kubernetes-custom-actions_{context}'] += Creating a template using Kubernetes custom actions in {product} + +You can create a template by defining a `Template` object as a YAML file. + +The `Template` object describes the template and its metadata. It also contains required input variables and a list of actions that are executed by the scaffolding service. ++ + +[source,yaml,subs="+attributes"] +---- +apiVersion: scaffolder.backstage.io/v1beta3 +kind: Template +metadata: + name: create-kubernetes-namespace + title: Create a kubernetes namespace + description: Create a kubernetes namespace + +spec: + type: service + parameters: + - title: Information + required: [namespace, token] + properties: + namespace: + title: Namespace name + type: string + description: Name of the namespace to be created + clusterRef: + title: Cluster reference + type: string + description: Cluster resource entity reference from the catalog + ui:field: EntityPicker + ui:options: + catalogFilter: + kind: Resource + url: + title: Url + type: string + description: Url of the kubernetes API, will be used if clusterRef is not provided + token: + title: Token + type: string + ui:field: Secret + description: Bearer token to authenticate with + skipTLSVerify: + title: Skip TLS verification + type: boolean + description: Skip TLS certificate verification, not recommended to use in production environment, default to false + caData: + title: CA data + type: string + ui:field: Secret + description: Certificate Authority base64 encoded certificate + labels: + title: Labels + type: string + description: Labels to be applied to the namespace + ui:widget: textarea + ui:options: + rows: 3 + ui:help: 'Hint: Separate multiple labels with a semicolon!' + ui:placeholder: 'kubernetes.io/type=namespace; app.io/managed-by=org' + + steps: + - id: create-kubernetes-namespace + name: Create kubernetes namespace + action: kubernetes:create-namespace + input: + namespace: ${{ parameters.namespace }} + clusterRef: ${{ parameters.clusterRef }} + url: ${{ parameters.url }} + token: ${{ secrets.token }} + skipTLSVerify: ${{ parameters.skipTLSVerify }} + caData: ${{ secrets.caData }} + labels: ${{ parameters.labels }} + +---- \ No newline at end of file diff --git a/modules/using-kubernetes-custom-actions/ref-supported-kubernetes-custom-actions.adoc b/modules/using-kubernetes-custom-actions/ref-supported-kubernetes-custom-actions.adoc new file mode 100644 index 0000000000..2faba2e798 --- /dev/null +++ b/modules/using-kubernetes-custom-actions/ref-supported-kubernetes-custom-actions.adoc @@ -0,0 +1,60 @@ +[id='ref-supported-Kubernetes-custom-actions_{context}'] += Supported Kubernetes custom actions in {product} + +In {product}, you can use custom Kubernetes actions in scaffolder templates. + +.Custom Kubernetes scaffolder actions + +Action: kubernetes:create-namespace:: +Creates a namespace for the Kubernetes cluster in the {product-short}. + +[cols="15%,15%,15%,40%,15%", frame="all", options="header"] +|=== +|Parameter name +|Type +|Requirement +|Description +|Example + +|`namespace` +|`string` +|Required +|Name of the Kubernetes namespace +|`{my-product-namespace}` + +|`clusterRef` +|`string` +|Required only if `url` is not defined. You cannot specify both `url` and `clusterRef`. +|Cluster resource entity reference from the catalog +|`bar` + +|`url` +|`string` +|Required only if `clusterRef` is not defined. You cannot specify both `url` and `clusterRef`. +|API url of the Kubernetes cluster +|`https://api.foo.redhat.com:6443` + +|`token` +|`String` +|Required +|Kubernetes API bearer token used for authentication +| + +|`skipTLSVerify` +|`boolean` +|Optional +|If true, certificate verification is skipped +|false + +|`caData` +|`string` +|Optional +|Base64 encoded certificate data +| + +|`label` +|`string` +|Optional +|Labels applied to the namespace +|app.io/type=ns; app.io/managed-by=org; +|=== \ No newline at end of file diff --git a/modules/using-service-now/proc-enable-servicenow-custom-actions-plugin.adoc b/modules/using-service-now/proc-enable-servicenow-custom-actions-plugin.adoc index 0c4b040ea1..b1cb404d61 100644 --- a/modules/using-service-now/proc-enable-servicenow-custom-actions-plugin.adoc +++ b/modules/using-service-now/proc-enable-servicenow-custom-actions-plugin.adoc @@ -11,7 +11,7 @@ For more information about installing the {product-short}, see xref:{installing- .Procedure -. To activate the custom actions plugin, add a `package` with plugin name and update the `disabled` field in your Helm Chart as follows: +. To activate the custom actions plugin, add a `package` with plugin name and update the `disabled` field in your Helm chart as follows: + -- [source,yaml] @@ -31,7 +31,7 @@ The default configuration for a plugin is extracted from the `dynamic-plugins.de ==== -- -. Set the following variables in the Helm Chart to access the custom actions: +. Set the following variables in the Helm chart to access the custom actions: + -- [source,yaml] diff --git a/modules/using-service-now/ref-supported-servicenow-custom-actions.adoc b/modules/using-service-now/ref-supported-servicenow-custom-actions.adoc index 9bb34ac420..5aaf71fa4d 100644 --- a/modules/using-service-now/ref-supported-servicenow-custom-actions.adoc +++ b/modules/using-service-now/ref-supported-servicenow-custom-actions.adoc @@ -9,8 +9,6 @@ The ServiceNow custom actions enable you to manage records in the {product}. The * `PATCH`: Updates a resource * `DELETE`: Deletes a resource -== ServiceNow custom actions - [GET] servicenow:now:table:retrieveRecord:: + -- @@ -200,7 +198,7 @@ Creates a record in a table in the {product-short}. |`sysparmInputDisplayValue` |`boolean` |Optional -|Set field values using their display value such as `true` or actual value as `false`. The default value is `false`. +|Set field values using their display value such as `true` or actual value as `false`. The default value is `false`. |`sysparmSuppressAutoSysField` |`boolean` @@ -414,4 +412,4 @@ Deletes a record from a table in the {product-short}. |Optional |Set as `true` to access data across domains if authorized. The default value is `false`. |=== --- \ No newline at end of file +-- diff --git a/titles/about/master.adoc b/titles/about/master.adoc index 0d00cfa9d1..329de7a02d 100644 --- a/titles/about/master.adoc +++ b/titles/about/master.adoc @@ -13,4 +13,5 @@ include::assemblies/assembly-about-rhdh.adoc[] * link:{installing-on-osd-on-gcp-book-url}[{installing-on-osd-on-gcp-book-title}] * link:{installing-on-gke-book-url}[{installing-on-gke-book-title}] * link:{installing-on-aks-book-url}[{installing-on-aks-book-title}] -* link:{installing-on-ocp-book-url}[{installing-on-ocp-book-title}] \ No newline at end of file +* link:{installing-on-ocp-book-url}[{installing-on-ocp-book-title}] + diff --git a/titles/adoption-insights/artifacts b/titles/adoption-insights/artifacts new file mode 120000 index 0000000000..f30b6dea60 --- /dev/null +++ b/titles/adoption-insights/artifacts @@ -0,0 +1 @@ +../../artifacts \ No newline at end of file diff --git a/titles/adoption-insights/assemblies b/titles/adoption-insights/assemblies new file mode 120000 index 0000000000..91646274db --- /dev/null +++ b/titles/adoption-insights/assemblies @@ -0,0 +1 @@ +../../assemblies \ No newline at end of file diff --git a/titles/adoption-insights/docinfo.xml b/titles/adoption-insights/docinfo.xml new file mode 100644 index 0000000000..5f7fe2ebac --- /dev/null +++ b/titles/adoption-insights/docinfo.xml @@ -0,0 +1,11 @@ +<title>{title} +{product} +{product-version} +{subtitle} + + {abstract} + + + {company-name} Customer Content Services + + diff --git a/titles/adoption-insights/images b/titles/adoption-insights/images new file mode 120000 index 0000000000..5fa6987088 --- /dev/null +++ b/titles/adoption-insights/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/titles/adoption-insights/master.adoc b/titles/adoption-insights/master.adoc new file mode 100644 index 0000000000..460626f3b5 --- /dev/null +++ b/titles/adoption-insights/master.adoc @@ -0,0 +1,10 @@ +include::artifacts/attributes.adoc[] +:context: title-adoption-insights +:imagesdir: images +:title: Adoption Insights in {product} +:subtitle: Delivers detailed analytics on adoption and engagement within your internal developer portal. +:abstract: As a platform engineer, you can configure Adoption Insights in {product-very-short} to visualize key metrics and trends to get information about the usage of {product-very-short} in your organization. += {title} + +//{product} Adoption Insights (Developer Preview) +include::assemblies/assembly-adoption-insights.adoc[leveloffset=+1] diff --git a/titles/adoption-insights/modules b/titles/adoption-insights/modules new file mode 120000 index 0000000000..36719b9de7 --- /dev/null +++ b/titles/adoption-insights/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file diff --git a/titles/authentication/master.adoc b/titles/authentication/master.adoc index 0db027bd0c..15ec5aa224 100644 --- a/titles/authentication/master.adoc +++ b/titles/authentication/master.adoc @@ -10,4 +10,3 @@ include::artifacts/attributes.adoc[] //{abstract} include::assemblies/assembly-enabling-authentication.adoc[] - diff --git a/titles/authorization/master.adoc b/titles/authorization/master.adoc index 1ac9860e0d..0ebc0a6db2 100644 --- a/titles/authorization/master.adoc +++ b/titles/authorization/master.adoc @@ -3,7 +3,7 @@ include::artifacts/attributes.adoc[] :imagesdir: images :title: Authorization in {product} :subtitle: Configuring authorization by using role based access control (RBAC) in {product} -:abstract: As a {product} platform engineer, you can manage authorizations of other users by using role based access control (RBAC) to meet the specific needs of your organization. +:abstract: {product} administrators can use role-based access control (RBAC) to manage authorizations of other users. //[id="{context}"] //= {title} diff --git a/titles/configuring/master.adoc b/titles/configuring/master.adoc index edce24bba2..e2d611561f 100644 --- a/titles/configuring/master.adoc +++ b/titles/configuring/master.adoc @@ -18,6 +18,12 @@ include::assemblies/assembly-configuring-external-postgresql-databases.adoc[leve include::modules/configuring-deployment/proc-configuring-deployment-by-using-the-operator.adoc[leveloffset=+1] +include::assemblies/assembly-configuring-readonlyrootfilesystem.adoc[leveloffset=+1] + + +include::assemblies/assembly-configuring-high-availability.adoc[leveloffset=+1] + + include::assemblies/assembly-configuring-a-proxy.adoc[leveloffset=+1] @@ -27,5 +33,8 @@ include::modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kube include::modules/dynamic-plugins/con-dynamic-plugins-cache.adoc[ leveloffset=+1] +include::assemblies/assembly-configuring-default-secret-pvc-mounts.adoc[leveloffset=+1] + + include::modules/dynamic-plugins/proc-installing-and-configuring-redis-cache.adoc[leveloffset=+1] diff --git a/titles/customizing/master.adoc b/titles/customizing/master.adoc index 838b8d5b2d..588ba4e2c8 100644 --- a/titles/customizing/master.adoc +++ b/titles/customizing/master.adoc @@ -20,13 +20,14 @@ include::modules/customizing/proc-customizing-the-backend-secret.adoc[leveloffse include::assemblies/assembly-configuring-templates.adoc[leveloffset=+1] -include::modules/customizing-the-learning-paths/proc-customize-rhdh-learning-paths.adoc[leveloffset=+1] +include::assemblies/assembly-customizing-the-learning-paths.adoc[leveloffset=+1] -include::assemblies/assembly-configuring-techdocs.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::modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc[leveloffset=+1] +include::assemblies/assembly-customizing-the-tech-radar-page.adoc[leveloffset=+1] include::assemblies/assembly-customizing-the-appearance.adoc[leveloffset=+1] @@ -36,4 +37,3 @@ include::assemblies/assembly-customizing-the-homepage.adoc[leveloffset=+1] include::assemblies/assembly-customizing-the-quick-access-card.adoc[leveloffset=+1] - diff --git a/titles/install-rhdh-air-gapped/master.adoc b/titles/install-rhdh-air-gapped/master.adoc index 7ef00cf127..19b1cf2d92 100644 --- a/titles/install-rhdh-air-gapped/master.adoc +++ b/titles/install-rhdh-air-gapped/master.adoc @@ -9,6 +9,6 @@ include::artifacts/attributes.adoc[] include::modules/installation/con-airgapped-environment.adoc[leveloffset=+1] -include::modules/installation/proc-install-rhdh-airgapped-environment-ocp-operator.adoc[leveloffset=+1] +include::assemblies/assembly-install-rhdh-airgapped-environment-ocp-operator.adoc[leveloffset=+1] -include::modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc[leveloffset=+1] +include::assemblies/assembly-install-rhdh-airgapped-environment-ocp-helm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/titles/install-rhdh-eks/master.adoc b/titles/install-rhdh-eks/master.adoc index bc93f42610..8662156ee3 100644 --- a/titles/install-rhdh-eks/master.adoc +++ b/titles/install-rhdh-eks/master.adoc @@ -16,7 +16,7 @@ You can install {product} on {eks-brand-name} ({eks-short}) using one of the fol * The {product} Helm chart // Operator method -include::modules/installation/proc-rhdh-deploy-eks-operator.adoc[leveloffset=+1] +include::assemblies/assembly-install-rhdh-eks-operator.adoc[leveloffset=+1] include::modules/installation/proc-deploy-rhdh-instance-eks.adoc[leveloffset=+2] diff --git a/titles/monitoring-and-logging/master.adoc b/titles/monitoring-and-logging/master.adoc index 9954c0ebf4..ffb370749d 100644 --- a/titles/monitoring-and-logging/master.adoc +++ b/titles/monitoring-and-logging/master.adoc @@ -11,7 +11,7 @@ include::artifacts/attributes.adoc[] include::assemblies/assembly-rhdh-observability.adoc[leveloffset=+1] //AWS -include::modules/observe/proc-rhdh-monitoring-logging-aws.adoc[leveloffset=+1] +include::assemblies/assembly-monitoring-and-logging-with-aws.adoc[leveloffset=+1] //AKS include::assemblies/assembly-monitoring-and-logging-aks.adoc[leveloffset=+1] diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index 8994501326..4d108c92e7 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -14,5 +14,11 @@ include::assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc[levelo //third-party plugins include::assemblies/dynamic-plugins/assembly-third-party-plugins.adoc[leveloffset=+1] -// Viewing installed plugins -include::modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] +//Install RHDH container image plugins +include::modules/dynamic-plugins/proc-enable-plugins-rhdh-container-image.adoc[leveloffset=+1] + +// Viewing installed plugins - moved to Extensions +//include::modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] + +// Extensions (marketplace) plugins +include::assemblies/dynamic-plugins/assembly-extensions-plugins.adoc[leveloffset=+1] diff --git a/titles/rel-notes-rhdh/title-rhdh-release-notes.adoc b/titles/rel-notes-rhdh/title-rhdh-release-notes.adoc index 5cdd60e777..7b79c1e485 100644 --- a/titles/rel-notes-rhdh/title-rhdh-release-notes.adoc +++ b/titles/rel-notes-rhdh/title-rhdh-release-notes.adoc @@ -20,11 +20,12 @@ include::modules/release-notes/ref-release-notes-deprecated-functionalities.adoc include::modules/release-notes/ref-release-notes-technology-preview.adoc[leveloffset=+1] +include::modules/release-notes/ref-release-notes-developer-preview.adoc[leveloffset=+1] include::modules/release-notes/ref-release-notes-fixed-issues.adoc[leveloffset=+1] -include::assemblies/assembly-release-notes-fixed-security-issues.adoc[leveloffset=+1] +include::modules/release-notes/ref-release-notes-fixed-security-issues.adoc[leveloffset=+1] include::modules/release-notes/ref-release-notes-known-issues.adoc[leveloffset=+1] diff --git a/titles/techdocs/artifacts b/titles/techdocs/artifacts new file mode 120000 index 0000000000..f30b6dea60 --- /dev/null +++ b/titles/techdocs/artifacts @@ -0,0 +1 @@ +../../artifacts \ No newline at end of file diff --git a/titles/techdocs/assemblies b/titles/techdocs/assemblies new file mode 120000 index 0000000000..91646274db --- /dev/null +++ b/titles/techdocs/assemblies @@ -0,0 +1 @@ +../../assemblies \ No newline at end of file diff --git a/titles/techdocs/docinfo.xml b/titles/techdocs/docinfo.xml new file mode 100644 index 0000000000..ce010bd06e --- /dev/null +++ b/titles/techdocs/docinfo.xml @@ -0,0 +1,12 @@ +TechDocs for {product} +{product} +{product-version} +Use the TechDocs plugin to read and manage your team's technical documentation in one place. Further enhance and customize your TechDocs experience with add-ons. + + Your organization can use the built-in TechDocs plugin for {product} to create, find, and use technical documentation in a central location and in a standardized way. Documentation files are stored alongside your code and rendered in the Docs tab. Use supported TechDocs add-ons, or create your own, to further enhance your documentation experience. + + + {company-name} Customer Content Services + + diff --git a/titles/techdocs/images b/titles/techdocs/images new file mode 120000 index 0000000000..5fa6987088 --- /dev/null +++ b/titles/techdocs/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/titles/techdocs/master.adoc b/titles/techdocs/master.adoc new file mode 100644 index 0000000000..0e4c731330 --- /dev/null +++ b/titles/techdocs/master.adoc @@ -0,0 +1,25 @@ +include::artifacts/attributes.adoc[] + +:context: customizing-display +[id="{context}"] += TechDocs for {product} + +// about techdocs +include::modules/techdocs/con-techdocs-about.adoc[leveloffset=+1] + +// techdocs configuration +include::assemblies/assembly-configuring-techdocs.adoc[leveloffset=+1] + +// using techdocs +include::assemblies/assembly-using-techdocs.adoc[leveloffset=+1] + +// techdocs add-ons +include::assemblies/assembly-techdocs-addons.adoc[leveloffset=+1] + +include::assemblies/assembly-techdocs-addons-installing.adoc[leveloffset=+2] + +include::assemblies/assembly-techdocs-addons-removing.adoc[leveloffset=+2] + +include::assemblies/assembly-techdocs-addons-using.adoc[leveloffset=+2] + +include::modules/techdocs/proc-techdocs-addon-create.adoc[leveloffset=+1] diff --git a/titles/techdocs/modules b/titles/techdocs/modules new file mode 120000 index 0000000000..8b0e854007 --- /dev/null +++ b/titles/techdocs/modules @@ -0,0 +1 @@ +../../modules \ No newline at end of file diff --git a/titles/telemetry/master.adoc b/titles/telemetry/master.adoc index 52a59af949..2608f4895a 100644 --- a/titles/telemetry/master.adoc +++ b/titles/telemetry/master.adoc @@ -1,11 +1,20 @@ include::artifacts/attributes.adoc[] :context: title-telemetry :imagesdir: images -:title: Telemetry data collection -:subtitle: Collecting and analyzing telemetry data to enhance {product} experience -:abstract: As a {product} administrator, you can collect and analyze telemetry data to enhance your {product} experience. +:title: Telemetry data collection and analysis +:subtitle: Collecting and analyzing web analytics and system observability data to enhance {product} experience +:abstract: As a {product} administrator, you can collect and analyze two distinct types of telemetry data: web analytics using Segment and system observability using OpenTelemetry, to enhance the {product} experience. = {title} -//Telemetry data collection -include::assemblies/assembly-rhdh-telemetry.adoc[leveloffset=+1] +//Telemetry data collection and analysis +include::modules/analytics/con-telemetry-data-collection-and-analysis.adoc[leveloffset=+1] + +// disabling telemetry +include::assemblies/assembly-disabling-telemetry-data-collection.adoc[leveloffset=+1] + +// enabling telemetry +include::assemblies/assembly-enabling-telemetry-data-collection.adoc[leveloffset=+1] + +// customizing segment source +include::assemblies/assembly-customizing-segment-source.adoc[leveloffset=+1] \ No newline at end of file