ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]
:toc: :toc-placement!:
= Installing Integreatly
:toc: toc::[]
= Overview
The purpose of this repository is to provide a set of Ansible playbooks that can be used to install a range of Red Hat middleware products & other projects via Ansible Tower on Openshift.
These products include:
== Prerequisites
.Prerequisites |=== |Requirement |Version |Ansible |>= v2.6 |Openshift Container Platform |>= v3.11 |Openshift CLI (OC) |>= v3.11 |===
== Installation Steps
=== RHPDS
The following steps will provide information on how to install Integreatly on an RHPDS Openshift cluster.
==== SSH to the master host and become root
[source,shell]
ssh -i /path/ocpkey.pem ec2-user@master.NAME-GUID.open.redhat.com
sudo -i==== Clone installation GIT repository on the master host
[source,shell]
git clone https://github.com/integr8ly/installation.git==== Create GitHub OAuth to enable GitHub authorization [OPTIONAL]
. Login into GitHub
. Go to Settings >> Developer Settings >> New OAuth App.
+
image::https://user-images.githubusercontent.com/7708031/48856646-dea13780-edae-11e8-9999-16b61dcc05ca.png[GitHub OAuth App]
. Add the following fields values + .Fields values descriptions |=== |Field |Value |Application Name |Any value |Home Page URL |http://localhost |Authorization callback URL |http://localhost |=== + IMPORTANT: The callback URL is a placeholder for now and will be changed after the installation playbook is finished.
. Click on Register Application
. The values found in GitHub OAuth App, Client ID and Client Secret, will be needed in the next step to install Integreatly.
image::https://user-images.githubusercontent.com/7708031/48856868-7141d680-edaf-11e8-836f-4d533f8ed402.png[GitHub OAuth App Fields]
==== Run the installation playbook
All products can be installed using the install.yml playbook located in the playbooks/ directory.
Before running the installer, please consider the following variables:
.Install playbook variables
|===
| Variable | Description
| eval_self_signed_certs | Whether the OpenShift cluster uses self-signed certs or not. Defaults to false
| github_client_id | GitHub OAuth client ID to enable GitHub authorization for Launcher. If not defined, GitHub authorization for Launcher will be disabled
| github_client_secret | GitHub OAuth client secret to enable GitHub authorization for Launcher. If not defined, GitHub authorization for Launcher will be disabled
| prerequisites_install | Boolean var that skips the installation of system wide tools/packages that are required by the installer if set to false (needs to be set to false when running the installer in a linux container). Defaults to true.
| heimdall_pull_secret_token | Heimdall pull secret token
|===
Some products can be excluded from the install by setting a var. For example, setting gitea=false will not install gitea. The flags for installing specific products can be found in the link:./inventories/group_vars/all/manifest.yaml[manifest.yaml] file
NOTE: Installation of individual products will not be a supported installation method with this repo. You can however write your own playbook to execute specific roles & tasks as needed.
By default Mobile Developer Services will not be installed. In order to install these services, consider the following variables.
.Install Mobile Developer Services
|===
| Variable | Description | Default Value
| ups | Whether Mobile Unified Push Server will be installed or not | true
| datasync | Whether DataSync components will be installed or not | true
|===
The installation can be run using the following command:
NOTE: If installing v1.5.2 or any prior release set the inventory file to inventories/hosts.template rather than inventories/pds.template as shown below
The following flag can be used if self signed certs are used.
To enable Heimdall you will need a valid pull secret token to access the registry, you can retrieve these from https://access.redhat.com/terms-based-registry/#/token/-heimdall/openshift-secret
Click on view its contents. Use the entry at data.dockerconfigjson to replace <your_secret_token> below.
[TIP] The following command installs Integreatly without GitHub authorization for Launcher.
==== Add the generated Authorization callback URL to GitHub OAuth
Replace the authorization callback URL previously containing a temporary localhost value with the output of the installation seen below.
image::https://user-images.githubusercontent.com/7708031/48856981-c1209d80-edaf-11e8-9d23-f550c7ec31be.png[GitHub OAuth auhotization callback URL, 640]
==== Add backup jobs (Optional not needed for dev)
NOTE: Needs to be used in an existing integreatly cluster.
NOTE: Requires an existing s3 secret s3-credentials in the backup namespace.
Sample command:
NOTE: If installing v1.5.2 or any prior release set the inventory file to inventories/hosts.template rather than inventories/pds.template as shown below
ansible-playbook \
-i inventories/pds.template \
-e 'backup_schedule="30 2 * * *"' \
-e 'backup_namespace=openshift-integreatly-backups' \
playbooks/install_backups.ymlParameters:
|===
| Variable | Description | Default
| backup_version | backup-container-image tag version | defaults to the most recent backup-container-image tag
| backup_resources_location | http url to download openshift cronjob template file(s) | https://raw.githubusercontent.com/integr8ly/backup-container-image/{{ backup_version }}/templates/openshift
| backup_image | backup image name to use (is used together with backup_version var) | quay.io/integreatly/backup-container:{{ backup_version }}
| backup_schedule | the cronjob schedule for all jobs - NOTE: always encapsulate the value in quotes, example: -e 'backup_schedule="30 2 * * *"'| 30 2 * * *
| backup_namespace | backup namespace name to add all cronjobs | openshift-integreatly-backups
|===
==== Validate installation
IMPORTANT: Once the installation has finished you will no longer be able to login via the Openshift console or oc cli as the admin if there is an sso redirect in place. The new admin user is admin@example.com password is Password1
The URL for the solution explorer is https://tutorial-web-app-webapp.apps.<domain>/
For example, if the master url is https://master.example.open.redhat.com/, the web app is available at https://tutorial-web-app-webapp.apps.example.open.redhat.com/.
image::https://user-images.githubusercontent.com/53817495/64680924-a3bfdb80-d476-11e9-801e-08f8a28c47a8.png[integr8ly WebApp]
TIP: The project https://github.com/integr8ly/tutorial-web-app[Webapp] is responsible for the solution explorer. You can find the URL looking for the router created for this project.
IMPORTANT: The default login credentials are admin@example.com / Password1
== Uninstalling Integreatly
Run the uninstall.yml playbook from the root of the repository:
NOTE: If installing v1.5.2 or any prior release set the inventory file to inventories/hosts.template rather than inventories/pds.template as shown below
== Troubleshooting
.Message "You need to install \"jmespath\" prior to running json_query filter" is shown when the installation fails
The issue means that python version used by Ansible has not this required module. In order to fix it is required to install the missing module. Following the command to install it via pip.
NOTE: The module need to be installed in the same version of python used by Ansible. Use the command $ ansible --version to check this path.
.Message "jsonpointer module is not available" is shown when the installation fails
The issue means that python version used by Ansible has not this required module. In order to fix it is required to install the missing module. Following the command to install it via pip.
Also, you might need to use the varible ansible_python_interpreter in the inventory file being used to fix it, for example:
TIP: The module need to be installed in the same version of python used by Ansible. Use the command $ ansible --version to check this path.
=== Self Signed Certs with Che If your cluster is using a self signed (non CA) certificate, there are a couple of things that needs to be noted.