Merge branch 'main' into RHIDP-7472

Author: Gerry-Forde

.gitignore

@@ -2,6 +2,7 @@
 titles/*/build
 index.html
 titles-generated/
+.vale-styles/AsciiDocDITA
 .vale-styles/RedHat
 .vscode
 .cache/

.vale.ini

@@ -10,9 +10,14 @@ StylesPath = ".vale-styles"
 MinAlertLevel = suggestion
 
 # Styles to download:
-Packages = RedHat
+Packages = RedHat,https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip
 
 # Display alerts on AsciiDoc files:
 [*.adoc]
 # Apply these styles:
-BasedOnStyles = RedHat,DeveloperHub
+BasedOnStyles = RedHat,DeveloperHub,AsciiDocDITA
+
+# Disable certain rules:
+AsciiDocDITA.AttributeReference = NO
+AsciiDocDITA.ShortDescription = NO
+AsciiDocDITA.CrossReference = NO

artifacts/snip-conscious-language.adoc

@@ -30,10 +30,10 @@ To start using Orchestrator in {product-very-short}, you must:
 include::modules/orchestrator/con-supported-architecture-for-orchestrator.adoc[leveloffset=+1]
 
 // provisioning plugin dependencies
-include::modules/orchestrator/con-understanding-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
+include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1]
 
 // installing the components for the orchestrator plugin
-include::modules/orchestrator/con-install-components-orchestrator-plugin.adoc[leveloffset=+1]
+include::modules/orchestrator/con-orchestrator-plugin-components.adoc[leveloffset=+1]
 
 // Orchestrator Infrastructure for {product} Helm chart
 include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2]

assemblies/assembly-orchestrator-rhdh.adoc

@@ -4,8 +4,8 @@
 
 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.
+.Prerequisites
+* You must have sufficient permissions as a platform engineer.
 
 .Procedure
 
@@ -206,4 +206,4 @@ To configure a floating action button as a dynamic plugin, complete any of the f
                 icon: bulkImportIcon
                 text: Bulk import
 ----
-<1> (Required) The import name with an associated component to the mount point.
+<1> (Required) The import name with an associated component to the mount point.

modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc

@@ -1,19 +1,17 @@
+:_mod-docs-content-type: PROCEDURE
 [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`. 
+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:
+* In your Helm chart configuration file, set `replicas` to a value greater than `1`.
++
+For example, to configure two replicas (one backup instance):
 +
-====
 [source,yaml,subs="+attributes,+quotes"]
 ----
 upstream:
   backstage:
-    replicas: _<replicas_value>_ <1>
+    replicas: 2
 ----
-====
-<1> Set the number of replicas based on the number of backup instances that you want to configure.

modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc

@@ -1,27 +1,25 @@
+:_mod-docs-content-type: PROCEDURE
 [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`.
+= 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 (CR).
+In the `{product-custom-resource-type}` CR, 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:
+* In your `{product-custom-resource-type}` custom resource (CR), set `replicas` to a value greater than `1`.
++
+For example, to configure two replicas (one backup instance):
 +
-====
 [source,yaml,subs="+attributes,+quotes"]
 ----
-apiVersion: rhdh.redhat.com/v1alpha3 
-kind: Backstage 
-metadata: 
-  name: _<your_yaml_file>_ 
+apiVersion: rhdh.redhat.com/v1alpha3
+kind: Backstage
+metadata:
+  name: _<your_yaml_file>_
 spec:
   deployment:
     patch:
-      spec: 
-        ... 
-        replicas: _<replicas_value>_ <1>
-        ...
+      spec:
+        replicas: 2
 ----
-====
-<1> Set the number of replicas based on the number of backup instances that you want to configure.

modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc

@@ -1,9 +1,11 @@
+:_mod-docs-content-type: PROCEDURE
 [id="mounting-additional-files-in-your-custom-configuration-using-rhdh-operator"]
-= Mounting additional files in your custom configuration using the {product} Operator
+= Mounting additional files in your custom configuration by using the {product} Operator
 
 You can use the {product-short} Operator to mount extra files, such as a ConfigMap or Secret, to the container in a preferred location.
 
-The `mountPath` field specifies the location where a ConfigMap or Secret is mounted. The behavior of the mount, whether it includes or excludes a `subPath`, depends on the specification of the `key` or `mountPath` fields.
+The `mountPath` field specifies the location where a ConfigMap or Secret is mounted.
+The behavior of the mount, whether it includes or excludes a `subPath`, depends on the specification of the `key` or `mountPath` fields.
 
 * If `key` and `mountPath` are not specified: Each key or value is mounted as a `filename` or content with a `subPath`.
 * If `key` is specified with or without `mountPath`: The specified key or value is mounted with a `subPath`.
@@ -15,17 +17,15 @@ The `mountPath` field specifies the location where a ConfigMap or Secret is moun
 * 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.
 ====
 
-
 .Prerequisites
 * You have developer permissions to access the {ocp-short} cluster containing your {product-short} instance using the {openshift-cli}.
 * link:{installing-on-ocp-book-url}[Your {ocp-short} administrator has installed the {product} Operator in {ocp-short}].
 
 .Procedure
-
 . In {ocp-short}, create your ConfigMap or Secret with the following YAML codes:
 +
-.Minimal `{my-extra-file-configmap}` ConfigMap example
-====
+Minimal `{my-extra-file-configmap}` ConfigMap example:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: v1
@@ -38,10 +38,9 @@ data:
   file 12.txt: |
     My file12 content
 ----
-====
 +
-.Minimal {product} Secret example
-====
+Minimal {product} Secret example:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: v1
@@ -52,12 +51,12 @@ StringData:
   secret11.txt: |
     secret-content
 ----
-====
++
 For more information, see xref:provisioning-your-custom-configuration[Provisioning and using your custom {product} configuration].
 
-. Set the value of the `configMaps name` to the name of the ConfigMap or `secrets name` to the name of the Secret in your `{product-custom-resource-type}` CR. For example:
+. Set the value of the `configMaps name` to the name of the ConfigMap or `secrets name` to the name of the Secret in your `{product-custom-resource-type}` CR.
+For example:
 +
-====
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -74,8 +73,7 @@ spec:
           mountPath: /my/my-rhdh-secret/path
 
 ----
-====
-
++
 [NOTE]
 ====
 `_<my_product_secrets>_` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}.

modules/configuring/proc-mounting-additional-files-in-your-custom-configuration-using-rhdh-operator.adoc

@@ -1,3 +1,4 @@
+:_mod-docs-content-type: PROCEDURE
 [id="using-the-operator-to-run-rhdh-with-your-custom-configuration"]
 = Using the {product} Operator to run {product-short} with your custom configuration
 
@@ -12,11 +13,10 @@ To use the {product-short} Operator to run {product} with your custom configurat
 * xref:provisioning-your-custom-configuration[You have provisioned your custom config maps and secrets in your `_<{my-product-namespace}>_` project].
 
 .Procedure
-
 . Author your {product-custom-resource-type} CR in a `{my-product-cr-name}.yaml` file to use your custom config maps and secrets.
 +
-.Minimal `{my-product-cr-name}.yaml` custom resource example
-====
+Minimal `{my-product-cr-name}.yaml` custom resource example:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: rhdh.redhat.com/v1alpha3
@@ -39,10 +39,9 @@ spec:
   database:
     enableLocalDb: true
 ----
-====
 +
-.`{my-product-cr-name}.yaml` custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets.
-====
+`{my-product-cr-name}.yaml` custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: rhdh.redhat.com/v1alpha3
@@ -71,21 +70,19 @@ spec:
   database:
     enableLocalDb: false
 ----
-====
 
 Mandatory fields::
 
 No fields are mandatory.
-You can create an empty {product-custom-resource-type} CR
-and run {product-short} with the default configuration.
+You can create an empty {product-custom-resource-type} CR and run {product-short} with the default configuration.
 
 Optional fields::
 
 `spec.application.appConfig.configMaps`:::
 Enter your config map name list.
 +
-.Mount files in the `{my-app-config-config-map}` config map.
-====
+Mount files in the `{my-app-config-config-map}` config map:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -95,10 +92,9 @@ spec:
       configMaps:
          - name: {my-app-config-config-map}
 ----
-====
 +
-.Mount files in the `{my-app-config-config-map}` and `rbac-policies` config maps.
-====
+Mount files in the `{my-app-config-config-map}` and `rbac-policies` config maps:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -109,13 +105,12 @@ spec:
          - name: {my-app-config-config-map}
          - name: rbac-policies
 ----
-====
 
 `spec.application.extraEnvs.envs`:::
 Optionally, enter your additional environment variables that are not secrets, such as xref:proc-configuring-proxy-in-operator-deployment_running-behind-a-proxy[your proxy environment variables].
 +
-.Inject your `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables.
-====
+Inject your `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -129,13 +124,12 @@ spec:
         - name: NO_PROXY
           value: 'localhost,example.org'
 ----
-====
 
 `spec.application.extraEnvs.secrets`:::
 Enter your environment variables secret name list.
 +
-.Inject the environment variables in your {product} secret
-====
+Inject the environment variables in your {product} secret:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -144,10 +138,9 @@ spec:
       secrets:
          - name: _<my_product_secrets>_
 ----
-====
 +
-.Inject the environment variables in the {product} and `{my-product-database-secrets}` secrets
-====
+Inject the environment variables in the {product} and `{my-product-database-secrets}` secrets:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -157,8 +150,7 @@ spec:
          - name: _<my_product_secrets>_
          - name: {my-product-database-secrets}
 ----
-====
-
++
 [NOTE]
 ====
 `_<my_product_secrets>_` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}.
@@ -167,7 +159,8 @@ spec:
 `spec.application.extraFiles.secrets`:::
 Enter your certificates files secret name and files list.
 +
-.Mount the `postgres-crt.pem`, `postgres-ca.pem`, and `postgres-key.key` files contained in the `{my-product-database-certificates-secrets}` secret
+Mount the `postgres-crt.pem`, `postgres-ca.pem`, and `postgres-key.key` files contained in the `{my-product-database-certificates-secrets}` secret:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -182,15 +175,17 @@ spec:
 `spec.database.enableLocalDb`:::
 Enable or disable the local PostgreSQL database.
 +
-.Disable the local PostgreSQL database generation to use an external postgreSQL database
+Disable the local PostgreSQL database generation to use an external postgreSQL database:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
   database:
     enableLocalDb: false
 ----
 +
-.On a development environment, use the local PostgreSQL database
+On a development environment, use the local PostgreSQL database:
++
 [source,yaml,subs="+attributes,+quotes"]
 ----
 spec:
@@ -200,8 +195,8 @@ spec:
 
 `spec.deployment`:::
 Optionally, xref:configuring-the-deployment[enter your deployment configuration].
-
-. Apply your {product-custom-resource-type} CR to start or update your {product-short} instance.
++
+Apply your {product-custom-resource-type} CR to start or update your {product-short} instance:
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----

modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc

@@ -12,18 +12,17 @@ You can customize the Adoption Insights plugin to suit your needs by disabling o
 
 * To customize `maxBufferSize`, `flushInterval`, `debug`, and `licensedUsers` in the Adoption Insights plugin, in your {product} `app-config.yaml` file, update the relevant settings as shown in the following code:
 +
-.`app-config.yaml` fragment
 [source,terminal]
 ----
 app:
   analytics:
-    adoptionInsights: 
+    adoptionInsights:
       maxBufferSize: _<maximum_buffer_size>_ <1>
       flushInterval: _<flush_interval>_ <2>
       debug: _<debug_value>_ <3>
       licensedUsers: _<licensed_users>_ <4>
 ----
-<1> (Optional) Specifies the maximum buffer size for event batching. The default value is `20`. 
+<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 {product-very-short} instance. The default value is `100`.