Jenkins: Document Jenkins setup

We don't have an overview of how our Jenkins CI is hung
together. Add a document to both aid any new instances
being set up, and to help us if we ever need to re-create
the CI.

Fixes: kata-containers#30

Signed-off-by: Graham whaley <[email protected]>

.gitignore

@@ -11,6 +11,7 @@
 !README.md
 !CODE_OF_CONDUCT.md  
 !CONTRIBUTING.md
+!Jenkins_setup.md
 
 # Don't ignore pullapprove yaml file
 .pullapprove.yml
@@ -29,3 +30,7 @@ jenkins/org.jenkinsci.plugins.cloudstats.CloudStatistics.xml
 
 # Ignore Jenkins credentials
 jenkins/credentials.xml
+
+# Include the pictures
+!pictures
+!pictures/**

Jenkins_setup.md

@@ -0,0 +1,161 @@
+# Kata Containers Jenkins CI setup
+
+The main Continuous Integration (CI) system for Kata Containers is [Jenkins](https://jenkins.io/).
+This document gives an overview of how Kata Containers integrates with Jenkins, and
+provides pointers and information to configuration information and scripts that will
+help set up a Kata Containers Jenkins CI system.
+
+## Types of jobs
+
+Kata Containers CI operates two types of CI builds:
+
+- PR builds. Builds are scheduled upon submission or change to a Pull Request on any
+of the repositories
+
+- Master builds. A build is scheduled upon the merge of a Pull Request into the master
+branch of a repository.
+
+How these builds are configured and executed are subtly different:
+
+### PR builds
+
+PR builds are triggered from Jenkins using the [GitHub Pull Request Builder](https://plugins.jenkins.io/ghprb) (GHPRB)
+plugin.
+
+The GHPRB plugin is configured to be triggered via github hooks. This is the preferred method
+to trigger on changes (preferred to polling). The preferred method is to integrate the CIs
+using the [katacontainersbot](https://github.com/katacontainersbot) user. Please discuss
+your requirements with the Kata Containers team who can then discuss the appropriate changes.
+
+The GHPRB triggers should be set up similar to:
+![Jenkins GHPRB plugin trigger config](pictures/ghprb_trigger.png)
+
+The GHPRB `Trigger Setup` further options should be set up similar to:
+![Jenkins GHPRB plugin trigger setup config](pictures/ghprb_adv_triggers.png)
+
+### Master builds
+
+Master branch builds are tracked with the Jenkins [git Source Code Management](https://plugins.jenkins.io/git)
+plugin. GITScm GitHub hooks are used to trigger builds.
+
+The Jenkins setup should look similar to the following for the:
+
+- Repository URL setup
+- Branches to build
+- Hook trigger enablement
+
+![Jenkins master setup](pictures/master_git_config.png)
+
+
+### Github bandwidth and tokens
+
+It should be noted that the GitHub API access is [rate limited](https://developer.github.com/v3/#rate-limiting). If no github access authentication method is configured into Jenkins
+then the CI may quickly run out of GitHub access bandwidth, which will stall the CI.
+
+For Kata Containers CI we configure Jenkins with a GitHub [Personal API token](https://blog.github.com/2013-05-16-personal-api-tokens/), which increases the bandwidth capacity.
+
+## Job build script
+
+Kata Containers Jenkins builds, for both PR and Master builds, are invoked using the top
+level [`jenkins_job_build.sh`](https://github.com/kata-containers/tests/blob/master/.ci/jenkins_job_build.sh) script from the [katacontainers/tests](https://github.com/kata-containers/tests)
+repository.
+
+This script takes a single argument (the path to the repository to build), and utilises
+some environment variables to guide what sort of build and run it should perform.
+
+An example of how this script is invoked from Jenkins is shown in the [Setting up Jenkins](#setting-up-jenkins) section.
+
+## Setting up Jenkins
+
+### Naming jobs
+
+Generally the Jobs in Jenkins are named in the form `kata-containers-<repo>-<distro>-<buildtype>`,
+e.g., for a runtime repo PR build on Ubuntu 17.10, the Job would be called:
+`kata-containers-runtime-ubuntu-17-10-PR`. Following this naming convention will make it much
+easier for other members of the project to navigate all CIs in a similar manner.
+
+### Setting up the scripts
+
+Both PR and Master builds use the same form of build and post-build teardown scripts that
+are configured in the Jenkins Job UI. These scripts look like:
+
+Build execute shell:
+```bash
+#!/bin/bash
+
+set -e
+
+export ghprbPullId
+export ghprbTargetBranch
+
+cd $HOME
+git clone https://github.com/kata-containers/tests.git
+cd tests
+
+.ci/jenkins_job_build.sh "github.com/kata-containers/runtime"
+```
+> **Note:**
+>
+> The `export` of the `ghprb` variables for the Master builds is benign, as the Master
+> builds do not use the GHPRB plugin. Subsequently, the `jenkins_job_build.sh` script can
+> still test for the GHPRB varibles to distinguish between a PR and Master build.
+
+This script is placed into the Jenkins build dialog like:
+
+![Jenkins Build dialog](pictures/jenkins_build.png)
+
+Teardown script:
+
+```bash
+#!/bin/bash
+
+export GOPATH=$WORKSPACE/go
+
+cd $GOPATH/src/github.com/kata-containers/tests
+.ci/teardown.sh "$WORKSPACE"
+```
+
+The teardown script is entered into the Jenkins Post-Build Actions dialog like:
+
+![Jenkins Build dialog](pictures/jenkins_build.png)
+
+## Environment variables
+
+The `jenkins_job_build.sh` script both checks for some variables to decide what to do,
+and sets some variables for sub-scripts to check.
+
+### Input variables
+
+The following variables influence the actions of the script:
+
+| Var                 | Effect                                                           |
+| ---------           | ---------------------------------------------------------------- |
+| `WORKSPACE`         | Must be set. Is set by Jenkins to point at the directory the script will use as its workspace (scratch area) |
+| `ghprbTargetBranch` | Is set by the GHPRB Jenkins plugin. Is only set for PR builds, and is used with `ghprbPullId` to distinguish between PR and Master builds. |
+| `ghprbPullId`       | Is used in PR builds to locate the correct branch on github to pull and build. |
+| `KATA_DEV_MODE`     | Must not be set, or the script will not act as a CI script. KATA_DEV_MODE is a developer only option allowing the script to be run 'safely' in a development environment. |
+| `METRICS_CI`        | If set, will skip running the QA tests after the install/build phases (as the tests are not required for a metrics run). |
+
+### Output variables
+
+| Var                 | Effect                                                           |
+| ---------           | ---------------------------------------------------------------- |
+| `CI`                | Is set by the script (unless KATA_DEV_MODE is already set) to indicate to sub-scripts that this is a CI build. |
+| `GOPATH`            | Is set to the installed Go environment                           |
+| `GOROOT`            | Is set to the installed Go environment                           |
+| `PATH`              | Is modified to include ${GOPATH}/bin, /usr/local/go/bin and the 'sbin' directories. |
+| `kata_repo`         | Is set to the github repo name, as passed in to $1 of the script. |
+
+## Experienced users
+
+For the more experienced Jenkins user, if you are au-fait reading Jenkins xml config files
+then you can find a backup of our Azure based Jenkins QA CI in this repository under the
+[jenkins sub folder](https://github.com/kata-containers/ci/tree/master/jenkins).
+
+## Other CIs
+
+Formerly Kata Containers, and one of its predecessors [Clear Containers](https://github.com/clearcontainers)
+have used both [Travis](https://travis-ci.com/) and [SemaphoreCI](https://semaphoreci.com/)
+as part of their CI infrastructure. Kata Containers is phasing use of these out in current
+preference for Jenkins, but if you have a strict need to use either of those CI systems with
+Kata Containers then feel free to ask the Kata Containers team for any relevant guidance.

README.md

@@ -1,3 +1,6 @@
 # Kata Containers CI
 
 This repository stores configuration for the Kata Containers Continuous Integration (CI) system.
+
+The default CI system for Kata Containers is [Jenkins](https://jenkins.io/). See
+the [Jenkins Setup](Jenkins_setup.md) document for more details.