From b732ec93d9c393daf590e1f1de87f80089cfadf5 Mon Sep 17 00:00:00 2001 From: MatthewLi Date: Wed, 20 Jan 2016 21:10:57 -0500 Subject: change the docs format to satisfy sphinx JIRA: OCTO-145 Change-Id: Ic20206fcfcab59354f657a316f76ac4f91935ffb Signed-off-by: MatthewLi (cherry picked from commit 9adbfb9aedab48b320d52270e2ba723d68f7caa1) --- .../opnfv-jenkins-slave-connection.rst | 148 +++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/octopus_docs/opnfv-jenkins-slave-connection.rst (limited to 'docs/octopus_docs/opnfv-jenkins-slave-connection.rst') diff --git a/docs/octopus_docs/opnfv-jenkins-slave-connection.rst b/docs/octopus_docs/opnfv-jenkins-slave-connection.rst new file mode 100644 index 0000000..645ba14 --- /dev/null +++ b/docs/octopus_docs/opnfv-jenkins-slave-connection.rst @@ -0,0 +1,148 @@ +================================================ +Connecting OPNFV Community Labs to OPNFV Jenkins +================================================ + +.. contents:: Table of Contents + :backlinks: none + +Abstract +======== + +This document describes how to connect resources (servers) located in Linux Foundation (LF) lab +and labs provided by the OPNFV Community to OPNFV Jenkins. + +License +======= +Connecting OPNFV Community Labs to OPNFV Jenkins (c) by Fatih Degirmenci (Ericsson AB) + +Connecting OPNFV Labs to OPNFV Jenkins document is licensed under a Creative Commons +Attribution 4.0 International License. +You should have received a copy of the license along with this. If not, see . + + +Version History +=============== + ++--------------------+--------------------+--------------------+----------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-05-05 | 0.1.0 | Fatih Degirmenci | First draft | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2015-09-25 | 1.0.0 | Fatih Degirmenci | Instructions for the | +| | | | Arno SR1 release | ++--------------------+--------------------+--------------------+----------------------+ + +Jenkins +======= + +Jenkins is an extensible open source Continuous Integration (CI) server. [1] + +Linux Foundation (LF) hosts and operates `OPNFV Jenkins `_. + +Jenkins Slaves +============== + +**Slaves** are computers that are set up to build projects for a **Jenkins Master**. [2] + +Jenkins runs a separate program called "**slave agent**" on slaves. +When slaves are registered to a master, the master starts distributing loads to slaves. [2] + +Term **Node** is used to refer to all machines that are part of Jenkins grid, slaves and master. [2] + +Two types of slaves are currently connected to OPNFV Jenkins and handling +different tasks depending on the purpose of connecting the slave. + +* Slaves hosted in `LF Lab `_ +* Slaves hosted in `Community Test Labs `_ + +The slaves connected to OPNFV Jenkins can be seen using this link: https://build.opnfv.org/ci/computer/ +Slaves without red cross next to computer icon are fully functional. + +Connecting Slaves to OPNFV Jenkins +================================== + +The method that is normally used for connecting slaves to Jenkins requires direct SSH access to servers. +[3] This is the method that is used for connecting slaves hosted in LF Lab. + +Connecting slaves using direct SSH access can become a challenge given that OPNFV Project +has number of different labs provided by community as mentioned in previous section. +All these labs have different security requirements which can increase the effort +and the time needed for connecting slaves to Jenkins. +In order to reduce the effort and the time needed for connecting slaves and streamline the process, +it has been decided to connect slaves using `Java Network Launch Protocol (JNLP) `_. + +Connecting Slaves from LF Lab to OPNFV Jenkins +---------------------------------------------- + +Slaves hosted in LF Lab are handled by LF. All the requests and questions regarding +these slaves should be submitted to `OPNFV LF Helpdesk `_. + +Connecting Slaves from Community Labs to OPNFV Jenkins +------------------------------------------------------ + +As noted in corresponding section, slaves from Community Labs are connected using JNLP. Via JNLP, +slaves open connection towards Jenkins Master instead of Jenkins Master accessing to them directly. + +Servers connecting to OPNFV Jenkins using this method must have access to internet. + +Please follow below steps to connect a slave to OPNFV Jenkins. + +1. Create a ticket by sending mail to OPNFV LF Helpdesk first, opnfv-helpdesk@rt.linuxfoundation.org. +2. Ensure DNS is setup for your public IP addresses: DNS A records and PTR records need to be matching. +3. Create a local user on server you want to connect to OPNFV Jenkins. (named **jenkins** for example) +4. Download slave.jar using https://build.opnfv.org/ci/jnlpJars/slave.jar and place it +to somewhere so jenkins user created in previous step can access. +5. Create a directory /home/jenkins/opnfv_slave_root. +6. Contact LF by sending mail to opnfv-helpdesk@rt.linuxfoundation.org as +getting the server connected requires help from LF. +7. Provide needed information to LF including the IP of the server, name of the slave, slave root, +and your Public PGP key in order for LF to pass credentials to you securely. +Please see the notes section for details regarding how to pass your Public PGP Key. + Slave IP: x.x.x.x + + Slave name: company-build + + Slave Root: /home/jenkins/opnfv_slave_root + + PGP Key: (attached, or exported to key server) +8. LF will provide you the key/token you need to use. +9. Try to see if you can establish connection towards OPNFV Jenkins by using below command. + +``java -jar slave.jar -jnlpUrl https://build.opnfv.org/ci/computer//slave-agent.jnlp -secret `` + +10. Navigate to OPNFV Jenkins and look for your slave. +It should have some executors in “Idle” state if the connection is successful. +11. Once you reach this step, you have the server connection to OPNFV Jenkins completed. +You can script the command you used above so the connection between slave and Jenkins can be kept open. + +Notes +========== + +Keeping the slave.jar Up to Date +-------------------------------- + +It is important to keep the slave.jar up to date since OPNFV Jenkins version may be updated any time. +In order to make sure you are using compatible version of slave.jar, +you can download it from https://build.opnfv.org/ci/jnlpJars/slave.jar whenever you reopen the connection towards OPNFV Jenkins. +You may experience random disconnects if you do not do this regularly. + +PGP Key Instructions +-------------------- + +Public PGP Key can be uploaded to public key server so it can be taken from +there using your mail address. Example command to upload the key to key server is + + ``gpg --keyserver hkp://keys.gnupg.net:80 --send-keys XXXXXXX`` + +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. + + ``gpg --export -a '' > pgp.pubkey`` + +References +========== + +* `What is Jenkins `_ +* `Jenkins Terminology `_ +* `Jenkins SSH Slaves Plugin `_ -- cgit 1.2.3-korg