From 3b21d16fe71343a6be10c16689adbc865cd124c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20Mass=C3=A9?= Date: Mon, 12 Jun 2017 18:43:56 +0200 Subject: [PATCH] rewrite doc --- README.md | 138 ++---------------------------------- doc/CONFIGURE_JENKINS.md | 75 ++++++++++++++++++++ doc/INSTALL.md | 146 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 227 insertions(+), 132 deletions(-) create mode 100644 doc/CONFIGURE_JENKINS.md create mode 100644 doc/INSTALL.md diff --git a/README.md b/README.md index 7819504..4c7f270 100644 --- a/README.md +++ b/README.md @@ -6,144 +6,18 @@ TODO ## Setup -### Dev environment +### In a DEV environment +To deploy the app : ``` oc new-app nodejs~https://github.com/nmasse-itix/OpenShift-Demo-NodeJS.git --strategy=source ``` -### Full CICD Deployment - -#### Prepare OpenShift - -Create the four environments : -``` -oc new-project demo-dev -oc new-project demo-build -oc new-project demo-test -oc new-project demo-prod -``` - -Create the build config in the build environment : -``` -oc new-build -n demo-build nodejs~https://github.com/nmasse-itix/OpenShift-Demo-NodeJS.git --strategy=source --name=openshift-demo-nodejs -``` - -You can test the build config with : -``` -oc start-build -n demo-build openshift-demo-nodejs --env=NPM_PACKAGE_TO_INSTALL=openshift-demo-nodejs-nmasse@0.1.0 -``` - -Deploy a Jenkins in the build project : -``` -oc new-app -n demo-build --template=jenkins-persistent --name=jenkins -``` - -Give admin role to the jenkins service account on subsequent environments : -``` -oc adm policy add-role-to-user admin system:serviceaccount:demo-build:jenkins -n demo-test -oc adm policy add-role-to-user admin system:serviceaccount:demo-build:jenkins -n demo-prod -``` - -Give rights on other environments to pull images from build environment : -``` -oc adm policy add-role-to-group system:image-puller system:serviceaccounts:demo-test -n demo-build -oc adm policy add-role-to-group system:image-puller system:serviceaccounts:demo-prod -n demo-build -``` - -Tag the test image : -``` -oc tag demo-build/openshift-demo-nodejs:latest openshift-demo-nodejs:ready-for-testing -n demo-test -``` - -Create the test application : -``` -oc new-app demo-build/openshift-demo-nodejs:ready-for-testing --name openshift-demo-nodejs -n demo-test -oc expose service openshift-demo-nodejs --name=openshift-demo-nodejs --hostname=demo.test.app.openshift.test -n demo-test -``` - -Tag the prod image : -``` -oc tag demo-test/openshift-demo-nodejs:ready-for-testing openshift-demo-nodejs:ready-for-prod -n demo-prod -``` - -Create the prod application (blue) : -``` -oc new-app demo-build/openshift-demo-nodejs:ready-for-prod --name openshift-demo-nodejs-blue -n demo-prod -l color=blue -``` - -Create the prod application (green) : -``` -oc new-app demo-build/openshift-demo-nodejs:ready-for-prod --name openshift-demo-nodejs-green -n demo-prod -l color=green -``` - -Create a service on selector "color" : -``` -oc create -n demo-prod -f - < - - Password: \ - - ID: npm-secret - -Create a Jenkins Pipeline that accepts the following parameters : - -| Parameter Name | Parameter Type | Default Value | Description | -| --- | --- | --- | --- | -| NPM_CREDENTIALS_ID | String | npm-secret | The Jenkins Credentials ID that holds login and password to login on NPM Registry | -| NPM_EMAIL | String | \ | The email address associated with the NPM Account pointed by NPM_CREDENTIALS_ID | -| NPM_REGISTRY | String | https://registry.npmjs.org | Private NPM registry to log in to (Default if not provided: https://registry.npmjs.org) | -| OPENSHIFT_IMAGE_STREAM | String | openshift-demo-nodejs | The ImageStream name to use to tag the built images | -| OPENSHIFT_BUILD_CONFIG | String | openshift-demo-nodejs | The BuildConfig name to use | -| OPENSHIFT_SERVICE | String | openshift-demo-nodejs | The Service object to update (either green or blue) | -| OPENSHIFT_DEPLOYMENT_CONFIG | String | openshift-demo-nodejs | The DeploymentConfig name to use | -| OPENSHIFT_BUILD_PROJECT | String | demo-build | The OpenShift project in which builds are run | -| OPENSHIFT_TEST_ENVIRONMENT | String | demo-test | The OpenShift project in which we will deploy the test version | -| OPENSHIFT_PROD_ENVIRONMENT | String | demo-prod | The OpenShift project in which we will deploy the prod version | -| OPENSHIFT_TEST_URL | String | http://demo.test.app.openshift.test | The App URL in the test environment (to run the integration tests) | +### Full CICD Deployment -Pick the pipeline from GIT using the option "Pipeline script from SCM". +See [INSTALL](doc/INSTALL.md). diff --git a/doc/CONFIGURE_JENKINS.md b/doc/CONFIGURE_JENKINS.md new file mode 100644 index 0000000..427f612 --- /dev/null +++ b/doc/CONFIGURE_JENKINS.md @@ -0,0 +1,75 @@ +# Configure Jenkins + +## Create a Credentials named `npm-secret` + +Login to Jenkins with your OpenShift credentials and create a Jenkins Credentials with the following parameters : + - Scope: global + - Kind: Username with password + - Username: \ + - Password: \ + - ID: npm-secret + +To create a Jenkins Credentials : + 1. Login to the Jenkins admin interface + 2. In the left side menu, click `Credentials`, then `System` + 3. Click `Global credentials` + 4. In the left side menu, click `Add Credentials` + 5. Fill-in the form + 6. Click `OK` + +## Install plugins + +Install the two following Jenkins plugins : + - [Pipeline Utility Steps](https://plugins.jenkins.io/pipeline-utility-steps) + - [Credentials Binding](https://plugins.jenkins.io/credentials-binding) + +Note: the `Pipeline Utility Steps` plugin might already be installed. In such case, make sure the latest version is installed. + +Quick reminder to install a plugin : + 1. Login to the Jenkins admin interface + 2. In the left side menu, click `Manage Jenkins` + 3. Click `Manage Plugins` + 4. Select the `Available` tab + 5. Search for the plugin to install + 6. Check the box next to the plugin to install + 7. Click `Download now and install after restart` + 8. Do not forget to check the box `Restart Jenkins` + +Note: to update a plugin, select the `Updates` tab instead of the `Available` tab. + +## Create the Jenkins Pipeline + +Depending if you created a JenkinsPipeline BuildConfig, OpenShift may have created +a Jenkins pipeline for you. In such a case, the Jenkins Pipeline is named `\/\`. + +So, if you installed the demo : + - manually, you need to create the pipeline from scratch + - automatically, you need to update the pipeline to add the following parameters + +Note: As of today, OpenShift does not accept build environment variables with Jenkins pipelines. +So you have to update the Jenkins pipeline created by OpenShift to add those variable. +In the next version this may change as there is a pull request for this feature +(see [\#11293](https://github.com/openshift/origin/issues/11293) +and [\#12323](https://github.com/openshift/origin/pull/12323)). + +So, create or update a Jenkins Pipeline that accepts the following parameters : + +| Parameter Name | Parameter Type | Default Value | Description | +| --- | --- | --- | --- | +| NPM_CREDENTIALS_ID | String | npm-secret | The Jenkins Credentials ID that holds login and password to login on NPM Registry | +| NPM_EMAIL | String | \ | The email address associated with the NPM Account pointed by NPM_CREDENTIALS_ID | +| NPM_REGISTRY | String | https://registry.npmjs.org | Private NPM registry to log in to (Default if not provided: https://registry.npmjs.org) | +| OPENSHIFT_IMAGE_STREAM | String | openshift-demo-nodejs | The ImageStream name to use to tag the built images | +| OPENSHIFT_BUILD_CONFIG | String | openshift-demo-nodejs | The BuildConfig name to use | +| OPENSHIFT_SERVICE | String | openshift-demo-nodejs | The Service object to update (either green or blue) | +| OPENSHIFT_DEPLOYMENT_CONFIG | String | openshift-demo-nodejs | The DeploymentConfig name to use | +| OPENSHIFT_BUILD_PROJECT | String | demo-build | The OpenShift project in which builds are run | +| OPENSHIFT_TEST_ENVIRONMENT | String | demo-test | The OpenShift project in which we will deploy the test version | +| OPENSHIFT_PROD_ENVIRONMENT | String | demo-prod | The OpenShift project in which we will deploy the prod version | +| OPENSHIFT_TEST_URL | String | http://demo.test.app.openshift.test | The App URL in the test environment (to run the integration tests) | + +Pick the pipeline from GIT using the option "Pipeline script from SCM" and the following parameters : + - SCM: GIT + - Script Path: Jenkinsfile + - Repository URL: https://github.com/nmasse-itix/OpenShift-Demo-NodeJS.git + - Branch Specifier: */master diff --git a/doc/INSTALL.md b/doc/INSTALL.md new file mode 100644 index 0000000..2390c11 --- /dev/null +++ b/doc/INSTALL.md @@ -0,0 +1,146 @@ +# Full CICD Setup + +## Automated setup through Templates + +Create the four environments : +``` +oc new-project demo-dev +oc new-project demo-build +oc new-project demo-test +oc new-project demo-prod +``` + +Deploy a Jenkins in the build project : +``` +oc new-app -n demo-build --template=jenkins-persistent --name=jenkins -p MEMORY_LIMIT=1Gi +``` + +Create all other objects using the template : +``` +oc process -f setup/all-in-one-template.yaml > objects.json +oc create -f objects.json +``` + +Then, configure Jenkins [as described here](doc/CONFIGURE_JENKINS.md). + +Where parameters are : +| Parameter Name | Required ? | Default Value | Description | +| --- | --- | --- | --- | +| DEV_PROJECT | No | demo-dev | TODO | +| BUILD_PROJECT | No | demo-build | TODO | +| TEST_PROJECT | No | demo-test | TODO | +| PROD_PROJECT | No | demo-prod | TODO | + + +## Manual Setup + +### Prepare OpenShift + +Create the four environments : +``` +oc new-project demo-dev +oc new-project demo-build +oc new-project demo-test +oc new-project demo-prod +``` + +Create the build config in the build environment : +``` +oc new-build -n demo-build nodejs~https://github.com/nmasse-itix/OpenShift-Demo-NodeJS.git --strategy=source --name=openshift-demo-nodejs +``` + +You can test the build config with : +``` +oc start-build -n demo-build openshift-demo-nodejs --env=NPM_PACKAGE_TO_INSTALL=openshift-demo-nodejs-nmasse@0.1.0 +``` + +Deploy a Jenkins in the build project : +``` +oc new-app -n demo-build --template=jenkins-persistent --name=jenkins -p MEMORY_LIMIT=1Gi +``` + +Give admin role to the jenkins service account on subsequent environments : +``` +oc adm policy add-role-to-user admin system:serviceaccount:demo-build:jenkins -n demo-test +oc adm policy add-role-to-user admin system:serviceaccount:demo-build:jenkins -n demo-prod +``` + +Give rights on other environments to pull images from build environment : +``` +oc adm policy add-role-to-group system:image-puller system:serviceaccounts:demo-test -n demo-build +oc adm policy add-role-to-group system:image-puller system:serviceaccounts:demo-prod -n demo-build +``` + +Tag the test image : +``` +oc tag demo-build/openshift-demo-nodejs:latest openshift-demo-nodejs:ready-for-testing -n demo-test +``` + +Create the test application : +``` +oc new-app demo-build/openshift-demo-nodejs:ready-for-testing --name openshift-demo-nodejs -n demo-test +oc expose service openshift-demo-nodejs --name=openshift-demo-nodejs --hostname=demo.test.app.openshift.test -n demo-test +``` + +Tag the prod image : +``` +oc tag demo-test/openshift-demo-nodejs:ready-for-testing openshift-demo-nodejs:ready-for-prod -n demo-prod +``` + +Create the prod application (blue) : +``` +oc new-app demo-build/openshift-demo-nodejs:ready-for-prod --name openshift-demo-nodejs-blue -n demo-prod -l color=blue +``` + +Create the prod application (green) : +``` +oc new-app demo-build/openshift-demo-nodejs:ready-for-prod --name openshift-demo-nodejs-green -n demo-prod -l color=green +``` + +Create a service on selector "color" : +``` +oc create -n demo-prod -f - <