X-Git-Url: https://gerrit.akraino.org/r/gitweb?a=blobdiff_plain;f=ci%2FREADME.md;h=6649ca7c01f2043ac608cb75f66b5a7cdf88f2c7;hb=HEAD;hp=3536070480950b75922f0713ce5d6e2d29b2c24b;hpb=e67da41b552179482f39a413b61ef0beff8ab12a;p=icn.git

diff --git a/ci/README.md b/ci/README.md
index 3536070..6649ca7 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -1,60 +1,95 @@
-# Setup a private Jenkins server from a refresh ubuntu 18.04
+# Setup a private Jenkins server from a fresh Ubuntu 18.04
 
-Akraino community has a publich jenkins cluster, we run CI jobs there.
+Akraino community has a public Jenkins cluster, we run CI jobs there.
 But the CD jobs, we need to run them in our private Jenkins cluster.
-For now, we support only one node private jenkins deployment.
-The only supported OS is ubuntu 18.04
-
-## How to setup jenkins server
-
-We define vars in `vars.yaml` to customize the deployment.
-The default listening address is the default ip address of the Jenkins server.
-To override the listening address/domain name, please set `jenkins_hostname`.
-The default Jenkins username/password is `admin/admin`. To overrides it, please set
-`jenkins_admin_username` and `jenkins_admin_password`.
-
-```bash
-git clone "https://gerrit.akraino.org/r/icn" # may need to switch the branch based on your case
-cd icn/ci
-sudo ./install_ansible.sh
-sudo ansible-playbook site_jenkins.yaml --extra-vars "@vars.yaml" -v
-```
+For now, we support only one node private Jenkins deployment.  The
+only supported OS is Ubuntu 18.04.
 
-Once the playbook is successful, we can visite the jenkins server at http://<listen_address>:8080.
+## How to setup Jenkins server
 
-## What to do next
+We define vars in `vars.yaml` to customize the deployment.  The
+default listening address is the default IP address of the Jenkins
+server.  To override the listening address/domain name, please set
+`jenkins_hostname`.  The default Jenkins username/password is
+`admin/admin`. To override it, please set `jenkins_admin_username` and
+`jenkins_admin_password`.
 
-1. Add the gerrit ssh key as jenkins credential, so that our jobs can pull code from the gerrit.
-The credential ID field must be `jenkins-ssh`, as this is hard coded in the jobs. The type should
-be private key. The user name is the gerrit account name.
-2. To push the logs to Akraino Nexus server, we need to create the authentication file for lftools.
-The file should be owned by jenkins user. The file path is `/var/lib/jenkins/.netrc` and
-the content should be one line `machine nexus.akraino.org login the_name password the_pass`
-3. The last step is to deploy our CD jobs by jenkins-job-builder tool.
+1. If deploying the Jenkins server on a machine configured with KuD
+   (i.e. an ICN jump server), first remove the `ANSIBLE_CONFIG` line
+   from `/etc/environment` and login again.
 
-```
-git clone --recursive "https://gerrit.akraino.org/r/ci-management"
-git clone "https://gerrit.akraino.org/r/icn"
-# create the jjb config file before moving on
-# https://docs.releng.linuxfoundation.org/en/latest/jenkins-sandbox.html
-jenkins-jobs test ci-management/jjb:icn/ci/jjb icn-master-verify
-jenkins-jobs update ci-management/jjb:icn/ci/jjb icn-master-verify
-```
+   ``` shell
+   ./ci.sh cleanup-after-kud
+   logout
+   ```
 
-A sample of jjb config file located at `~/.config/jenkins_jobs/jenkins_jobs.ini`
-```
-[job_builder]
-ignore_cache=True
-keep_descriptions=False
-recursive=True
-retain_anchors=True
-update=jobs
-
-[jenkins]
-user=admin
-password=admin
-url=http://localhost:8080
+2. Install the Jenkins server into the machine. If the VM verifier
+   Jenkins job will not be added later, set `WITH_VAGRANT=no` in the
+   environment before running the install step.
+
+   ``` shell
+   # Use one of the following
+   WITH_VAGRANT=no ./ci.sh install-jenkins
+   ./ci.sh install-jenkins
+   ```
+
+   After the script has completed, the Jenkins server can be visited
+   at http://<listen_address>:8080.
+
+3. Add the Gerrit ssh key as Jenkins credential, so that the jobs can
+   pull code from Gerrit. `JENKINS_SSH_PRIVATE_KEY` is the path to the
+   private key file of the `icn.jenkins` Gerrit account.
+
+   ``` shell
+   JENKINS_SSH_PRIVATE_KEY="path/to/icn.jenkins/id_rsa"
+   ./ci.sh install-credentials
+   ```
+
+  To use a different account, edit `git-url` in `jjb/defaults.yaml`
+  with the account name and execute the above command with the
+  username specified.
+
+   ``` shell
+   JENKINS_SSH_USERNAME="username"
+   JENKINS_SSH_PRIVATE_KEY="path/to/username/id_rsa"
+   ./ci.sh install-credentials
+   ```
+
+4. To push the logs to Akraino Nexus server, we need to create the
+   authentication file for lftools.
+
+   ``` shell
+   JENKINS_LFTOOLS_USERNAME="username"
+   JENKINS_LFTOOLS_PASSWORD="password"
+   ./ci.sh install-lftools-credentials
+   ```
+
+5. Add the ICN Jenkins jobs to Jenkins. The script adds only a subset
+   of the available jobs; review the script for information about
+   other jobs.
+
+   ``` shell
+   ./ci.sh update-jobs
+   ```
+
+## Job specific instructions
+
+### icn-bluval
+
+The Bluval job requires that Jenkins ssh into the cluster control
+plane. The script can be used to create a new keypair for the
+`jenkins` user and install the credentials into an existing cluster.
+
+For example, where the control plane endpoint is at `192.168.151.254`
+and there exists `/home/ubuntu/.kube/config`:
+
+``` shell
+CLUSTER_MASTER_IP=192.168.151.254
+CLUSTER_SSH_USER=root
+./ci.sh install-jenkins-id
 ```
 
-4. There is [a bug](https://issues.jenkins-ci.org/browse/JENKINS-28466) of jenkins
-which makes some environemtn variables not usable. To fix the bug, we need 'Manage Jenkins' > 'Configure System' > 'click save without any changes'.
+The same values of `CLUSTER_MASTER_IP` and `CLUSTER_SSH_USER` should
+be provided to the icn-bluval job in Jenkins. Note that
+`CLUSTER_SSH_USER` must be `root` for the Bluval Lynis testing to
+succeed.