From e98941e16d176749ace5181ae06c61bbe0cf6119 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Tue, 3 Oct 2017 16:17:15 -0400 Subject: Documentation * Update README * Add parameter docs to inventory examples * Remove unused graphic * Update defaults --- inventory/byo/hosts.origin.example | 65 ++++++ inventory/byo/hosts.ose.example | 65 ++++++ roles/openshift_cfme/README.md | 251 +++++++++++++++-------- roles/openshift_cfme/defaults/main.yml | 19 +- roles/openshift_cfme/img/CFMEBasicDeployment.png | Bin 38316 -> 0 bytes 5 files changed, 294 insertions(+), 106 deletions(-) delete mode 100644 roles/openshift_cfme/img/CFMEBasicDeployment.png diff --git a/inventory/byo/hosts.origin.example b/inventory/byo/hosts.origin.example index c54d6bca7..29467816a 100644 --- a/inventory/byo/hosts.origin.example +++ b/inventory/byo/hosts.origin.example @@ -897,3 +897,68 @@ ose3-lb-ansible.test.example.com containerized=false [nodes] ose3-master[1:3]-ansible.test.example.com ose3-node[1:2]-ansible.test.example.com openshift_node_labels="{'region': 'primary', 'zone': 'default'}" +# CloudForms/ManageIQ (CFME/MIQ) Configuration + +# See the readme for full descriptions and getting started +# instructions: ../../roles/openshift_cfme/README.md or go directly to +# their definitions: ../../roles/openshift_cfme/defaults/main.yml +# ../../roles/openshift_cfme/vars/main.yml +# +# Namespace for the CFME project +#openshift_cfme_project: openshift-cfme + +# Namespace/project description +#openshift_cfme_project_description: CloudForms Management Engine + +# Choose 'miq-template' for a podified database install +# Choose 'miq-template-ext-db' for an external database install +# +# If you are using the miq-template-ext-db template then you must add +# the required database parameters to the +# openshift_cfme_template_parameters variable. +#openshift_cfme_app_template: miq-template + +# Allowed options: nfs, nfs_external, preconfigured, cloudprovider. +#openshift_cfme_storage_class: nfs + +# [OPTIONAL] - 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. +#openshift_cfme_storage_nfs_external_hostname: false + +# [OPTIONAL] - If you are using external NFS then you must set the base +# path to the exports location here. +# +# Additionally: EXTERNAL NFS REQUIRES that YOU CREATE the nfs exports +# that will back the application PV and optionally the database +# pv. Export path definitions, relative to +# {{ openshift_cfme_storage_nfs_base_dir }} +# +# LOCAL NFS NOTE: +# +# You may may also change this value if you want to change the default +# path used for local NFS exports. +#openshift_cfme_storage_nfs_base_dir: /exports + +# LOCAL NFS NOTE: +# +# You may override the automatically selected LOCAL NFS server by +# setting this variable. Useful for testing specific task files. +#openshift_cfme_storage_nfs_local_hostname: false + +# DEFAULT PV SIZES +# How large to make the MIQ application PV +#openshift_cfme_app_pv_size: 5Gi + +# How large to make the MIQ PostgreSQL PV +#openshift_cfme_db_pv_size: 15Gi + +# A hash of parameters you want to override or set in the +# miq-template.yaml or miq-template-ext-db.yaml templates. Set this in +# your inventory file as a simple hash. Acceptable values are defined +# under the .parameters list in files/miq-template{-ext-db}.yaml +# Example: +# +# openshift_cfme_template_parameters={'APPLICATION_MEM_REQ': '512Mi'} +#openshift_cfme_template_parameters: {} + diff --git a/inventory/byo/hosts.ose.example b/inventory/byo/hosts.ose.example index 7c637b3cb..ccba27177 100644 --- a/inventory/byo/hosts.ose.example +++ b/inventory/byo/hosts.ose.example @@ -900,3 +900,68 @@ ose3-lb-ansible.test.example.com containerized=false [nodes] ose3-master[1:3]-ansible.test.example.com ose3-node[1:2]-ansible.test.example.com openshift_node_labels="{'region': 'primary', 'zone': 'default'}" + +# CloudForms/ManageIQ (CFME/MIQ) Configuration + +# See the readme for full descriptions and getting started +# instructions: ../../roles/openshift_cfme/README.md or go directly to +# their definitions: ../../roles/openshift_cfme/defaults/main.yml +# ../../roles/openshift_cfme/vars/main.yml +# +# Namespace for the CFME project +#openshift_cfme_project: openshift-cfme + +# Namespace/project description +#openshift_cfme_project_description: CloudForms Management Engine + +# Choose 'miq-template' for a podified database install +# Choose 'miq-template-ext-db' for an external database install +# +# If you are using the miq-template-ext-db template then you must add +# the required database parameters to the +# openshift_cfme_template_parameters variable. +#openshift_cfme_app_template: miq-template + +# Allowed options: nfs, nfs_external, preconfigured, cloudprovider. +#openshift_cfme_storage_class: nfs + +# [OPTIONAL] - 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. +#openshift_cfme_storage_nfs_external_hostname: false + +# [OPTIONAL] - If you are using external NFS then you must set the base +# path to the exports location here. +# +# Additionally: EXTERNAL NFS REQUIRES that YOU CREATE the nfs exports +# that will back the application PV and optionally the database +# pv. Export path definitions, relative to +# {{ openshift_cfme_storage_nfs_base_dir }} +# +# LOCAL NFS NOTE: +# +# You may may also change this value if you want to change the default +# path used for local NFS exports. +#openshift_cfme_storage_nfs_base_dir: /exports + +# LOCAL NFS NOTE: +# +# You may override the automatically selected LOCAL NFS server by +# setting this variable. Useful for testing specific task files. +#openshift_cfme_storage_nfs_local_hostname: false + +# DEFAULT PV SIZES +# How large to make the MIQ application PV +#openshift_cfme_app_pv_size: 5Gi + +# How large to make the MIQ PostgreSQL PV +#openshift_cfme_db_pv_size: 15Gi + +# A hash of parameters you want to override or set in the +# miq-template.yaml or miq-template-ext-db.yaml templates. Set this in +# your inventory file as a simple hash. Acceptable values are defined +# under the .parameters list in files/miq-template{-ext-db}.yaml +# Example: +# +# openshift_cfme_template_parameters={'APPLICATION_MEM_REQ': '512Mi'} +#openshift_cfme_template_parameters: {} 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: | -| **STORAGE OPTIONS** | | | | | -| `openshift_cfme_storage_class` | **No** | `nfs` | Storage type to use, choices: