Bxmsdoc 2083 master

docs/product-assembly_dm-on-openshift/src/main/asciidoc/ba/.gitignore

@@ -0,0 +1 @@
+build

docs/product-assembly_dm-on-openshift/src/main/asciidoc/ba/master-docinfo.xml

@@ -0,0 +1,10 @@
+<productname>{PRODUCT}</productname>
+<productnumber>{PRODUCT_VERSION}</productnumber>
+<subtitle>
+	For {PRODUCT} {PRODUCT_VERSION}
+
+</subtitle>
+<abstract>
+	<para>This topic describes deploying {PRODUCT} {PRODUCT_VERSION} in an OpenShift environment.</para>
+</abstract>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

docs/product-assembly_dm-on-openshift/src/main/asciidoc/ba/master.adoc

@@ -0,0 +1,4 @@
+
+:BA:
+
+include::topics/main.adoc[]

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm-openshift-deploy-con.adoc

@@ -0,0 +1,8 @@
+[id='dm-openshift-deploy-con']
+= Deploying {PRODUCT} in your OpenShift environment
+
+To deploy {PRODUCT} in your OpenShift environment, use the OpenShift templates that are provided with {PRODUCT}.
+
+.Prerequisites
+You must complete the preparatory tasks as described in <<dm-openshift-prepare-con>>.
+

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm-openshift-overview-con.adoc

@@ -0,0 +1,16 @@
+[id='dm-openshift-overview-con']
+= Overview
+
+If you have an OpenShift environment, you can deploy {PRODUCT} into this environment instead of a regular on-premises deployment. 
+
+In this solution, {KIE_SERVER} is deployed as an OpenShift pod. You can scale the pod up and down, providing as few or as many containers as necessary. You can use all standard OpenShift methods to manage the pod, balance the load, and deploy new versions.
+
+You can also deploy {CENTRAL} on the OpenShift infrastructure together with {KIE_SERVER}. In this case, you can use {CENTRAL} to manage the {KIE_SERVER} and to develop new rules.
+
+Alternatively, you can deploy {KIE_SERVER} without {CENTRAL}. To manage {KIE_SERVER} in this case, you have two options:
+
+* Use the _source to image_ (S2I) template and provide a Git repository with the source of your decision service. OpenShift automatically builds the source, installs the decision service into the {KIE_SERVER} image, and starts the service. No further management of the image is required. If you want to use a new version of the decision service, you can build a new image. This option is often preferable for typical version management approaches (DevOps) in a containerized infrastructure.
+
+* Use an instance of {CENTRAL} installed on-premises (without OpenShift) or a stand-alone management console installed on-premises to manage the {KIE_SERVER} that is deployed in OpenShift.
+
+IMPORTANT: All calls to the {KIE_SERVER} that runs on OpenShift must be stateless. While the server accepts stateful calls, the state might not be saved between calls, because the server can be scaled to multiple containers or might be restarted by OpenShift automatically.

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm-openshift-prepare-con.adoc

@@ -0,0 +1,10 @@
+[id='dm-openshift-prepare-con']
+= Preparing to deploy {PRODUCT} in your OpenShift environment
+
+Before deploying {PRODUCT} in your OpenShift environment, you need to complete several preparatory tasks. You do not need to redo these tasks if you want to deploy additional images, for example, for new versions of decision services or for other decision services. 
+
+.Prerequisites
+
+* Ensure that at least 4 gigabytes of memory are available in the OpenShift environment.
+* Create the OpenShift project for the deployment. 
+* Log in to the project using the OpenShift web console and using the `oc` command.

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm/.gitignore

@@ -0,0 +1 @@
+build

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm/master-docinfo.xml

@@ -0,0 +1,10 @@
+<productname>{PRODUCT}</productname>
+<productnumber>{PRODUCT_VERSION}</productnumber>
+<subtitle>
+	For {PRODUCT} {PRODUCT_VERSION}
+
+</subtitle>
+<abstract>
+	<para>This topic describes deploying {PRODUCT} {PRODUCT_VERSION} in an OpenShift environment.</para>
+</abstract>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

docs/product-assembly_dm-on-openshift/src/main/asciidoc/dm/master.adoc

@@ -0,0 +1,4 @@
+
+:DM:
+
+include::topics/main.adoc[]

docs/product-assembly_dm-on-openshift/src/main/asciidoc/imagestreams-file-install-proc.adoc

@@ -0,0 +1,17 @@
+[id='imagestreams-file-install-proc']
+= Installing the image streams file
+
+You must install the image streams file into the OpenShift environment. This file provides the required information for downloading necessary images from the Red Hat repository.
+
+The file is named `image_streams.json`. It is provided with {PRODUCT}.
+
+.Procedure
+Complete one of the following actions to install the file:
+
+* Using the OpenShift Web UI, select *Add to Project > Import YAML / JSON*, then choose the file or paste its contents.
+
+* Using the command line:
+[subs="verbatim,macros"]
+----
+$ oc create -f image_streams.json
+----

docs/product-assembly_dm-on-openshift/src/main/asciidoc/kieserver-central-deploy-proc.adoc

@@ -0,0 +1,18 @@
+[id='kieserver-central-deploy-proc']
+= Deploying {CENTRAL} and {KIE_SERVER}
+
+You can deploy {CENTRAL} on the OpenShift infrastructure together with {KIE_SERVER}. In this case, you can use {CENTRAL} to manage the {KIE_SERVER} and to develop new rules.
+
+.Procedure
+. In the OpenShift Web UI, select *Import YAML / JSON* and then select or paste the `rhdm70-full.yaml` file, which is supplied with {PRODUCT}.
+. In the *Add Template* window, ensure *Process the template* is selected and click *Continue*.
+. Set the following mandatory parameters:
+** *Application Name*: the name of the OpenShift application. It is used in the default URLs for {CENTRAL} and {KIE_SERVER}.
+** *Decision Central Server Certificate Name*: the name of the certificate in the keystore that you created in <<secrets-central-create-proc>>.
+** *Decision Central Server Keystore Password*: the password for the keystore that you created in <<secrets-central-create-proc>>.
+** *KIE Server Certificate Name*: the name of the certificate in the keystore that you created in <<secrets-kie-create-proc>>.
+** *KIE Server Keystore Password*: the password for the keystore that you created in <<secrets-kie-create-proc>>.
+** *ImageStream Namespace*: the name of the OpenShift project.
+
+You can also set other parameters as necessary.
+. Click *Create*.

docs/product-assembly_dm-on-openshift/src/main/asciidoc/kieserver-nos2i-deploy-proc.adoc

@@ -0,0 +1,39 @@
+[id='kieserver-nos2i-deploy-proc']
+= Deploying {KIE_SERVER} without using Source to Image (S2I)
+
+
+You can deploy {KIE_SERVER} on the OpenShift infrastructure without {CENTRAL} and without S2I. In this case, {KIE_SERVER} can pick up a decision service from a Maven repository. However, to load the service, you must manage the {KIE_SERVER} using one of the following tools:
+
+* {CENTRAL}, installed outside of the OpenShift environment
+* A stand-alone management console, installed outside of the OpenShift environment
+* The API.
+
+.Before you begin
+
+Ensure that the Maven repository for your decision service is available.
+
+If you are planning to use {CENTRAL} or a management console, ensure that it is installed and record its settings for controlling a KIE server.
+
+.Procedure
+. In the OpenShift Web UI, select *Import YAML / JSON* and then select or paste the `rhdm70-kieserver.yaml` file, which is supplied with {PRODUCT}.
+. In the *Add Template* window, ensure *Process the template* is selected and click *Continue*.
+. Set the following mandatory parameters:
+** *Application Name*: the name of the OpenShift application. It is used in the default URLs for {CENTRAL} and {KIE_SERVER}.
+** *KIE Server Certificate Name*: the name of the certificate in the keystore that you created in <<secrets-kie-create-proc>>.
+** *KIE Server Keystore Password*: the password for the keystore that you created in <<secrets-kie-create-proc>>.
+** *ImageStream Namespace*: the name of the OpenShift project.
+
+You can also set other parameters as necessary. In particular, if you want to use {CENTRAL} or a stand-alone management console, set the following parameters according to the settings available:
+
+** *KIE server controller protocol*
+** *KIE server controller service*
+** *KIE server controller host*
+** *KIE server controller port*
+
+If you want to set the Maven repository for retrieving the decision service, set the following parameters to point to the repository:
+
+** *Maven repository URL*
+** *Maven repository username*
+** *Maven repository password*
+
+. Click *Create*.

docs/product-assembly_dm-on-openshift/src/main/asciidoc/kieserver-s2i-deploy-proc.adoc

@@ -0,0 +1,24 @@
+[id='kieserver-s2i-deploy-proc']
+= Deploying {KIE_SERVER} using Source to Image (S2I)
+
+You can deploy {KIE_SERVER} on the OpenShift infrastructure using Source to Image (S2I). In this case, provide a Git repository with the source of your decision service. OpenShift automatically builds the source, installs the decision service into the {KIE_SERVER} image, and starts the service. No further management of the image is required. If you want to use a new version of the decision service, you can build a new image. This option is often preferable for typical version management approaches (DevOps) in a containerized infrastructure.
+
+.Before you begin
+
+Ensure that the complete source code for your decision service is available in a Git repository that the OpenShift server can access. The source code is built using a Maven process, so it must include a `pom.xml` file.
+
+.Procedure
+. In the OpenShift Web UI, select *Import YAML / JSON* and then select or paste the `rhdm70-kieserver-s2i.yaml` file, which is supplied with {PRODUCT}.
+. In the *Add Template* window, ensure *Process the template* is selected and click *Continue*.
+. Set the following mandatory parameters:
+** *Application Name*: the name of the OpenShift application. It is used in the default URLs for {CENTRAL} and {KIE_SERVER}.
+** *KIE Server Certificate Name*: the name of the certificate in the keystore that you created in <<secrets-kie-create-proc>>.
+** *KIE Server Keystore Password*: the password for the keystore that you created in <<secrets-kie-create-proc>>.
+** *KIE Server Container Deployment*: the identifying information of the decision service (KJAR file) that is built from your source. The format is: `<containerId>=<groupId>:<artifactId>:<version>`. You can provide two or more KJAR files using the `|` separator, for example: `containerId=groupId:artifactId:version|c2=g2:a2:v2`. The Maven build process must produce all these files from the source in the Git repository.
+** *Git Repository URL*: the URL for the Git repository that contains the source for your decision service.
+** *Git Reference*: the branch in the Git repository
+** *Context Directory*: the path to the source in the Git repository
+** *ImageStream Namespace*: the name of the OpenShift project.
+
+You can also set other parameters as necessary. In particular, if you want the built binaries to be saved in a Maven repository, set the *Maven mirror URL* parameter.
+. Click *Create*.

docs/product-assembly_dm-on-openshift/src/main/asciidoc/main.adoc

@@ -0,0 +1,30 @@
+[id='assembly_dm-on-openshift']
+
+include::product-shared-docs/document-attributes.adoc[]
+
+= Decision Manager on OpenShift
+// Context attribute is assembly specific and enables module reuse between assemblies.
+:imagesdir: topics/product-shared-docs/images
+:context: dm-on-openshift
+include::product-shared-docs/author-group.adoc[]
+
+// Purpose statement for the assembly
+As a system administrator, you can deploy and manage {PRODUCT} in an OpenShift environment. The OpenShift platform automates container deployment and management. You can use the templates provided with Decision Manager to deploy it into OpenShift and to scale it as necessary.
+
+.Prerequisite
+You must have a deployed OpenShift environment. For deta
+ils, see the documentation for the OpenShift product that you use.
+
+// Modules - concepts, procedures, refs, etc.
+include::dm-openshift-overview-con.adoc[leveloffset=+1]
+include::dm-openshift-prepare-con.adoc[leveloffset=+1]
+include::imagestreams-file-install-proc.adoc[leveloffset=+2]
+include::secrets-kie-create-proc.adoc[leveloffset=+2]
+include::secrets-central-create-proc.adoc[leveloffset=+2]
+include::dm-openshift-deploy-con.adoc[leveloffset=+1]
+include::kieserver-central-deploy-proc.adoc[leveloffset=+2]
+include::kieserver-s2i-deploy-proc.adoc[leveloffset=+2]
+include::kieserver-nos2i-deploy-proc.adoc[leveloffset=+2]
+
+// Versioning info
+include::product-shared-docs/versioning-information.adoc[]

docs/product-assembly_dm-on-openshift/src/main/asciidoc/secrets-central-create-proc.adoc

@@ -0,0 +1,30 @@
+[id='secrets-central-create-proc']
+= Creating the secrets for {CENTRAL}
+
+If you are planning to deploy {CENTRAL} in your OpenShift environment, you must create an SSL certificate for {CENTRAL} and provide it to your OpenShift environment as a secret. Do not use the same certificate and keystore for {CENTRAL} and for {KIE_SERVER}.
+
+.Procedure
+. Generate an SSL keystore with a private and public key for SSL encryption for {CENTRAL}. For production use, generate a valid signed certificate that matches the expected URL of the {CENTRAL}. Save the keystore in a file named `keystore.jks`. Record the name of the certificate and the password of the keystore file.
+
+See https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.1/html-single/Security_Guide/index.html#Generate_a_SSL_Encryption_Key_and_Certificate[Generate a SSL Encryption Key and Certificate] for more information on how to create a keystore with self-signed or purchased SSL certificates.
+
+. Use the `oc` command to generate a secret named `decisioncentral-app-secret` from the new keystore file:
+
+[subs="verbatim,macros"]
+----
+$ oc create secret generic decisioncentral-app-secret --from-file=keystore.jks
+----
+
+. Create a service account named `decisioncentral-service-account`:
+
+[subs="verbatim,macros"]
+----
+$ oc create serviceaccount decisioncentral-service-account
+----
+
+. Add the secret to the service account:
+
+[subs="verbatim,macros"]
+----
+$ oc secret add sa/decisioncentral-service-account secret/decisioncentral-app-secret
+----

docs/product-assembly_dm-on-openshift/src/main/asciidoc/secrets-kie-create-proc.adoc

@@ -0,0 +1,32 @@
+[id='secrets-kie-create-proc']
+= Creating the secrets for {KIE_SERVER}
+
+OpenShift uses objects called `Secrets` to hold sensitive information, such as passwords or keystores. See the https://access.redhat.com/documentation/en/openshift-enterprise/version-3.2/developer-guide/#dev-guide-secrets[Secrets chapter] in the OpenShift documentation for more information.
+
+You must create an SSL certificate for {KIE_SERVER} and provide it to your OpenShift environment as a secret.
+
+.Procedure
+. Generate an SSL keystore with a private and public key for SSL encryption for {KIE_SERVER}. For production use, generate a valid signed certificate that matches the expected URL of the {KIE_SERVER}. Save the keystore in a file named `keystore.jks`. Record the name of the certificate and the password of the keystore file.
+
+See https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.1/html-single/Security_Guide/index.html#Generate_a_SSL_Encryption_Key_and_Certificate[Generate a SSL Encryption Key and Certificate] for more information on how to create a keystore with self-signed or purchased SSL certificates.
+
+. Use the `oc` command to generate a secret named `kieserver-app-secret` from the new keystore file:
+
+[subs="verbatim,macros"]
+----
+$ oc create secret generic kieserver-app-secret --from-file=keystore.jks
+----
+
+. Create a service account named `kieserver-service-account`:
+
+[subs="verbatim,macros"]
+----
+$ oc create serviceaccount kieserver-service-account
+----
+
+. Add the secret to the service account:
+
+[subs="verbatim,macros"]
+----
+$ oc secret add sa/kieserver-service-account secret/kieserver-app-secret
+----