Merge branch 'main' into RHIDP-5351-oc-mirror-helm-procedure-update

Author: Fortune-Ndlovu

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

@@ -70,6 +70,159 @@ 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 <your-clusterrole-file>.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: <BACKSTAGE_ENTITY_NAME>
+----
+
+.. (Optional) For identifying resources by namespace:
++
+[source,yaml]
+----
+annotations:
+  ...
+  backstage.io/kubernetes-namespace: <RESOURCE_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: <BACKSTAGE_ENTITY_NAME>
+----
+
+.. GitOps application mapping: Add this label to map Argo CD Rollouts to a specific GitOps application
++
+[source,yaml]
+----
+labels:
+  ...
+  app.kubernetes.io/instance: <GITOPS_APPLICATION_NAME>
+----
+
++
+[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
 

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]

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 <<EOF | oc -n <your-namespace> 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 <<EOF | oc -n <your-namespace> 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="+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:

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:

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
+----
+====

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. 

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.
 ====
 

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.

modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc

@@ -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"

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