RHDHBUGS-1109 - Added OLM framework prerequisites for AKS and reused common content (#1382) (#1390)

* RHDHBUGS-1109 - Added OLM framework prerequisites for AKS



* Refactoring to reuse common steps



* Update modules/installation/proc-provisioning-your-pull-secret-to-your-rhdh-instance-namespace.adoc



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



---------

Signed-off-by: Fabrice Flore-Thébault <[email protected]>
Co-authored-by: Armel Soro <[email protected]>

Author: themr0c

artifacts/attributes.adoc

@@ -93,6 +93,7 @@
 
 // First mention of OpenShift CLI or `oc` in a module
 :openshift-cli: pass:quotes[OpenShift CLI (`oc`)]
+:platform-generic: OpenShift
 
 // Links and their title (in alphabetical order)
 :about-book-link: {product-docs-link}/html-single/about_red_hat_developer_hub/index

assemblies/assembly-install-rhdh-eks-operator.adoc

@@ -0,0 +1,25 @@
+:_mod-docs-content-type: ASSEMBLY
+// To use this module define the attributes: :platform-long: :platform: :platform-id:
+[id="assembly-installing-rhdh-on-{platform-id}-by-using-the-operator"]
+= Installing {product-short} on {platform-long} by using the Operator
+
+To benefit from over-the-air updates and catalogs provided by Operator-based applications distributed with the Operator Lifecycle Manager (OLM) framework, consider installing {product} by using the {product} Operator distributed in the {company-name} Ecosystem.
+
+On {platform}, the most notable differences over an OpenShift-based installation are:
+
+* The OLM framework and the {company-name} Ecosystem are not built-in.
+* The {company-name} Ecosystem pull-secret is not managed globally.
+* To expose the application, Ingresses replace OpenShift Routes.
+
+For clarity, the content is broken down in sections highlighting these platform-specific additional steps.
+
+include::modules/installation/proc-installing-the-operator-on-{platform-id}-by-using-olm.adoc[leveloffset=+1]
+
+include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[leveloffset=+1]
+
+include::modules/installation/proc-provisioning-your-pull-secret-to-your-rhdh-instance-namespace.adoc[leveloffset=+1]
+
+include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1]
+
+include::modules/installation/proc-exposing-your-operator-based-rhdh-instance-on-{platform-id}.adoc[leveloffset=+1]
+

assemblies/assembly-installing-rhdh-on-platform-by-using-the-operator.adoc

@@ -1,19 +1,20 @@
 [id="provisioning-your-custom-configuration"]
 = Provisioning your custom {product} configuration
 
-To configure {product}, provision your custom {product} config maps and secrets to {ocp-brand-name} before running {product}.
+To configure {product}, provision your custom {product} config maps and secrets to {platform-long} before running {product}.
 
 [TIP]
 ====
-You can skip this step to run {product-short} with the default config map and secret.
+On {ocp-brand-name}, you can skip this step to run {product-short} with the default config map and secret.
 Your changes on this configuration might get reverted on {product-short} restart.
 ====
 
 .Prerequisites
-* By using the {ocp-docs-link}/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.
+* By using the {platform-cli-link}, you have access, with developer permissions, to the {platform-generic} 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 `_<my_product_secrets>_.txt` file to provision your secrets as environment variables values in {a-platform-generic} secret,
+rather than in clear text in your configuration files.
 It contains one secret per line in `KEY=value` form.
 +
 * {authentication-book-link}[Enter your authentication secrets].
@@ -23,7 +24,7 @@ This is the main {product-short} configuration file.
 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} Operator on {platform}, 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}.
@@ -55,49 +56,31 @@ backend:
 *** {authentication-book-link}[{authentication-book-title}].
 *** {authorization-book-link}[{authorization-book-title}].
 *** {customizing-book-link}[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.
+. Provision your custom configuration files to your {platform} cluster.
 
-.. Create the _<{my-product-namespace}>_ project aimed at containing your {product-short} instance.
+.. Create the _<{my-product-namespace}>_ {namespace} aimed at containing your {product-short} instance.
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----
 $ oc create namespace {my-product-namespace}
 ----
-+
-Alternatively, {ocp-docs-link}/html-single/building_applications/index#creating-a-project-using-the-web-console_projects[create the project by using the web console].
 
 .. Provision your `{my-app-config-file}` file to the `{my-app-config-config-map}` config map in the _<{my-product-namespace}>_ project.
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----
 $ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file} --namespace={my-product-namespace}
 ----
-+
-Alternatively, {ocp-docs-link}/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.
 +
 [source,terminal,subs="+attributes,+quotes"]
 ----
 $ oc create secret generic `_<my_product_secrets>_` --from-file=`_<my_product_secrets>_.txt` --namespace={my-product-namespace}
 ----
-+
-Alternatively,
-{ocp-docs-link}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console].
-
-[NOTE]
-====
-`_<my_product_secrets>_` 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 use an external PostgreSQL database, {configuring-book-link}configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
 * To enable dynamic plugins, {installing-and-viewing-plugins-book-link}[provision your dynamic plugins config map].
-
 * To configure authorization by using external files, {authorization-book-link}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].

modules/configuring/proc-provisioning-your-custom-configuration.adoc

@@ -1,3 +1,5 @@
+:_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
 
@@ -7,16 +9,16 @@ To use the {product-short} Operator to run {product} with your custom configurat
 * Injects environment variables provisioned in your custom secrets.
 
 .Prerequisites
-* By using the {ocp-docs-link}/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.
-* {installing-on-ocp-book-link}[Your {ocp-short} administrator has installed the {product} Operator in {ocp-short}].
-* xref:provisioning-your-custom-configuration[You have provisioned your custom config maps and secrets in your `_<{my-product-namespace}>_` project].
+* By using the {platform-cli-link}, you have access, with developer permissions, to the {platform} cluster aimed at containing your {product-short} instance.
+* Your administrator has installed the {product} Operator in the cluster.
+* 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 +41,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 +72,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 +94,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 +107,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].
+Optionally, enter your additional environment variables that are not secrets, such as {configuring-book-link}#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 +126,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 +140,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,7 +152,7 @@ spec:
          - name: _<my_product_secrets>_
          - name: {my-product-database-secrets}
 ----
-====
++
 
 [NOTE]
 ====
@@ -167,7 +162,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 +178,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:
@@ -199,9 +197,9 @@ spec:
 ----
 
 `spec.deployment`:::
-Optionally, xref:configuring-the-deployment[enter your deployment configuration].
+Optionally, {configuring-book-link}#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"]
 ----