docs/octopus_docs/opnfv-jenkins-slave-connection.rst

   1 ================================================
   2 Connecting OPNFV Community Labs to OPNFV Jenkins
   3 ================================================
   4
   5 .. contents:: Table of Contents
   6    :backlinks: none
   7
   8 Abstract
   9 ========
  10
  11 This document describes how to connect resources (servers) located in Linux Foundation (LF) lab
  12 and labs provided by the OPNFV Community to OPNFV Jenkins.
  13
  14 License
  15 =======
  16 Connecting OPNFV Community Labs to OPNFV Jenkins (c) by Fatih Degirmenci (Ericsson AB)
  17
  18 Connecting OPNFV Labs to OPNFV Jenkins document is licensed under a Creative Commons
  19 Attribution 4.0 International License.
  20 You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
  21
  22
  23 Version History
  24 ===============
  25
  26 +--------------------+--------------------+--------------------+----------------------+
  27 | **Date**           | **Ver.**           | **Author**         | **Comment**          |
  28 |                    |                    |                    |                      |
  29 +--------------------+--------------------+--------------------+----------------------+
  30 | 2015-05-05         | 0.1.0              | Fatih Degirmenci   | First draft          |
  31 |                    |                    |                    |                      |
  32 +--------------------+--------------------+--------------------+----------------------+
  33 | 2015-09-25         | 1.0.0              | Fatih Degirmenci   | Instructions for the |
  34 |                    |                    |                    | Arno SR1 release     |
  35 +--------------------+--------------------+--------------------+----------------------+
  36
  37 Jenkins
  38 =======
  39
  40 Jenkins is an extensible open source Continuous Integration (CI) server. [1]
  41
  42 Linux Foundation (LF) hosts and operates `OPNFV Jenkins <https://build.opnfv.org/ci/>`_.
  43
  44 Jenkins Slaves
  45 ==============
  46
  47 **Slaves** are computers that are set up to build projects for a **Jenkins Master**.  [2]
  48
  49 Jenkins runs a separate program called "**slave agent**" on slaves.
  50 When slaves are registered to a master, the master starts distributing loads to slaves.  [2]
  51
  52 Term **Node** is used to refer to all machines that are part of Jenkins grid, slaves and master. [2]
  53
  54 Two types of slaves are currently connected to OPNFV Jenkins and handling
  55 different tasks depending on the purpose of connecting the slave.
  56
  57 * Slaves hosted in `LF Lab <https://wiki.opnfv.org/get_started/lflab_hosting#hardware_setup>`_
  58 * Slaves hosted in `Community Test Labs <https://wiki.opnfv.org/pharos#community_test_labs>`_
  59
  60 The slaves connected to OPNFV Jenkins can be seen using this link: https://build.opnfv.org/ci/computer/
  61 Slaves without red cross next to computer icon are fully functional.
  62
  63 Connecting Slaves to OPNFV Jenkins
  64 ==================================
  65
  66 The method that is normally used for connecting slaves to Jenkins requires direct SSH access to servers.
  67 [3] This is the method that is used for connecting slaves hosted in LF Lab.
  68
  69 Connecting slaves using direct SSH access can become a challenge given that OPNFV Project
  70 has number of different labs provided by community as mentioned in previous section.
  71 All these labs have different security requirements which can increase the effort
  72 and the time needed for connecting slaves to Jenkins.
  73 In order to reduce the effort and the time needed for connecting slaves and streamline the process,
  74 it has been decided to connect slaves using `Java Network Launch Protocol (JNLP) <https://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/jnlp.html>`_.
  75
  76 Connecting Slaves from LF Lab to OPNFV Jenkins
  77 ----------------------------------------------
  78
  79 Slaves hosted in LF Lab are handled by LF. All the requests and questions regarding
  80 these slaves should be submitted to `OPNFV LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_.
  81
  82 Connecting Slaves from Community Labs to OPNFV Jenkins
  83 ------------------------------------------------------
  84
  85 As noted in corresponding section, slaves from Community Labs are connected using JNLP. Via JNLP,
  86 slaves open connection towards Jenkins Master instead of Jenkins Master accessing to them directly.
  87
  88 Servers connecting to OPNFV Jenkins using this method must have access to internet.
  89
  90 Please follow below steps to connect a slave to OPNFV Jenkins.
  91
  92 1. Create a ticket by sending mail to OPNFV LF Helpdesk first, opnfv-helpdesk@rt.linuxfoundation.org.
  93 2. Ensure DNS is setup for your public IP addresses: DNS A records and PTR records need to be matching.
  94 3. Create a local user on server you want to connect to OPNFV Jenkins. (named **jenkins** for example)
  95 4. Download slave.jar using https://build.opnfv.org/ci/jnlpJars/slave.jar and place it
  96 to somewhere so jenkins user created in previous step can access.
  97 5. Create a directory /home/jenkins/opnfv_slave_root.
  98 6. Contact LF by sending mail to opnfv-helpdesk@rt.linuxfoundation.org as
  99 getting the server connected requires help from LF.
 100 7. Provide needed information to LF including the IP of the server, name of the slave, slave root,
 101 and your Public PGP key in order for LF to pass credentials to you securely.
 102 Please see the notes section for details regarding how to pass your Public PGP Key.
 103     Slave IP: x.x.x.x
 104
 105     Slave name: company-build
 106
 107     Slave Root: /home/jenkins/opnfv_slave_root
 108
 109     PGP Key: (attached, or exported to key server)
 110 8. LF will provide you the key/token you need to use.
 111 9. Try to see if you can establish connection towards OPNFV Jenkins by using below command.
 112
 113 ``java -jar slave.jar -jnlpUrl https://build.opnfv.org/ci/computer/<slave_name>/slave-agent.jnlp -secret <token>``
 114
 115 10. Navigate to OPNFV Jenkins and look for your slave.
 116 It should have some executors in “Idle” state if the connection is successful.
 117 11. Once you reach this step, you have the server connection to OPNFV Jenkins completed.
 118 You can script the command you used above so the connection between slave and Jenkins can be kept open.
 119
 120 Notes
 121 ==========
 122
 123 Keeping the slave.jar Up to Date
 124 --------------------------------
 125
 126 It is important to keep the slave.jar up to date since OPNFV Jenkins version may be updated any time.
 127 In order to make sure you are using compatible version of slave.jar,
 128 you can download it from https://build.opnfv.org/ci/jnlpJars/slave.jar whenever you reopen the connection towards OPNFV Jenkins.
 129 You may experience random disconnects if you do not do this regularly.
 130
 131 PGP Key Instructions
 132 --------------------
 133
 134 Public PGP Key can be uploaded to public key server so it can be taken from
 135 there using your mail address. Example command to upload the key to key server is
 136
 137     ``gpg --keyserver hkp://keys.gnupg.net:80  --send-keys XXXXXXX``
 138
 139 The Public PGP Key can also be attached to the email by storing the key in a file and then attaching it to the email.
 140
 141     ``gpg --export -a '<your email address>' > pgp.pubkey``
 142
 143 References
 144 ==========
 145
 146 * `What is Jenkins <https://wiki.jenkins-ci.org/display/JENKINS/Meet+Jenkins>`_
 147 * `Jenkins Terminology <https://wiki.jenkins-ci.org/display/JENKINS/Terminology>`_
 148 * `Jenkins SSH Slaves Plugin <https://wiki.jenkins-ci.org/display/JENKINS/SSH+Slaves+plugin>`_