Merge "modified for fraser 6.1.0 release"
[releng.git] / 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   1. Create a user named **jenkins** on the machine you want to connect to OPNFV Jenkins and give the user sudo rights.
115   2. Install needed software on the machine you want to connect to OPNFV Jenkins as slave.
116
117     - openjdk 8
118     - monit
119
120   3. If the slave will be used for running virtual deployments, Functest, and Yardstick, install below software and make jenkins user the member of the groups.
121
122     - docker
123     - libvirt
124
125   4. Create slave root in Jenkins user home directory.
126
127     ``mkdir -p /home/jenkins/opnfv/slave_root``
128
129   5. Clone OPNFV Releng Git repository.
130
131     ``mkdir -p /home/jenkins/opnfv/repos``
132
133     ``cd /home/jenkins/opnfv/repos``
134
135     ``git clone https://gerrit.opnfv.org/gerrit/p/releng.git``
136
137   6. Contact LF by sending mail to `OPNFV LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_ and request creation of a slave on OPNFV Jenkins. Include below information in your mail.
138
139     - Slave root (/home/jenkins/opnfv/slave_root)
140     - Public IP of the slave (You can get the IP by executing ``curl http://icanhazip.com/``)
141     - PGP Key (attached to the mail or exported to a key server)
142
143   7. Once you get confirmation from LF stating that your slave is created on OPNFV Jenkins, check if the firewall on LF is open for the server you are trying to connect to Jenkins.
144
145     ``cp /home/jenkins/opnfv/repos/releng/utils/jenkins-jnlp-connect.sh /home/jenkins/``
146     ``cd /home/jenkins/``
147     ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n  <slave name on OPNFV Jenkins> -s <the token you received from LF> -f``
148
149      - If you receive an error, follow the steps listed on the command output.
150
151   8. Run the same script with test(-t) on foreground in order to make sure no problem on connection. You should see **INFO: Connected** in the console log.
152
153     ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF> -t``
154
155      - If you receive an error similar to the one shown `on this link <http://hastebin.com/ozadagirax.avrasm>`_, you need to check your firewall and allow outgoing connections for the port.
156
157   9. Kill the Java slave.jar process.
158   10. Run the same script normally without test(-t) in order to get monit script created.
159
160     ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF>``
161
162   11. Edit monit configuration and enable http interface. The file to edit is /etc/monit/monitrc on Ubuntu systems. Uncomment below lines.
163
164     set httpd port 2812 and
165         use address localhost  # only accept connection from localhost
166         allow localhost        # allow localhost to connect to the server and
167
168   12. Restart monit service.
169
170     - Without systemd:
171
172       ``sudo service monit restart``
173
174     - With systemd: you have to enable monit service first and then restart it.
175
176       ``sudo systemctl enable monit``
177
178       ``sudo systemctl restart monit``
179
180   13. Check to see if jenkins comes up as managed service in monit.
181
182     ``sudo monit status``
183
184   14. Connect slave to OPNFV Jenkins using monit.
185
186     ``sudo monit start jenkins``
187
188   15. Check slave on OPNFV Jenkins to verify the slave is reported as connected.
189
190     - The slave on OPNFV Jenkins should have some executors in “Idle” state if the connection is successful.
191
192 Notes
193 ==========
194
195 PGP Key Instructions
196 --------------------
197
198 Public PGP Key can be uploaded to public key server so it can be taken from
199 there using your mail address. Example command to upload the key to key server is
200
201     ``gpg --keyserver hkp://keys.gnupg.net:80  --send-keys XXXXXXX``
202
203 The Public PGP Key can also be attached to the email by storing the key in a file and then
204 attaching it to the email.
205
206     ``gpg --export -a '<your email address>' > pgp.pubkey``
207
208 References
209 ==========
210
211 * `What is Jenkins <https://wiki.jenkins-ci.org/display/JENKINS/Meet+Jenkins>`_
212 * `Jenkins Terminology <https://wiki.jenkins-ci.org/display/JENKINS/Terminology>`_
213 * `Jenkins SSH Slaves Plugin <https://wiki.jenkins-ci.org/display/JENKINS/SSH+Slaves+plugin>`_