docs/infra/jenkins/connect-to-jenkins.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. (c) Open Platform for NFV Project, Inc. and its contributors
   4
   5 .. _connect-to-jenkins:
   6
   7 ================================================
   8 Connecting OPNFV Community Labs to OPNFV Jenkins
   9 ================================================
  10
  11 .. contents:: Table of Contents
  12    :backlinks: none
  13
  14 Abstract
  15 ========
  16
  17 This document describes how to connect resources (servers) located in Linux Foundation (LF) lab
  18 and labs provided by the OPNFV Community to OPNFV Jenkins.
  19
  20 License
  21 =======
  22 Connecting OPNFV Community Labs to OPNFV Jenkins (c) by Fatih Degirmenci (Ericsson AB) and others.
  23
  24 Connecting OPNFV Labs to OPNFV Jenkins document is licensed under a Creative Commons
  25 Attribution 4.0 International License.
  26
  27 You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
  28
  29
  30 Version History
  31 ===============
  32
  33 +------------+-------------+------------------+---------------------------------------+
  34 | **Date**   | **Version** | **Author**       | **Comment**                           |
  35 |            |             |                  |                                       |
  36 +------------+-------------+------------------+---------------------------------------+
  37 | 2015-05-05 | 0.1.0       | Fatih Degirmenci | First draft                           |
  38 |            |             |                  |                                       |
  39 +------------+-------------+------------------+---------------------------------------+
  40 | 2015-09-25 | 1.0.0       | Fatih Degirmenci | Instructions for the                  |
  41 |            |             |                  | Arno SR1 release                      |
  42 +------------+-------------+------------------+---------------------------------------+
  43 | 2016-01-25 | 1.1.0       | Jun Li           | Change the format for                 |
  44 |            |             |                  | new doc toolchain                     |
  45 +------------+-------------+------------------+---------------------------------------+
  46 | 2016-01-27 | 1.2.0       | Fatih Degirmenci | Instructions for the                  |
  47 |            |             |                  | Brahmaputra release                   |
  48 +------------+-------------+------------------+---------------------------------------+
  49 | 2016-05-25 | 1.3.0       | Julien           | Add an additional step after step9 to |
  50 |            |             |                  | output the correct monit config file  |
  51 +------------+-------------+------------------+---------------------------------------+
  52
  53 Jenkins
  54 =======
  55
  56 Jenkins is an extensible open source Continuous Integration (CI) server. [1]
  57
  58 Linux Foundation (LF) hosts and operates `OPNFV Jenkins <https://build.opnfv.org/ci/>`_.
  59
  60 Jenkins Slaves
  61 ==============
  62
  63 **Slaves** are computers that are set up to build projects for a **Jenkins Master**.  [2]
  64
  65 Jenkins runs a separate program called "**slave agent**" on slaves.
  66 When slaves are registered to a master, the master starts distributing load to slaves by
  67 scheduling jobs to run on slaves if the jobs are set to run on them.  [2]
  68
  69 Term **Node** is used to refer to all machines that are part of Jenkins grid, slaves and
  70 master. [2]
  71
  72 Two types of slaves are currently connected to OPNFV Jenkins and handling
  73 different tasks depending on the purpose of connecting the slave.
  74
  75 * Slaves hosted in `LF Lab <https://wiki.opnfv.org/get_started/lflab_hosting#hardware_setup>`_
  76 * Slaves hosted in `Community Test Labs <https://wiki.opnfv.org/pharos#community_test_labs>`_
  77
  78 The slaves connected to OPNFV Jenkins can be seen using this link:
  79 https://build.opnfv.org/ci/computer/
  80
  81 Slaves without red cross next to computer icon are fully functional.
  82
  83 Connecting Slaves to OPNFV Jenkins
  84 ==================================
  85
  86 The method that is normally used for connecting slaves to Jenkins requires direct SSH access to
  87 servers.
  88 [3] This is the method that is used for connecting slaves hosted in LF Lab.
  89
  90 Connecting slaves using direct SSH access can become a challenge given that OPNFV Project
  91 has number of different labs provided by community as mentioned in previous section.
  92 All these labs have different security requirements which can increase the effort
  93 and the time needed for connecting slaves to Jenkins.
  94 In order to reduce the effort and the time needed for connecting slaves and streamline the
  95 process, it has been decided to connect slaves using
  96 `Java Network Launch Protocol (JNLP) <https://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/jnlp.html>`_.
  97
  98 Connecting Slaves from LF Lab to OPNFV Jenkins
  99 ----------------------------------------------
 100
 101 Slaves hosted in LF Lab are handled by LF. All the requests and questions regarding
 102 these slaves should be submitted to `OPNFV LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_.
 103
 104 Connecting Slaves from Community Labs to OPNFV Jenkins
 105 ------------------------------------------------------
 106
 107 As noted in corresponding section, slaves from Community Labs are connected using JNLP. Via JNLP,
 108 slaves open connection towards Jenkins Master instead of Jenkins Master accessing to them directly.
 109
 110 Servers connecting to OPNFV Jenkins using this method must have access to internet.
 111
 112 Please follow below steps to connect a slave to OPNFV Jenkins.
 113
 114 #. Create a user named **jenkins** on the machine you want to connect to
 115    OPNFV Jenkins and give the user sudo rights.
 116
 117 #. Install needed software on the machine you want to connect to OPNFV
 118    Jenkins as slave.
 119
 120    - openjdk 8
 121    - monit
 122
 123 #. If the slave will be used for running virtual deployments, Functest,
 124    and Yardstick, install below software and make jenkins user the
 125    member of the groups.
 126
 127    - docker
 128    - libvirt
 129
 130 #. Create slave root in Jenkins user home directory.
 131
 132    ``mkdir -p /home/jenkins/opnfv/slave_root``
 133
 134 5. Clone OPNFV Releng Git repository.
 135
 136    .. code::
 137
 138      mkdir -p /home/jenkins/opnfv/repos
 139      cd /home/jenkins/opnfv/repos
 140      git clone https://gerrit.opnfv.org/gerrit/p/releng.git
 141
 142 #. Contact LF by creating a ticket to `Connect my 3rd party CI/Lab
 143    <https://jira.linuxfoundation.org/servicedesk/customer/portal/2/create/135>`_
 144    Include the following information in your ticket.
 145
 146    - Slave root (/home/jenkins/opnfv/slave_root)
 147    - Public IP of the slave (You can get the IP by executing ``curl http://icanhazip.com/``)
 148    - PGP Key (attached to the mail or exported to a key server)
 149
 150 #. Once you get confirmation from LF stating that your slave is created
 151    on OPNFV Jenkins, check if the firewall on LF is open for the server
 152    you are trying to connect to Jenkins.
 153
 154    .. code::
 155
 156       cp /home/jenkins/opnfv/repos/releng/utils/jenkins-jnlp-connect.sh /home/jenkins/
 157       cd /home/jenkins/
 158       sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF> -f
 159
 160    - If you receive an error, follow the steps listed on the command output.
 161
 162 #. Run the same script with test(-t) on foreground in order to make sure
 163    no problem on connection. You should see **INFO: Connected** in the
 164    console log.
 165
 166    ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF> -t``
 167
 168    - If you receive an error similar to the one shown `on this link
 169      <http://hastebin.com/ozadagirax.avrasm>`_, you need to check your
 170      firewall and allow outgoing connections for the port.
 171
 172 #. Kill the Java slave.jar process.
 173
 174 #. Run the same script normally without test(-t) in order to get monit
 175    script created.
 176
 177    ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF>``
 178
 179 #. Edit monit configuration and enable http interface. The file to edit
 180    is /etc/monit/monitrc on Ubuntu systems. Uncomment below lines.
 181
 182    .. code::
 183
 184      set httpd port 2812 and
 185          use address localhost  # only accept connection from localhost
 186          allow localhost        # allow localhost to connect to the server and
 187
 188 #. Restart monit service.
 189
 190    - Without systemd:
 191
 192      ``sudo service monit restart``
 193
 194    - With systemd: you have to enable monit service first and then restart it.
 195
 196      .. code::
 197
 198         sudo systemctl enable monit
 199         sudo systemctl restart monit
 200
 201 #. Check to see if jenkins comes up as managed service in monit.
 202
 203    ``sudo monit status``
 204
 205 #. Connect slave to OPNFV Jenkins using monit.
 206
 207    ``sudo monit start jenkins``
 208
 209 #. Check slave on OPNFV Jenkins to verify the slave is reported as connected.
 210
 211    - The slave on OPNFV Jenkins should have some executors in “Idle”
 212      state if the connection is successful.
 213
 214 Notes
 215 =====
 216
 217 PGP Key Instructions
 218 --------------------
 219
 220 Public PGP Key can be uploaded to public key server so it can be taken from
 221 there using your mail address. Example command to upload the key to key server is
 222
 223 ``gpg --keyserver hkp://keys.gnupg.net:80  --send-keys XXXXXXX``
 224
 225 The Public PGP Key can also be attached to the email by storing the key in a file and then
 226 attaching it to the email.
 227
 228 ``gpg --export -a '<your email address>' > pgp.pubkey``
 229
 230 References
 231 ==========
 232
 233 * `What is Jenkins <https://wiki.jenkins-ci.org/display/JENKINS/Meet+Jenkins>`_
 234 * `Jenkins Terminology <https://wiki.jenkins-ci.org/display/JENKINS/Terminology>`_
 235 * `Jenkins SSH Slaves Plugin <https://wiki.jenkins-ci.org/display/JENKINS/SSH+Slaves+plugin>`_