Attack of the Pipelines

In this lab we will explore the sample TODO List application and create a pipeline in Jenkins to build and deploy our code.

Learning Outcomes

As a learner by the end of this lesson you will be able to

• Build and run the full stack of the TODO List application locally
• Create an un-gated pipeline using the Jenkins UI for the backend and frontend
• Add branching to the pipeline to target specific namespace

Tools and Frameworks

The following tools are used throughout this exercise. Familiarity with them is not required but knowing what they are may help!

1. Jenkins - OpenSource build automation server; highly customisable through plugins
2. NodeJS - Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. Node.js' package ecosystem, npm, is the largest ecosystem of open source libraries in the world.
3. MongoDB - MongoDB stores data in flexible, JSON-like documents, meaning fields can vary from document to document and data structure can be changed over time
4. VueJS - Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. It is designed from the ground up to be incrementally adoptable, and can easily scale between a library and a framework depending on different use cases. It consists of an approachable core library that focuses on the view layer only, and an ecosystem of supporting libraries that helps you tackle complexity in large Single-Page Applications.

Big Picture

From the previous exercise; we created some supporting tooling needed by our app/

10,000 Ft View

This lab requires users to take the sample TODO app and create a build pipeline in Jenkins by clicking your way to success ending up with an app deployed to each of the namespaces created previously

1. Import the projects into your gitlab instance. See README of each for build instructions

2. Deploy a MongoDB using the provided template to all project namespace.

3. Create 2 pipline with three stages (build, bake, deploy) in jenkins for develop & master branches on the todolist-fe such that:

   • a Build job is responsible for compiling and packaging our code:
     1. Checkout from source code (develop for <yourname>-dev & master for <yourname>-test)
     2. Install node dependencies and run a build / package
     3. Send the package to Nexus
     4. Archive the workspace to persist the workspace in case of failure
     5. Tag the GitLab repository with the ${JOB_NAME}.${BUILD_NUMBER} from Jenkins. This is our ${BUILD_TAG} which will be used on downstream jobs.
     6. Trigger the bake job with the ${BUILD_TAG} param
   • a Bake job should take the package and put it in a Linux Container
     1. Take an input of the previous jobs ${BUILD_TAG} ie ${JOB_NAME}.${BUILD_NUMBER}.
     2. Checkout the binary from Nexus and unzip it's contents
     3. Run an oc start-build of the App's BuildConfig and tag it's imagestream with the provided ${BUILD_TAG}
     4. Trigger a deploy job using the parameter ${BUILD_TAG}
   • a deploy job should roll out the changes by updating the image tag in the DC:
     1. Take an input of the ${BUILD_TAG}
     2. Patch / set the DeploymentConfig to the image's ${BUILD_TAG}
     3. Rollout the changes
     4. Verify the deployment

4. Repeat the above setup for the backend todolist-fe. TIP - use the copy config to speed things up!

5. Verify that both apps and the DB are talking to one another as expected.

Step by Step Instructions

This is a fairly structured guide with references to exact filenames and sections of text to be added.

Part 1 - Explore the Sample App

In this part of the exercise we will explore the sample application, become familiar with it locally before building and deploying in OCP Land

1. Git clone the todolist-fe project to somewhere sensible and checkout the develop branch.
   bash $ git clone https://github.com/springdo/todolist-fe.git $ git checkout develop

2. Create a new project (internal) in GitLab called todolist-fe to host your clone of the project and copy it's remote address.

3. In your local clone of the todolist-fe, remove the origin and add the GitLab origin by replacing <YOUR_GIT_LAB_PROJECT>. Push your app to GitLab
   bash $ git remote remove origin $ git remote add origin <YOUR_GIT_LAB_PROJECT> $ git push -u origin --all

4. To get the app running locally; first check you've got node and npm installed
   bash $ node -v $ npm -v
   

   
   NOTE - If you are missing these dependencies; install them with ease using the Node Version Manager
   

   
   

5. The todolist-fe has a package.json at the root of the project, this defines some configuration for the app including it's dependencies, dev dependencies, scripts and other configuration. Install the apps dependencies
   bash $ npm install

6. The todolist-fe has some scripts defined in the package.json at the root of the project. To run any of these scripts run npm run <SCRIPT_NAME>. Let's start by serving our application
   
   bash npm run serve

7. This will take sometime to execute; but once done it should open the browser for you displaying the todolist-fe app.
   

   • The server hosting it live reloads; so as you make changes to your code; the app will live update
   • The Data you see in the screen is dummy / stubbed data. This is served up when there is no backend connection found

8. The app is a todolist manager built in Vue.js. Play around with the App. You will notice when you add todos they appear and clear as expected. If you refresh the page you'll loose all additions. This is because there is persistence

9. The structure of the todolist-fe is as follows.
   bash todolist-fe ├── jest.config.js ├── jsconfig.json ├── nightwatch.config.js ├── node_modules ├── package.json ├── public │   ├── favicon.ico │   ├── img │   ├── index.html │   └── manifest.json ├── src │   ├── App.vue │   ├── assets │   ├── components │   ├── config │   ├── main.js │   ├── registerServiceWorker.js │   ├── router.js │   ├── scss │   ├── services │   ├── store │   └── views ├── tests │   ├── e2e │   └── unit └── vue.config.js
   where the following are the important things:

   • ./src is the main collection of files needed by the app. The entrypoint is the main.js which is used to load the root App.vue file.
   • ./node_modules is where the dependencies are stored
   • ./test contains our end-to-end tests and unit tests. More covered on these in later labs.
   • ./src/components contains small, lightweight reusable components for our app. These include the NewTodo component which encapsulates the styling, logic and data for adding a new todo to our list
   • ./src/store is the vuex files for managing application state and backend connectivity
   • ./src/views is the view containers; which are responsible for loading components and managing their interactions.
   • the ./src/router.js controls routing logic. In our case the app only has one real endpoint.
   • ./src/scss contains custom SCSS used in the application.
   • ./*.js is mostly config files for running and managing the app and the tests

10. Now let's move on to the todolist-api and wire them together. As with the todolist-fe we need to clone the repo and add it to our GitLab in the cluster.
    bash $ git clone https://github.com/springdo/todolist-api.git $ git checkout develop

11. Create a new project (internal) in GitLab called todolist-api to host your clone of the project and copy it's remote address.

12. In your local clone of the todolist-api, remove the origin and add the GitLab origin by replacing <YOUR_GIT_LAB_PROJECT>. Push your app to GitLab
    bash $ git remote remove origin $ git remote add origin <YOUR_GIT_LAB_PROJECT> $ git push -u origin --all

13. Once pushed; explore the application. It is a NodeJS application with the Express.js framework and MongoDB for persistent storage. Same as before, the package.json defines most of the configuration etc. Install the dependencies
    bash $ npm i

14. While the dependencies are being installed; explore the project structure.
    bash todolist-api ├── Dockerfile ├── Gruntfile.js ├── README.md ├── node_modules ├── package-lock.json ├── package.json ├── server │   ├── api │   │   └── todo │   ├── app.js │   ├── components │   │   └── errors │   ├── config │   │   ├── environment │   │   ├── express.js │   │   ├── local.env.sample.js │   │   └── seed.js │   ├── mocks │   │   ├── mock-routes-config.json │   │   ├── mock-routes.js │   │   └── mock-routes.spec.js │   ├── routes.js │   └── views │   └── 404.html └── tasks └── perf-test.js
    where the following are the important things:

    • ./server is the main collection of files needed by the app. The entrypoint is the app.js
    • ./node_modules is where the dependencies are stored
    • ./server/api is where the api's controller, data model & unit test are stored.
    • ./server/mocks is a mock server used for when there is no DB access
    • ./server/config stores our Express JS config, header information and other middlewear.
    • ./server/config/environment stores enviromnent specific config; such as connectivity to backend services like the MongoDB.
    • ./tasks is a collection of additional Grunt tasks which will be used in later labs
    • package.json contains the dependency list and a lot of very helpful scripts for managing the app lifecycle

15. The npm scripts are shown below. There are application start scripts, build and test items which will be used in the build. The ones for MongoDB are just provided for convenience and require Docker installed to execute.
    json "scripts": { "start": "node server/app.js", "dev": "./node_modules/.bin/grunt serve", "jshint": "./node_modules/.bin/grunt jshint", "jshint:ci": "./node_modules/.bin/grunt jshint:ci_server", "clean": "rm -rf reports package-contents*", "build": "mkdir -p package-contents && cp -vr server Dockerfile package.json package-contents", "package": "zip -r package-contents.zip package-contents", "test": "node_modules/.bin/nyc node_modules/.bin/mocha server/**/*.spec.js --exit", "test:ci": "export MOCHA_FILE='reports/server/mocha/test-results.xml' && export NODE_ENV=ci && node_modules/.bin/nyc node_modules/.bin/mocha server/**/*.spec.js -R mocha-junit-reporter --exit", "mongo" : "docker run -i -d --name mongo-local -p 27017:27017 mongo", "mongo:drop" : "npm run mongo:stop && docker rm mongo-local", "mongo:stop" : "docker stop mongo-local", "mongo:start" : "docker start mongo-local" },

16. To run the application; start a new instance of the MongoDB by running.
    bash $ npm run mongo
    

    
    npm run mongo:drop is used to completely remove the running container. npm run mongo:stop & npm run mongo:start will preserve data in the container
    

17. Fire up the todolist-api by running.
    bash $ npm run start
    

18. Check things are responding correctly by running and checking the response. It contains some seeded data (stored in server/config/seed.js)
    bash $ curl localhost:9000/api/todos
json [{ "_id": "5ac8ff1fdfafb02138698948", "title": "Learn some stuff about MongoDB", "completed": false, "__v": 0 }, { "_id": "5ac8ff1fdfafb02138698949", "title": "Play with NodeJS", "completed": true, "__v": 0 }]

19. Now let's check out todolist-fe app by reloading the browser. We should now see our dummy front end data is replaced by the backend seed data
    

Part 2 - Create a NodeJS Build slave

In this exercise; we will create a build configuration to generate a slave for Jenkins to use in it's builds

1. In order for Jenkins to be able to run npm builds and installs as we have done locally, we must configure a jenkins-build-slave for Jenkins to use. This slave will be dynamically provisioned when we run a build. It needs to have NodeJS and npm installed in it. In your enablement-cd-cd repository, checkout the template and configuration. This will bring in the template, the params & the Dockerfile.
   bash $ git checkout exercise2/jenkins-slave docker/ templates/ params/

2. Open the params/jenkins-slave-npm file and update <YOUR_ENABLEMENT_GIT_REPO> accordingly. This set of parameters will clone from the enablement repo and run a docker build of the Dockerfile stored in docker/jenkins-slave-npm.
   bash SOURCE_REPOSITORY_URL=<YOUR_ENABLEMENT_GIT_REPO> SOURCE_CONTEXT_DIR=docker/jenkins-slave-npm NAME=npm-jenkins-slave

3. Create an item in the ansible variables file under the ci-cd-builds object to run the template with. Don't forget to substitute <YOUR_NAME>
   ```yaml

• name: "jenkins-npm-slave"
  namespace: "-ci-cd"
  template: "{{ inventory_dir }}/../templates/jenkins-slave-generic-template.yml"
  params: "{{ inventory_dir }}/../params/jenkins-slave-npm"
  tags:
  • jenkins-slave
    ```
    

1. Run the OpenShift Applier to trigger a build of this jenkins slave image.
   bash $ ansible-playbook roles/openshift-applier/playbooks/openshift-cluster-seed.yml \ -i inventory/ \ -e "filter_tags=jenkins-slave"

2. Verify the build executed successfully by logging into the cluster and checking the builds tab of the <YOUR_NAME>-ci-cd project.
   

3. You should now be able to apply the label jenkins-slave-npm to a build job to run a build on this newly created slave as we will see in the rest of this lab
   

   
   NOTE - Jenkins may need to be restarted for the configuration to appear. To do this; navigate to your jenkins instance and add /restart to the url.
   

Part 3 - Add configs to cluster

In this exercise; we will use the OpenShift Applier to drive the creation of cluster content required by the app such and MongoDB and the Apps Build / Deploy Config

1. TODO - waiting for Justins example before proceeding here

Part 4 - Build > Bake > Deploy

In this exercise; we take what we have working locally and get it working in OpenShift

This exercise will involve creating three stages (or items) in our pipeline, each of these is detailed below at a very high level. Move on to the next step to begin implementation.
* a build job is responsible for compiling and packaging our code:
1. Checkout from source code (develop for <yourname>-dev & master for <yourname>-test)
2. Install node dependencies and run a build / package
3. Send the package to Nexus
4. Archive the workspace to persist the workspace in case of failure
4. Tag the GitLab repository with the ${JOB_NAME}.${BUILD_NUMBER} from Jenkins. This is our ${BUILD_TAG} which will be used on downstream jobs.
5. Trigger the bake job with the ${BUILD_TAG} param
* a bake job should take the package and put it in a Linux Container
1. Take an input of the previous jobs ${BUILD_TAG} ie ${JOB_NAME}.${BUILD_NUMBER}.
2. Checkout the binary from Nexus and unzip it's contents
3. Run an oc start-build of the App's BuildConfig and tag it's imagestream with the provided ${BUILD_TAG}
4. Trigger a deploy job using the parameter ${BUILD_TAG}
* a deploy job should roll out the changes by updating the image tag in the DC:
1. Take an input of the ${BUILD_TAG}
2. Patch / set the DeploymentConfig to the image's ${BUILD_TAG}
3. Rollout the changes
4. Verify the deployment
* We will now go through these steps in detail.

Part 4a - Build

1. With the BuildConfig and DeployConfig in place from previous steps; Log into Jenkins and create a New Item which is jenkins speak for a new job configuration.

2. Name this job dev-todolist-fe-build and select Freestyle Job. All our jobs will take the form of <ENV>-<APP_NAME>-<JOB_PURPOSE>.

3. The page that loads is the Job Configuration page. It can be returned to at anytime from Jenkins. To conserve space; we will make sure Jenkins only keeps the last builds artifacts. Tick the Discard old builds checkbox and set Max # of builds to keep with artifacts to 1 as below

4. Our NodeJS build needs to be run on the jenkins-slave-npm we created earlier. Specify this in the box labelled Restrict where this project can be run

5. On the Source Code Management tab, specify the endpoint for our GitLab todolist-fe Project and specify your credentials from the dropdown box. Set the Branch Specifier to develop.

6. Scroll down to the Build Environment tab and select the Color ANSI Console Output checkbox

7. Move on to the Build section and select Add build step. From the dropdown select Execute Shell. On the box that appears; insert the following, to build package and deploy our app to Nexus:
   bash #!/bin/bash set -o xtrace scl enable rh-nodejs8 'npm install' scl enable rh-nodejs8 'npm run build:ci:dev' scl enable rh-nodejs8 'npm run package' scl enable rh-nodejs8 'npm run publish'
   

8. Scroll to the final section; the Post-build Actions. Add a new post-build action from the dropdown called Archive the artifacts and specify ** in the box. This will zip the entire workspace and copy it back to Jenkins for inspection if needed.

9. On the Post-build Actions; Add another post-build action from the dropdown called Git Publisher. This is useful for tying the git check-in to the feature in your tracking tool to the built product.

   • Tick the box Push Only If Build Succeeds
   • Add the Tag to push of
     bash ${JOB_NAME}.${BUILD_NUMBER}
   • Specify the commit message to be
     bash Automated commit by jenkins from ${JOB_NAME}.${BUILD_NUMBER}
     

10. Finally; add the trigger for the next job in the pipeline. Add another post-build action from the dropdown called Trigger parameterized build on other projects.

    • Set the project to build to be dev-todolist-fe-bake
    • Set the condition to be Stable or unstable but not failed.
    • Click Add Parameters dropdown and select Predefined parameters.
    • In the box, insert our BUILD_TAG as follows
      bash BUILD_TAG=${JOB_NAME}.${BUILD_NUMBER}
      
      

      
      NOTE - Jenkins might say "No such project ‘dev-todolist-fe-bake’. Did you mean ...." at this point. Don't worry; it's because we have not created the next job yet.
      

11. Hit save which will take you to the job overview page - and that's it; our build phase is complete!

Part 4b - Bake

1. Next we will setup our bake phase; which is a little simpler. Go to Jenkins home and create another Freestyle Job (as before) called dev-todolist-fe-bake.

2. This job is will take in the BUILD_TAG from the previous one so check the This project is parameterized box on the General tab.

   • Add string parameter type
   • set the name to BUILD_TAG. This will be available to the job as an Enviroment Variable.
   • You can set dev-todolist-fe-build. as the default value for ease when triggering manually.
   • The description is not required but a handy one for reference would be ${JOB_NAME}.${BUILD_NUMBER} of previous build eg dev-todolist-fe-build.1232
     

3. This time set the Restrict where this project can be run label to master.
   

   
   This the default node that jobs run on. We don't want jenkins to execute the bake on any other nodes if the master is busy so it is always safer to specify it here.
   

4. There is no Git or SCM needed for this job so move down to the Build Environment and tick Delete workspace before build starts

5. Scroll down to the Build Environment tab and select the Color ANSI Console Output checkbox

6. Move on to the Build section and select Add build step. From the dropdown select Execute Shell. On the box the appears; insert the following, to pull the package from Nexus. We patch the BuildConfig with the Jenkins Tag to get traceablility from feature to source code to built item. Finally; the oc start-build command is run:
   bash #!/bin/bash curl -v -f http://admin:admin123@${NEXUS_SERVICE_HOST}:${NEXUS_SERVICE_PORT}/repository/zip/com/redhat/todolist/${BUILD_TAG}/package-contents.zip -o package-contents.zip unzip package-contents.zip oc project <YOUR_NAME>-ci-cd # probs not needed NAME=todolist-fe oc patch bc ${NAME} -p "spec: output: to: kind: ImageStreamTag name: '${NAME}:${BUILD_TAG}'" oc start-build ${NAME} --from-dir=package-contents/ --follow
   

7. Finally; add the trigger for the next job in the pipeline. Add a post-build action from the dropdown called Trigger parameterized build on other projects.

   • Set the project to build to be dev-todolist-fe-deploy
   • Set the condition to be Stable.
   • Click Add Parameters dropdown and select Current build parameters. This will pass the ${BUILD_TAG} to the downstream job which we will create next.
   • In the box, insert our BUILD_TAG as follows
     

8. Hit save! That's our bake phase done! Finally; on to our deploy

Part 4c - Deploy

1. Next we will setup our deploy phase. This job is very similar in setup to the bake phase so this time go to Jenkins home and create dev-todolist-fe-deploy Job and but scroll to the bottom and Copy from dev-todolist-fe-bake.
   

2. The only two differences between the jobs is the Build Step and there are no Post Build Actions. First to the Build tab and add the following to the shell box. The process for running the deploy is to tag the image created previously for use in the dev project. Then update the DeploymentConfig to use the Jenkins Tag which kicked the process off. Once successful; the changes are rolled out
   bash #!/bin/bash set -o xtrace # VARS PIPELINES_NAMESPACE=donal-ci-cd NAMESPACE=donal-dev NAME=todolist-fe oc project ${NAMESPACE} oc tag ${PIPELINES_NAMESPACE}/${NAME}:${BUILD_TAG} ${NAMESPACE}/${NAME}:${BUILD_TAG} oc set env dc ${NAME} NODE_ENV=dev oc set image dc/${NAME} ${NAME}=docker-registry.default.svc:5000/${NAMESPACE}/${NAME}:${BUILD_TAG} oc rollout latest dc/${NAME}
   

3. Secondly, add another build step called Verify OpenShift Deployment include the following

   • Set the Project to your <YOUR_NAME>-dev
   • Set the DeploymentConfig to your app's name todolist-fe
   • Set the replica count to 1
     

4. Finally; delete the Post Build Action to trigger another job (by hitting the red X). Save the configuration. We're almost ready to run the pipeline!

Part 4d - Pipeline

1. With our Jenkins setup in place; now move to our todolist-fe app. Open in it your favourite editor and navigate to src/config/dev.js. Update <YOUR_NAME> accordingly. For example:
   

2. Repeat this for src/config/test.js file. Once done; commit your chanages and push them to GitLab
   bash $ git add . $ git commit -m "ADD config for api" $ git push

3. Back on Jenkins; can tie all the jobs in the pipeline together into a nice single view using the Build Pipeline view. Back on the Jenkins home screen Click the + beside the all tab on the top. Give the new view a sensible name like dev-todolist-fe-pipeline
   .

4. Set the Pipeline Flow's Inital Job to dev-todolist-fe-build and save.
   

5. You should now see the pipeline view. Run the pipeline by hitting build (you can move onto the next part while it is running as it may take some time).
   

Part 5 - Backend Pipeline

In this exercise we will use the Jobs created for the todolist-fe as a template to create a pipeline for the todolist-api app

1. On Jenkins home; create a new job for our backend build called dev-todolist-api-build. Use the Copy from section to copy all the configuration from the dev-todolist-fe-build.
   

2. When this has loaded; find and replace both occurrences -fe with -api within the Job's configuration. Places to make sure you check are:

   • The GitLab project URL
   • Projects to build on the Post Build Action

3. On the Build tab; remove the :dev from the npm run build:ci:dev so it just reads.
   bash scl enable rh-nodejs8 'npm run build:ci'
   The rest of the instructions can be left as they are.

4. Save the configuration for dev-todolist-api-build

5. On Jenkins home; create a new job for our backend build called dev-todolist-api-bake. Use the Copy from section to copy all the configuration from the dev-todolist-fe-bake as you've just done.

6. When this has loaded; find and replace the occurrences -fe with -api within the Job's configuration. Places to make sure you check are:

   • The BUILD_TAG default value and description
   • NAME in the execute shell step
   • Projects to build on the Post Build Action

7. Save the configuration for dev-todolist-api-build

8. On Jenkins home; create a new job for our backend build called dev-todolist-api-deploy. Use the Copy from section to copy all the configuration from the dev-todolist-fe-deploy as you've just done.

9. When this has loaded; find and replace the occurrences -fe with -api within the Job's configuration. Places to make sure you check are:

   • The BUILD_TAG default value and description
   • NAME in the execute shell step
   • The name of the DeploymentConfig to validate in the Verify OpenShift Deployment

10. Save the configuration for dev-todolist-api-build and that's it for wiring together our todolist-api pipeline.

11. Before we kick off the build; check our front end app and see if it has deployed successfully. Check the deployment in OpenShift and load the url. If it has been a success we should see our dummyData. This is because there is not backend deployed.
    

12. Run the dev-todolist-api-build to trigger the backend pipeline. When complete we should see the sample data has changed
    

Extension Tasks

Ideas for go-getters. Advanced topic for doers to get on with if they finish early. These will usually not have a solution available and are provided for additional scope.

• Git Tasks
  • Add a GitHub Webhook to trigger your build on each commit
• Pipeline Tasks
  • Add pipeline for branch for each project.
  • Use test- instead of dev- across all config and names
• Promote build
  • Create a promote-to-uat phase after the branch deploy
  • Create a uat env using the OpenShift Applier as seen before
  • Tag and promote the image without rebuilding after the test-**-deploy
• MongoDB tasks
  • Add MongoDB Stateful set for the UAT environment (or test)
  • Inject MongoDB config into the NodeJS app using config map & secrets.
  • Improve the security of the DB by making the user /passwords randomly generated
• Setup Nexus as an npm mirror registry and use it in the builds to speed up the build time

Additional Reading

List of links or other reading that might be of use / reference for the exercise

• What's in a package.json?

Slide links

link back to the deck for the supporting material