From e98941e16d176749ace5181ae06c61bbe0cf6119 Mon Sep 17 00:00:00 2001
From: Tim Bielawa <tbielawa@redhat.com>
Date: Tue, 3 Oct 2017 16:17:15 -0400
Subject: Documentation

* Update README
* Add parameter docs to inventory examples
* Remove unused graphic
* Update defaults
---
 roles/openshift_cfme/README.md | 251 ++++++++++++++++++++++++++---------------
 1 file changed, 163 insertions(+), 88 deletions(-)

(limited to 'roles/openshift_cfme/README.md')

diff --git a/roles/openshift_cfme/README.md b/roles/openshift_cfme/README.md
index 5d90e532f..98cefa6b4 100644
--- a/roles/openshift_cfme/README.md
+++ b/roles/openshift_cfme/README.md
@@ -1,13 +1,23 @@
 # CloudForms Availability
 
 As noted in [Limitations - Product Choice](#product-choice),
-CloudForms 4.6 is not yet released. Until such time, this role is
-limited to installing ManageIQ, the open source project that CFME is
-based on.
+[CloudForms](https://www.redhat.com/en/technologies/management/cloudforms)
+(CFME) 4.6 is not yet released. Until such time, this role is limited
+to installing [ManageIQ](http://manageiq.org) (MIQ), the open source
+project that CFME is based on.
+
+After CFME 4.6 is available to customers this role will enable
+(optional) logic which will install CFME or MIQ based on your
+deployment type (`openshift_deployment_type`):
+
+* `openshift-enterprise` → CloudForms
+* `origin` → ManageIQ
+
 
 # Table of Contents
 
    * [Introduction](#introduction)
+      * [Important Notes](#important-notes)
    * [Requirements](#requirements)
    * [Role Variables](#role-variables)
    * [Getting Started](#getting-started)
@@ -18,49 +28,60 @@ based on.
       * [External PostgreSQL Database](#external-postgresql-database)
    * [Limitations](#limitations)
       * [Product Choice](#product-choice)
-      * [Storage](#storage)
-      * [Database](#database)
    * [Configuration](#configuration)
-      * [Configuration - Storage Classes](#configuration---storage-classes)
+      * [Database](#database)
+         * [Podified](#podified)
+         * [External](#external)
+      * [Storage Classes](#storage-classes)
          * [NFS (Default)](#nfs-default)
          * [NFS External](#nfs-external)
          * [Cloud Provider](#cloud-provider)
          * [Preconfigured (Expert Configuration Only)](#preconfigured-expert-configuration-only)
-      * [Configuration - Database](#configuration---database)
-         * [Podified Database](#podified-database)
-         * [External Database](#external-database)
    * [Customization](#customization)
    * [Additional Information](#additional-information)
 
 # Introduction
 
-This role will allow a user to install CFME 4.6 or ManageIQ on an OCP
+This role will allow a user to install CFME 4.6 or MIQ on an OCP
 3.7 cluster. The role provides customization options for overriding
-default deployment parameters. The role includes several choices for
-storage classes.
+default deployment parameters. This role allows the user to deploy
+different installation flavors:
+
+* **Fully Podified** - In this way all application services are ran as
+  pods in the container platform.
+* **External Database** - In this way the application utilizes an
+  externally hosted database server. All other services are ran in the
+  container platform.
 
-This role includes the following storage class options
+This role includes the following storage class options:
 
 * NFS - **Default** - local, on cluster
 * NFS External - NFS somewhere else, like a storage appliance
 * Cloud Provider - Use automatic storage provisioning from your cloud
-  provider (`gce` or `aws`)
+  provider (*gce* or *aws*)
 * Preconfigured - **expert only**, assumes you created everything ahead
   of time
 
-This role allows you to host the required PostgreSQL database podified
-(on a pod in the cluster) or externally (on an existing PostgreSQL
-host).
-
 You may skip ahead to the [Getting Started](#getting-started) section
 now for examples of how to set up your Ansible inventory for various
-deployment configurations. However, you are **strongly urged** to read
-through the [Configuration](#configuration) and
-[Customization](#customization) sections first.
+deployment configurations. However, you are **strongly urged** to
+first read through the [Configuration](#configuration) and
+[Customization](#customization) sections as well as the following
+[Important Note](#important-notes).
 
-# Requirements
+## Important Notes
+
+Not all parameters are present in **both** template versions (podified
+db and external db). For example, while the podified database template
+has a `POSTGRESQL_MEM_REQ` parameter, no such parameter is present in
+the external db template, as there is no need for this information due
+to there being no databases that require pods.
 
-* OCP 3.7 must be installed **before** running this role.
+*Be extra careful* if you are overriding template
+parameters. Including parameters not defined in a template **will
+cause errors**.
+
+# Requirements
 
 The **default** requirements are listed in the table below. These can
 be overridden through customization parameters (See
@@ -76,27 +97,32 @@ even fail to deploy, if these requirements are not satisfied.
 | Application Storage | `≥ 5.0 Gi`    | Minimum PV size required for the application | `APPLICATION_VOLUME_CAPACITY` |
 | PostgreSQL Memory   | `≥ 6.0 Gi`    | Minimum required memory for the database     | `POSTGRESQL_MEM_REQ`          |
 | PostgreSQL Storage  | `≥ 15.0 Gi`   | Minimum PV size required for the database    | `DATABASE_VOLUME_CAPACITY`    |
-| Cluster Hosts       | `≥ 3`         | Number of hosts in your cluster              | `∅`                           |
+| Cluster Hosts       | `≥ 3`         | Number of hosts in your cluster              |                               |
 
 The implications of this table are summarized below:
 
 * You need several cluster nodes
 * Your cluster nodes must have lots of memory available
-* You will need several GiB's of storage available
+* You will need several GiB's of storage available, either locally or
+  on your cloud provider
 
 
 # Role Variables
 
+The following is a table of the publicly exposed variables that may be
+used in your Ansible inventory to control the behavior of this
+installer.
 
 
 | Variable                                       | Required | Default                        | Description                         |
 |------------------------------------------------|:--------:|:------------------------------:|-------------------------------------|
 | `openshift_cfme_project`                       | **No**   | `openshift-cfme`               | Namespace for the installation.     |
 | `openshift_cfme_project_description`           | **No**   | *CloudForms Management Engine* | Namespace/project description.      |
+| `openshift_cfme_install_cfme`                  | **No**   | `false`                        | Boolean, set to `true` to install the application |
 | **PRODUCT CHOICE**  | | | | |
 | `openshift_cfme_app_template`                  | **No**   | `miq-template`                 | The project flavor to install. Choices: <ul><li>`miq-template`: ManageIQ using a podified database</li> <li> `miq-template-ext-db`: ManageIQ using an external database</li> <li>`cfme-template`: CloudForms using a podified database<sup>[1]</sup></li> <li> `cfme-template-ext-db`: CloudForms using an external database.<sup>[1]</sup></li></ul> |
-| **STORAGE OPTIONS** | | | | |
-| `openshift_cfme_storage_class`                 | **No**   | `nfs`                          | Storage type to use, choices: <ul><li>`nfs` - Best used for proof-of-concept installs. Will setup NFS on a cluster host (defaults to your first master in the inventory file) to back the required PVCs. The application requires a PVC and the database (which may be hosted externally) may require a second. PVC minimum required sizes are 5GiB for the MIQ application, and 15GiB for the PostgreSQL database (20GiB minimum available space on a volume/partition if used specifically for NFS purposes)</li> <li>`nfs_external` - You are using an external NFS server, such as a netapp appliance. See the [Configuration - Storage Classes](#configuration---storage-classes) section below for required information.</li> <li>`preconfigured` - This CFME role will do NOTHING to modify storage settings. This option assumes expert knowledge and that you have done everything required ahead of time.</li> <li>`cloudprovider` - You are using an OCP cloudprovider integration for your storage class. For this to work you must have already configured the required inventory parameters for your cloud provider. Ensure `openshift_cloudprovider_kind` is defined (aws or gce) and that the applicable cloudprovider parameters are provided. |
+| **STORAGE CLASSES** | | | | |
+| `openshift_cfme_storage_class`                 | **No**   | `nfs`                          | Storage type to use, choices: <ul><li>`nfs` - Best used for proof-of-concept installs. Will setup NFS on a cluster host (defaults to your first master in the inventory file) to back the required PVCs. The application requires a PVC and the database (which may be hosted externally) may require a second. PVC minimum required sizes are 5GiB for the MIQ application, and 15GiB for the PostgreSQL database (20GiB minimum available space on a volume/partition if used specifically for NFS purposes)</li> <li>`nfs_external` - You are using an external NFS server, such as a netapp appliance. See the [Configuration - Storage Classes](#storage-classes) section below for required information.</li> <li>`preconfigured` - This CFME role will do NOTHING to modify storage settings. This option assumes expert knowledge and that you have done everything required ahead of time.</li> <li>`cloudprovider` - You are using an OCP cloudprovider integration for your storage class. For this to work you must have already configured the required inventory parameters for your cloud provider. Ensure `openshift_cloudprovider_kind` is defined (aws or gce) and that the applicable cloudprovider parameters are provided. |
 | `openshift_cfme_storage_nfs_external_hostname` | **No**   | `false`                        | If you are using an *external NFS server*, such as a netapp appliance, then you must set the hostname here. Leave the value as `false` if you are not using external NFS. <br /> *Additionally*: **External NFS REQUIRES** that you create the NFS exports that will back the application PV and optionally the database PV.
 | `openshift_cfme_storage_nfs_base_dir`          | **No**   | `/exports/`                    | If you are using **External NFS** then you may set the base path to the exports location here. <br />**Local NFS Note**: You *may* also change this value if you want to change the default path used for local NFS exports. |
 | `openshift_cfme_storage_nfs_local_hostname`    | **No**   | `false`                        | If you do not have an `[nfs]` group in your inventory, or want to simply manually define the local NFS host in your cluster, set this parameter to the hostname of the preferred NFS server. The server must be a part of your OCP/Origin cluster. |
@@ -117,9 +143,8 @@ The implications of this table are summarized below:
 Below are some inventory snippets that can help you get started right
 away.
 
-Once you've settled on a configuration scheme (and you have installed
-OCP 3.7) you can install CFME using this `ansible-playbook`
-invocation:
+Once you've settled on a configuration scheme you can install CFME
+using this `ansible-playbook` invocation:
 
 ```
 $ ansible-playbook -v -i <YOUR_INVENTORY> playbooks/byo/openshift-cfme/config.yml
@@ -130,7 +155,7 @@ $ ansible-playbook -v -i <YOUR_INVENTORY> playbooks/byo/openshift-cfme/config.ym
 This example is the simplest. All of the default values and choices
 are used. This will result in a fully podified CFME installation. All
 application components, as well as the PostgreSQL database will be
-created as pods in the OCP cluster.
+created as pods in the container platform.
 
 ```ini
 [OSEv3:vars]
@@ -207,13 +232,13 @@ or `cfme-template-ext-db`.
 
 Additionally, database connection information **must** be supplied in
 the `openshift_cfme_template_parameters` customization parameter. See
-[Customization - Database - External](#external-database) for more
+[Customization - Database - External](#external) for more
 information.
 
 ```ini
 [OSEv3:vars]
-openshift_cfme_app_template=miq-template-ext-db
-openshift_cfme_template_parameters={'DATABASE_IP': '10.9.8.7', 'DATABASE_PASSWORD': 'r1ck&M0r7y', ... }
+openshift_cfme_app_template=cfme-template-ext-db
+openshift_cfme_template_parameters={'DATABASE_USER': 'root', 'DATABASE_PASSWORD': 'r1ck&M0r7y', 'DATABASE_IP': '10.10.10.10', 'DATABASE_PORT': '5432', 'DATABASE_NAME': 'cfme'}
 ```
 
 # Limitations
@@ -228,18 +253,6 @@ integrated**. Presently this role will only deploy a ManageIQ
 installation. This role will be updated once CFME 4.6 is released and
 this limitation note will be removed.
 
-## Storage
-
-While all storage classes (`nfs`, `nfs_external`, `preconfigured`, and
-`cloudprovider`) are presently supported, the local `nfs` storage
-class has some specific limitations:
-
-1. Currently only verified to work if your first master is your NFS
-   host
-1. Overriding the base exports path is not recommended as this may
-   cause configuration conflicts with other exports on your host
-
-
 # Configuration
 
 Before you can deploy CFME you must decide *how* you want to deploy
@@ -248,15 +261,101 @@ it. There are two major decisions to make:
 1. Do you want an external, or a podified database?
 1. Which storage class will back your PVs?
 
-## Configuration - Storage Classes
+## Database
+
+### Podified
+
+Any `POSTGRES_*` or `DATABASE_*` template parameters in
+[miq-template.yaml](files/templates/manageiq/miq-template.yaml) or
+[cfme-template.yaml](files/templates/cloudforms/cfme-template.yaml)
+may be customized through the `openshift_cfme_template_parameters`
+hash.
+
+### External
+
+Any `POSTGRES_*` or `DATABASE_*` template parameters in
+[miq-template-ext-db.yaml](files/templates/manageiq/miq-template-ext-db.yaml)
+or
+[cfme-template-ext-db.yaml](files/templates/cloudforms/cfme-template-ext-db.yaml)
+may be customized through the `openshift_cfme_template_parameters`
+hash.
+
+External PostgreSQL databases require you to provide database
+connection parameters. You must set the required connection keys in
+the `openshift_cfme_template_parameters` parameter in your
+inventory. The following keys are required:
+
+* `DATABASE_USER`
+* `DATABASE_PASSWORD`
+* `DATABASE_IP`
+* `DATABASE_PORT` - *note: Most PostgreSQL servers run on port `5432`*
+* `DATABASE_NAME`
+
+Your inventory would contain a line similar to this:
+
+```ini
+[OSEv3:vars]
+openshift_cfme_app_template=cfme-template-ext-db
+openshift_cfme_template_parameters={'DATABASE_USER': 'root', 'DATABASE_PASSWORD': 'r1ck&M0r7y', 'DATABASE_IP': '10.10.10.10', 'DATABASE_PORT': '5432', 'DATABASE_NAME': 'cfme'}
+```
+
+**Note** the new value for the `openshift_cfme_app_template`
+parameter, `cfme-template-ext-db` (ManageIQ installations would use
+`miq-template-ext-db` instead).
+
+At run time you may run into errors similar to this:
+
+```
+TASK [openshift_cfme : Ensure the CFME App is created] ***********************************
+task path: /home/tbielawa/rhat/os/openshift-ansible/roles/openshift_cfme/tasks/main.yml:74
+Tuesday 03 October 2017  15:30:44 -0400 (0:00:00.056)       0:00:12.278 *******
+{"cmd": "/usr/bin/oc create -f /tmp/postgresql-ZPEWQS -n openshift-cfme", "kind": "Endpoints", "results": {}, "returncode": 1, "stderr": "Error from server (BadRequest): error when creating \"/tmp/postgresql-ZPEWQS\": Endpoints in version \"v1\" cannot be handled as a Endpoints: [pos 218]: json: decNum: got first char 'f'\n", "stdout": ""}
+```
+
+Or like this:
+
+```
+TASK [openshift_cfme : Ensure the CFME App is created] ***********************************
+task path: /home/tbielawa/rhat/os/openshift-ansible/roles/openshift_cfme/tasks/main.yml:74
+Tuesday 03 October 2017  16:05:36 -0400 (0:00:00.052)       0:00:18.948 *******
+fatal: [m01.example.com]: FAILED! => {"changed": true, "failed": true, "msg":
+{"cmd": "/usr/bin/oc create -f /tmp/postgresql-igS5sx -n openshift-cfme", "kind": "Endpoints", "results": {}, "returncode": 1, "stderr": "The Endpoints \"postgresql\" is invalid: subsets[0].addresses[0].ip: Invalid value: \"doo\": must be a valid IP address, (e.g. 10.9.8.7)\n", "stdout": ""},
+```
+
+While intimidating at first, there are useful bits of information in
+here. Examine the error output closely and we can tell exactly what is
+wrong.
+
+In the first example we see `Endpoints in version \"v1\" cannot be
+handled as a Endpoints: [pos 218]: json: decNum: got first char
+...`. This is because in my example I used the value `foo` for the
+parameter `DATABASE_PORT`.
+
+In the second example we see `The Endpoints \"postgresql\" is invalid:
+subsets[0].addresses[0].ip: Invalid value: \"doo\": must be a valid IP
+address ...`. This is because in my example I used the value `doo` in
+the `DATABASE_IP` field.
+
+Luckily for us when the templates are processed behind the scenes they
+are also running type checking validation. So, don't worry, just look
+closely at the errors and ensure you are providing the correct values
+for each parameter.
+
+## Storage Classes
 
 OpenShift CFME supports several storage class options.
 
-###  NFS (Default)
+### NFS (Default)
 
 The NFS storage class is best suited for proof-of-concept and
 test/demo deployments. It is also the **default** storage class for
-deployments. No additional configuration is required for this choice.
+deployments. No additional configuration is required for this
+choice.
+
+Customization is provided through the following role variables:
+
+* `openshift_cfme_storage_nfs_base_dir`
+* `openshift_cfme_storage_nfs_local_hostname`
 
 ### NFS External
 
@@ -266,15 +365,19 @@ for the required PVs. For external NFS you must have:
 * For CFME: a `cfme-app` and optionally a `cfme-db` (for podified database) exports
 * For ManageIQ: an `miq-app` and optionally an `miq-db` (for podified database) exports
 
-Additional configuration is required to use external NFS. The
-`openshift_cfme_storage_nfs_external_hostname` parameter must be set
-to the hostname or IP of your external NFS server.
+Configuration is provided through the following role variables:
+
+* `openshift_cfme_storage_nfs_external_hostname`
+* `openshift_cfme_storage_nfs_base_dir`
+
+The `openshift_cfme_storage_nfs_external_hostname` parameter must be
+set to the hostname or IP of your external NFS server.
 
-If `/exports` is not the parent directory to your CFME exports then
-you must set the base directory via the
+If `/exports` is not the parent directory to your exports then you
+must set the base directory via the
 `openshift_cfme_storage_nfs_base_dir` parameter.
 
-For example, if your server export is `/exports/hosted/prod/miq-app`
+For example, if your server export is `/exports/hosted/prod/cfme-app`
 then you must set
 `openshift_cfme_storage_nfs_base_dir=/exports/hosted/prod`.
 
@@ -289,6 +392,9 @@ Using this storage class, when the application is created the required
 PVs will automatically be provisioned using the configured cloud
 provider storage integration.
 
+There are no additional variables to configure the behavior of this
+storage class.
+
 ### Preconfigured (Expert Configuration Only)
 
 The *preconfigured* storage class implies that you know exactly what
@@ -296,39 +402,8 @@ you're doing and that all storage requirements have been taken care
 ahead of time. Typically this means that you've already created the
 correctly sized PVs.
 
-## Configuration - Database
-
-### Podified Database
-
-Any `POSTGRES_*` or `DATABASE_*` template parameters in
-[miq-template.yaml](files/templates/manageiq/miq-template.yaml) or
-[cfme-template.yaml](files/templates/cloudforms/cfme-template.yaml)
-may be customized through the `openshift_cfme_template_parameters`
-hash.
-
-### External Database
-
-External PostgreSQL databases require you to provide database
-connection parameters. You must set the required connection keys in
-the `openshift_cfme_template_parameters` parameter in your
-inventory. The following keys are required:
-
-* `DATABASE_USER`
-* `DATABASE_PASSWORD`
-* `DATABASE_IP`
-* `DATABASE_PORT` - *note: Most PostgreSQL servers run on port `5432`*
-* `DATABASE_NAME`
-
-Your inventory would contain a line similar to this:
-
-```ini
-[OSEv3:vars]
-openshift_cfme_app_template=miq-template-ext-db
-openshift_cfme_template_parameters={'DATABASE_IP': '10.9.8.7', 'DATABASE_PASSWORD': 'r1ck&M0r7y', ...}
-```
-
-**Note** the new value for the `openshift_cfme_app_template`
-parameter, `miq-template-ext-db`.
+There are no additional variables to configure the behavior of this
+storage class.
 
 # Customization
 
-- 
cgit v1.2.3