From 63a86799de844b461325903d76994a84ac76a235 Mon Sep 17 00:00:00 2001 From: Mike Olund Date: Fri, 24 Mar 2017 09:22:17 -0700 Subject: [PATCH] OpenShift documentation updates --- openshift/README.md | 297 ++++++++++++++++++++++++++++++++------------ 1 file changed, 218 insertions(+), 79 deletions(-) diff --git a/openshift/README.md b/openshift/README.md index 16b6f441..46f77d96 100644 --- a/openshift/README.md +++ b/openshift/README.md @@ -1,152 +1,291 @@ -# eDivorce Environments +# A Quickstart Guide to Setting Up eDivorce on OpenShift -There are several environments set up for different purposes within OpenShift. They are available at the URLs below. +There are three deployment environments set up for different purposes within OpenShift. They are available at the URLs below. |Environment| URL |Justice URL| -|-----------|-----|-----| -|DEV|edivorce-dev.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce-dev| -|TEST|edivorce-test.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce-test| -|PROD|edivorce-prod.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce| +|-----------|-----|-----------| +|DEV|[https://edivorce-dev.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce-dev]| +|TEST|[https://edivorce-test.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce-test]| +|PROD|[https://edivorce-prod.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce]| +These instructions assume you have 4 EMPTY projects created in OpenShift: -# How to access Jenkins for eDivorce +- jag-csb-edivorce-tools (BUILD) +- jag-csb-edivorce-dev (DEV) +- jag-csb-edivorce-test (TEST) +- jag-csb-edivorce-prod (PROD) -- Login to https://edivorce-jenkins.pathfinder.gov.bc.ca with the username/password that was provided to you. - -# How to access OpenShift for eDivorce +## How to Access OpenShift for eDivorce -## Web UI +### Web UI - Login to https://console.pathfinder.gov.bc.ca:8443; you'll be prompted for GitHub authorization. You must be part of the BCDevOps Github organization, and you must have access to the eDivorce projects. -## Command-line (```oc```) tools +### Command-line (```oc```) tools - Download OpenShift [command line tools](https://github.com/openshift/origin/releases/download/v1.2.1/openshift-origin-client-tools-v1.2.1-5e723f6-mac.zip), unzip, and add ```oc``` to your PATH. - Copy command line login string from https://console.pathfinder.gov.bc.ca:8443/console/command-line. It will look like ```oc login https://console.pathfinder.gov.bc.ca:8443 --token=xtyz123xtyz123xtyz123xtyz123``` - Paste the login string into a terminal session. You are no authenticated against OpenShift and will be able to execute ```oc``` commands. ```oc -h``` provides a summary of available commands. -# Project contents - -- The "edivorce-tools" project contains the Jenkins instance and the other jsg-csb-edivorce-* projects contain different "environments". The names are self-explanatory. - -# Uploading Templates into OpenShift +## Uploading Templates into OpenShift 1. Clone the project from Github, and then ```cd``` into the openshift/templates directory. -2. Log into the OpenShift Console to get your command line token. Then log into OpenShift from the command line. - -3. Upload the templates into OpenShift with the following commands (this can also be done via the web interface) - -``` -oc create -f ../jenkins/jenkins-pipeline-persistent-template.json -n jag-csb-edivorce-tools -oc create -f edivorce-build-template.yaml -n jag-csb-edivorce-tools -oc create -f nginx-build-template.yaml -n jag-csb-edivorce-tools -oc create -f ../jenkins/pipeline.yaml -n jag-csb-edivorce-tools +2. Log into the OpenShift console to get your command line token. Then log into OpenShift from the command line. -oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-dev -oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-test -oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-prod +3. Upload the templates into OpenShift with the following commands -oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-dev -oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-test -oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-prod + Tools templates + ``` + oc create -f ../jenkins/jenkins-pipeline-persistent-template.json -n jag-csb-edivorce-tools + oc create -f edivorce-build-template.yaml -n jag-csb-edivorce-tools + oc create -f nginx-build-template.yaml -n jag-csb-edivorce-tools + oc create -f ../jenkins/pipeline.yaml -n jag-csb-edivorce-tools + ``` -``` + Main eDivorce environment template + ``` + oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-dev + oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-test + oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-prod + ``` + NGINX proxy template + ``` + oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-dev + oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-test + oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-prod + ``` -# Setting up the Tools Project +## Setting up the Tools Project -Install Docker Toolbox on your computer +### Install Docker on your computer -Open Docker QuickStart Terminal (need Docker engine started and env variables set) and build the S2I image: +### Build the S2I image: ```docker build -t s2i-nginx git://github.com/BCDevOps/s2i-nginx``` -Tag and push this image to the OpenShift Docker Registry for your OpenShift Project: +### Tag and push this image to the OpenShift Docker Registry for your OpenShift Project: -```docker tag s2i-nginx docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx``` +``` +docker tag s2i-nginx docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx -```docker login docker-registry.pathfinder.gov.bc.ca -u -p ``` +docker login docker-registry.pathfinder.gov.bc.ca -u -p -```docker push docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx``` +docker push docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx +``` (your docker token is the same as your OpenShift login token) +### Process the templates in the 'tools' project +#### These can be processed from the commandline ``` oc project jag-csb-edivorce-tools oc process jenkins-pipeline-persistent | oc create -f - oc process edivorce-build | oc create -f - oc process nginx-build | oc create -f - - ``` -Select "Add to Project" +#### For some reason the edivorce-build-pipeline template can't be processed from the command line like the other templates -On the Browse Catalog tab, type "edivorce-build-pipeline" into the filter field. Select the template. Create. -(For some reason this can't be done from the command line like the other templates) +1. Log into the web console ang go to the :"eDivorce App (tools)" project +2. Select "Add to Project" from the web interface +3. On the Browse Catalog tab, type "edivorce-build-pipeline" into the filter field. Select the template. -# Setting up Dev/Test/Prod Projects +4. Create -1. Give the dev/test/prod projects access to ImageStreams stored in the tools project +5. Delete the extra services that OpenShift automatically created when you processed the edivorce-build-template. We are using perisistent storage for Jenkins. These are ephemeral. ``` - oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-dev:default -n jag-csb-edivorce-tools - oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-dev - - oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-test:default -n jag-csb-edivorce-tools - oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-test + oc project jag-csb-edivorce-tools - oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-prod:default -n jag-csb-edivorce-tools - oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-prod + oc delete svc jenkins-pipeline-svc + oc delete deploymentconfig jenkins-pipeline-svc + oc delete route jenkins-pipeline-svc ``` -2. In the web console, go into the project you want to configure +### Add the webhook to GitHub -3. Select "Add to Project" +1. Log into the web console ang go to the :"eDivorce App (tools)" project -4. On the Browse Catalog tab, type "edivorce" into the filter field. Select the edivorce template. +2. Select Builds => Pipelines => build-and-deploy-to-dev => Configuration - You need to enter values for the following fields: - ``` - Type of environnment (dev,test or prod). - - Type the word dev, test, or prod - - Network of upstream proxy - - This is used to ensure that requests come from the Justice Proxy only. It - should be entered in IPV4 CIDR notation e.g. 10.10.15.10/16. (The actual - value you need to enter cannot be stored on Github because this would - violate BC Government Github policies. However the PROXY_NETWORK setting - is currently the same for all 3 environemts [dev/test/prod] ) - ``` +3. Copy the GitHub wookhook URL -5. Select "Add to Project" again +4. Go to the repository settings in Github, and add the webhook url under "Webhooks" +-- Payload URL = The URL you copied from OpenShift +-- Content type = application/json +-- Secret = Leave Blank +-- Just push the event +-- Active -6. On the Browse Catalog tab, type "nginx" into the filter field. Select the nginx template +## Setting up Dev/Test/Prod Projects - You need to enter values for the following fields: +### Important Configuration Options - ``` - Type of environnment (dev,test or prod). - - Type the word dev, test, or prod - ``` +#### Mandatory Settings: + +**PROXY_NETWORK:** + +Network of upstream proxy. This is used to ensure that requests come from +the Justice Proxy only. It should be entered in IPV4 CIDR notation +e.g. 10.10.15.10/16. The actual value you need to enter cannot be stored on Github +because this would violate BC Government Github policies. The PROXY_NETWORK +setting is currently the same for all 3 environments (dev, test & prod) + +#### Optional Settings you will probably want to set: -7. Weasyprint doesn't deploy itself by default. (outstanding issue). Go to Applications => Deployments => weasyprint and press the 'Deploy' button. +**BASICAUTH_ENABLED:** +Turns on simple basic authentication for test and dev environments. +This is recommended since these environments are accessible to the general public. +Set it to "True" (no quotes) to enable it. Default = False -# Data management operations +**BASICAUTH_USERNAME / BASICAUTH_PASSWORD:** -You can either use the terminal window in the OpenShift console or the ```oc rsh``` command to get to the command line on the postgresql pod. +Username will default to divorce, and password will default to a random 16 digit string +unless you override these settings + +### Setting up Dev + +Tag the builds in the tools project so they can be deployed to dev +``` +oc project jag-csb-edivorce-tools +oc tag edivorce-django:latest edivorce-django:deploy-to-dev +oc tag nginx-proxy:latest nginx-proxy:deploy-to-dev +``` + +Give the dev project access to Docker images stored in the tools project +``` +oc project jag-csb-edivorce-dev +oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-dev:default -n jag-csb-edivorce-tools +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-dev +``` + +Deploy the Django app and the Postgresql DB +``` +oc process edivorce -v ENVIRONMENT_TYPE=dev,PROXY_NETWORK=123.45.67.89/0,BASICAUTH_ENABLED=True | oc create -f - +``` + +Deploy the NGINX proxy +``` +oc process nginx -v ENVIRONMENT_TYPE=dev | oc create -f - +``` + +Deploy Weasyprint +``` +oc deploy weasyprint --latest +``` + +Give the Jenkins build pipeline access to the dev project +``` +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-dev +``` + + +### Setting up Test + +Tag the builds in the tools project so they can be deployed to test +``` +oc project jag-csb-edivorce-tools +oc tag edivorce-django:latest edivorce-django:deploy-to-test +oc tag nginx-proxy:latest nginx-proxy:deploy-to-test +``` + +Give the test project access to Docker images stored in the tools project +``` +oc project jag-csb-edivorce-test +oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-test:default -n jag-csb-edivorce-tools +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-test +``` + +Deploy the Django app and the Postgresql DB +``` +oc process edivorce -v ENVIRONMENT_TYPE=test,PROXY_NETWORK=123.45.67.89/0,BASICAUTH_ENABLED=True | oc create -f - +``` + +Deploy the NGINX proxy +``` +oc process nginx -v ENVIRONMENT_TYPE=test | oc create -f - +``` + +Deploy Weasyprint +``` +oc deploy weasyprint --latest +``` + +Give the Jenkins build pipeline access to the test project +``` +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-test +``` + +### Setting up Prod + +Tag the builds in the tools project so they can be deployed to prod +``` +oc project jag-csb-edivorce-tools +oc tag edivorce-django:latest edivorce-django:deploy-to-prod +oc tag nginx-proxy:latest nginx-proxy:deploy-to-prod +``` + +Give the prod project access to Docker images stored in the tools project +``` +oc project jag-csb-edivorce-prod +oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-prod:default -n jag-csb-edivorce-tools +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-prod +``` + +Deploy the Django app and the Postgresql DB +``` +oc process edivorce -v ENVIRONMENT_TYPE=prod,PROXY_NETWORK=123.45.67.89/0 | oc create -f - +``` + +Deploy the NGINX proxy +``` +oc process nginx -v ENVIRONMENT_TYPE=prod | oc create -f - +``` + +Deploy weasyprint +``` +oc deploy weasyprint --latest +``` + +Give the Jenkins build pipeline access to the prod project +``` +oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-prod +``` + + +## Data management operations + +If you need to access the DB, you can either use the terminal window in the OpenShift console or the ```oc rsh``` +command to get to the command line on the postgresql pod. + +### You can find the current name of the postgresql pod in the web console + +The pod identifiers change with every deployment, you need to find the current one ``` oc rsh postgresql-2-qp0oh +``` + +### Sample postgresql terminal session +``` psql -d default \dt +select count(*) from core_bceiduser; + \q + +exit ``` - ** the pod identifiers change regularly, you need to find the current one + +## How to access Jenkins for eDivorce + +- Login to https://edivorce-jenkins.pathfinder.gov.bc.ca with the username/password that was provided to you.