BXMSDOC-8504-main: Add ConfigMap sections

assemblies/assembly-openshift-operator.adoc

@@ -104,6 +104,8 @@ include::{enterprise-dir}/openshift/operator-environment-deploy-assy.adoc[levelo
 include::{enterprise-dir}/openshift/operator-modify-proc.adoc[leveloffset=+2]
 include::{enterprise-dir}/openshift/jboss-postconfigure-proc.adoc[leveloffset=+2]
 include::{enterprise-dir}/openshift/jvm-settings-ref.adoc[leveloffset=+2]
+include::{enterprise-dir}/openshift/configmaps-con.adoc[leveloffset=+2]
+include::{enterprise-dir}/openshift/using-configmaps-proc.adoc[leveloffset=+3]
 include::{enterprise-dir}/openshift/customimage-con.adoc[leveloffset=+2]
 include::{enterprise-dir}/openshift/customimage-rpm-proc.adoc[leveloffset=+3]
 include::{enterprise-dir}/openshift/customimage-jar-proc.adoc[leveloffset=+3]

doc-content/enterprise-only/openshift/architecture-authoring-con.adoc

@@ -87,7 +87,7 @@ The controller strategy is not suitable for clustered deployment. In an OpenShif
 
 Each {KIE_SERVER} deployment (which can be scaled) creates a ConfigMap that reflects its current state. The {CENTRAL} discovers all {KIE_SERVERS} by reading their ConfigMaps.
 
-When the user requests a change in the {KIE_SERVER} configuration (for example, deploys or undeploys a service), {CENTRAL} initiates a connection to {KIE_SERVER} and sends a REST API request. {KIE_SERVER} changes the ConfigMap to reflect the new configuration state and then triggers its own redeployment, so that all instances are redeployed and reflect the new configuration.
+When the user requests a change in the {KIE_SERVER} configuration (for example, deploys or undeploys a service), {CENTRAL} initiates a connection to {KIE_SERVER} and sends a REST API request. {KIE_SERVER} changes the ConfigMap to reflect the new configuration state and then triggers its redeployment, so that all instances are redeployed and reflect the new configuration. For more information about ConfigMaps, see {URL_DEPLOYING_ON_OPENSHIFT}#configmaps-con[_KIE configuration and ConfigMaps_].
 
 You can deploy several independent {KIE_SERVERS} in your OpenShift environment. Each of the {KIE_SERVERS} has a separate ConfigMap with the necessary configuration. You can scale each of the {KIE_SERVERS} separately.
 

doc-content/enterprise-only/openshift/configmaps-con.adoc

@@ -0,0 +1,96 @@
+[id='configmaps-con_{context}']
+= KIE configuration and ConfigMaps
+
+When installing the {PRODUCT} operator, the operator creates ConfigMaps, a YAML file, prefixed as `kieconfig-$VERSION`, for the current namespace. A ConfigMap is a YAML file containing the configuration for functionality such as `DeploymentConfigs`, secrets, routes, and services for the {PRODUCT} components for that namespace.
+
+.Example ConfigMap:
+[source]
+----
+# Please edit the object below. Lines beginning with a '#' will be ignored,
+# and an empty file will abort the edit. If an error occurs while saving this file will be
+# reopened with the relevant failures.
+#
+apiVersion: v1
+data:
+  mysql.yaml: |
+    ## KIE Databases BEGIN
+    databases:
+      ## RANGE BEGINS
+      #[[ range $index, $Map := .Databases ]]
+…
+----
+
+The operator uses ConfigMaps to configure and deploy the components. This includes all supported {PRODUCT} components such as {KIE_SERVER}, Smart Router, {CENTRAL} and service-related configuration such as for persistent volumes, build configuration, and routes. When ConfigMaps are edited manually, the operator uses the new values to create the deployments when the environment is reconciled.
+
+The {PRODUCT} operator can use the current version and the previous version of {PRODUCT} components concurrently, with ConfigMaps for each version, for example, 7.13.0 and 7.12.1.
+
+kieconfigs-7.12.1::
+This contains the `common.yaml` configuration file. For more information, see  https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/common.yaml[`common.yaml`] on GitHub. You can configure the following components using this configuration file:
++
+* {KIE_SERVER}, the server object, is identified by the `## KIE Servers BEGIN` placeholder.
+* {CENTRAL} and {CENTRAL} Monitoring, the console object, is defined on the first line of the `common.yaml`.
+* Smartrouter, the smartrouter object, is identified by the `## KIE smartrouter BEGIN` placeholder.
+
+[NOTE]
+====
+`kieconfigs-7.12.1` also holds the routes and services relating to these three components.
+====
+
+kieconfigs-7.12.1-dashbuilder::
+This contains the configuration YAML file for the Dashbuilder component.
++
+For more information, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dashbuilder/rhpam-standalone-dashbuilder.yaml[`rhpam-standalone-dashbuilder.yaml`] on GitHub.
+
+kieconfigs-7.12.1-dbs::
+This contains the base `DeploymentConfig` for the MySQL and PostgreSQL databases.
++
+For more information about the MySQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/mysql.yaml[`mysql.yaml`] on GitHub.
++
+For more information about the PostgreSQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/postgresql.yaml[`postgresql.yaml`] on GitHub.
+
+kieconfigs-7.12.1-dbs-pim::
+This contains the snippet configuration for the Process Instance Migration (PIM) supported databases; external, MySQL, and PostgreSQL.
++
+For more information about the PIM external configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/pim/external.yaml[`external.yaml`] on GitHub.
++
+For more information about the PIM MySQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/pim/mysql.yaml[`mysql.yaml`] on GitHub.
++
+For more information about the PIM PostgreSQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/pim/postgresql.yaml[`postgresql.yaml`] on GitHub.
++
+[NOTE]
+====
+These YAML files only hold the specific configuration for the PIM database configured using `application.properties` in this configMap.
+====
+
+kieconfigs-7.12.1-dbs-servers::
+This contains the snippet configuration for the supported database configurations; external, h2, MySQL, and PostgreSQL.
++
+For more information about the external configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/external.yaml[`external.yaml`] on GitHub.
++
+For more information about the h2 configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/h2.yaml[`h2.yaml`] on GitHub. Note that the h2 configuration is not supported on production environments.
++
+For more information about the MySQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/mysql.yaml[`mysql.yaml`] on GitHub.
++
+For more information about the PostgreSQL configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/dbs/servers/postgresql.yaml[`postgresql.yaml`] on GitHub.
+
+kieconfigs-7.12.1-envs::
+This contains the specific configurations for each {PRODUCT} environment such as the authoring or trial environments. This ConfigMap contains the following YAML files:
++
+* rhdm-authoring-ha.yaml
+* rhdm-authoring.yaml
+* rhdm-production-immutable.yaml
+* rhdm-trial.yaml
+* rhpam-authoring-ha.yaml
+* rhpam-authoring.yaml
+* rhpam-production-immutable.yaml
+* rhpam-production.yaml
+* rhpam-standalone-dashbuilder.yaml
+* rhpam-trial.yaml
++
+For more information about specific configurations for each {PRODUCT} environment, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/envs/[ConfigMaps for {PRODUCT} environments] on GitHub.
+
+kieconfigs-7.12.1-jms::
+This contains the ActiveMQ configuration for {KIE_SERVER} when the JMS Executor is enabled. For more information about the JMS Executor configuration, see https://github.com/kiegroup/kie-cloud-operator/blob/7.12.1-1/rhpam-config/7.12.1/jms/activemq-jms-config.yaml[`activemq-jms-config`] on GitHub.
+
+kieconfigs-7.12.1-pim::
+This contains the process instance migration (PIM) DeploymentConfig and related PIM configuration. If you are using MySQL or any other database with PIM you must use the `kieconfigs-7.12.1-dbs-pim` configMap and edit the `mysql.yaml` file.

doc-content/enterprise-only/openshift/githooks-prepare-proc.adoc

@@ -16,7 +16,7 @@ Skip this procedure if you do not want to configure Git hooks.
 A `pre-commit` script is not supported in {CENTRAL}. Use a `post-commit` script.
 ====
 +
-. Create a configuration map (ConfigMap) or persistent volume with the files.
+. Create a configuration map (ConfigMap) or persistent volume with the files. For more information about ConfigMaps, see {URL_DEPLOYING_ON_OPENSHIFT}#configmaps-con[_KIE configuration and ConfigMaps_].
 ** If the Git hooks consist of one or several fixed script files, use the `oc` command to create a configuration map. For example:
 +
 [subs="attributes,verbatim,macros"]

doc-content/enterprise-only/openshift/using-configmaps-proc.adoc

@@ -0,0 +1,155 @@
+[id='using-configmaps-proc_{context}']
+= Using ConfigMaps
+
+You can use ConfigMaps to customize the {PRODUCT} Operator and apply the related configuration. To make changes to ConfigMaps, you can use the `oc` command tool or the {OPENSHIFT} console.
+
+.Prerequisites
+
+* Operator is installed in your current namespace.
+* A KieApp is available.
+* `kieconfig-$VERSION-*` are available.
++
+To check if `kieconfig-$VERSION-*` are available, run the following command:
++
+----
+$ oc get cm | grep kieconfigs
+----
++
+.Example output of `oc get cm | grep kieconfigs`:
++
+[source]
+----
+kieconfigs-7.13.0               1       64m
+kieconfigs-7.13.0-dashbuilder   1       64m
+kieconfigs-7.13.0-dbs           2       64m
+kieconfigs-7.13.0-dbs-pim       3       64m
+kieconfigs-7.13.0-dbs-servers   4       64m
+kieconfigs-7.13.0-envs         10       64m
+kieconfigs-7.13.0-jms           1       64m
+kieconfigs-7.13.0-pim           1       64m
+kieconfigs-7.12.1               1       64m
+kieconfigs-7.12.1-dashbuilder   1       64m
+kieconfigs-7.12.1-dbs           2       64m
+kieconfigs-7.12.1-dbs-pim       3       64m
+kieconfigs-7.12.1-dbs-servers   4       64m
+kieconfigs-7.12.1-envs         10       64m
+kieconfigs-7.12.1-jms           1       64m
+kieconfigs-7.12.1-pim           1       64m
+----
+
+.Procedure
+
+. Create an `rhpam-authoring environment` with one replica for {CENTRAL} and {KIE_SERVER}.
++
+.Example `rhpam-authoring`:
+[source, yaml]
+----
+apiVersion: app.kiegroup.org/v2
+kind: KieApp
+metadata:
+  name: rhpam-authoring
+  annotations:
+    consoleName: rhpam-authoring
+    consoleTitle: PAM Authoring
+    consoleDesc: Deploys a PAM Authoring environment
+spec:
+  environment: rhpam-authoring
+objects:
+  servers:
+    - replicas: 1
+  console:
+    replicas: 1
+----
+. Complete one of the following steps:
+** To open a specific ConfigMap with the `oc` tool, run the following command:
++
+[source]
+----
+$ oc edit cm/<CONFIGMAP_NAME>
+----
++
+[NOTE]
+====
+The `oc` tool is similar to the `vim` text editing tool.
+====
+** To open a specific ConfigMap using the {OPENSHIFT} console, navigate to `kieconfigs-7.12.1` on the *ConfigMaps* page and edit it by opening it's YAML version.
+
+. To modify the YAML file, add `annotations` fields that contain your changes, for example:
++
+Add the following to `Console.deploymentConfigs.metadata`:
++
+[source, yaml]
+----
+           annotations:
+             my.custom.annotation/v1: v1-rhpam-app-console
+----
++
+To update {KIE_SERVER}, add the following to the `## KIE Servers Start` placeholder identifier:
++
+[source, yaml]
+----
+             annotations:
+               my.custom.annotation/v1: v1-rhpam-app-kieserver
+----
++
+[NOTE]
+====
+You can also edit the Smart Router configuration using this ConfigMap.
+====
+
+. To save the changes, complete one of the following steps:
+** In the `oc` tool editor, to save the change the change and exit, enter `:wq!`.
+** In the the {OPENSHIFT} console, to save the change using the {OPENSHIFT} console, click *Save*.
+
+. If an environment is running and the operator didn’t automatically start redeployment for the component that was changed, you must manually delete the DeploymentConfig of the target component by using `oc` command tool by completing the following steps:
+.. To return the DeploymentConfig, run the following command:
++
+[source]
+----
+$ oc get dc
+----
++
+The output of `oc get dc` is returned.
++
+.Example output of `oc get dc`:
+[source]
+----
+$ oc get dc
+NAME                          REVISION   DESIRED   CURRENT   TRIGGERED BY
+rhpam-authoring-kieserver            1         1         1         config
+rhpam-authoring-rhpamcentr           1         1         1         config
+----
+
+.. To delete the DeploymentConfig of the target components, run the following commands:
++
+[source]
+----
+$ oc delete dc/rhpam-authoring-kieserver
+----
++
+[source]
+----
+$ oc delete dc/rhpam-authoring-rhpamcentr
+----
++
+The deployment is redeployed with the changes applied in the ConfigMap.
+
+. To verify that the change was applied by checking the annotations for the {KIE_SERVER} DeploymentConfig, run the following command:
++
+[source]
+----
+$ oc describe dc/rhpam-authoring-kieserver
+----
++
+.Example output of `oc describe dc/rhpam-authoring-kieserver`:
+[source]
+----
+Name:		rhpam-authoring-kieserver
+Namespace:	examplenamespace
+Created:	15 minutes ago
+Labels:		app=rhpam-authoring
+		application=rhpam-authoring
+		service=rhpam-authoring-kieserver
+		services.server.kie.org/kie-server-id=rhpam-authoring-kieserver
+Annotations:	my.custom.annotation/v1=v1-rhpam-app-kieserver
+----