blob: 0a1e0e77432f61ab9b63f758fea25bdda54ba539 [file] [log] [blame]
James E. Blaircdd00072012-06-08 19:17:28 -07001:title: Launchers
2
James E. Blair1f4c2bb2013-04-26 08:40:46 -07003.. _Gearman: http://gearman.org/
Antoine Mussod06f2a62012-11-16 17:40:58 +01004
James E. Blair1f4c2bb2013-04-26 08:40:46 -07005.. _`Gearman Plugin`:
6 https://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin
7
Joshua Hesketh6a0a6182014-03-13 13:23:30 +11008.. _`Turbo-Hipster`:
9 http://git.openstack.org/cgit/stackforge/turbo-hipster/
10
11.. _`Turbo-Hipster Documentation`:
12 http://turbo-hipster.rtfd.org/
13
Joshua Hesketh36c3fa52014-01-22 11:40:52 +110014.. _FormPost: http://docs.openstack.org/developer/swift/misc.html#module-swift.common.middleware.formpost
15
James E. Blair1f4c2bb2013-04-26 08:40:46 -070016.. _launchers:
Antoine Mussod06f2a62012-11-16 17:40:58 +010017
James E. Blaircdd00072012-06-08 19:17:28 -070018Launchers
19=========
20
James E. Blair1f4c2bb2013-04-26 08:40:46 -070021Zuul has a modular architecture for launching jobs. Currently, the
22only supported module interfaces with Gearman_. This design allows
23any system to run jobs for Zuul simply by interfacing with a Gearman
24server. The recommended way of integrating a new job-runner with Zuul
25is via this method.
James E. Blaircdd00072012-06-08 19:17:28 -070026
James E. Blair1f4c2bb2013-04-26 08:40:46 -070027If Gearman is unsuitable, Zuul may be extended with a new launcher
28module. Zuul makes very few assumptions about the interface to a
29launcher -- if it can trigger jobs, cancel them, and receive success
30or failure reports, it should be able to be used with Zuul. Patches
31to this effect are welcome.
32
James E. Blair1f4c2bb2013-04-26 08:40:46 -070033Zuul Parameters
34---------------
James E. Blaircdd00072012-06-08 19:17:28 -070035
Joshua Heskethe8987162014-03-13 13:05:33 +110036Zuul will pass some parameters with every job it launches. These are
37for workers to be able to get the repositories into the state they are
38intended to be tested in. Builds can be triggered either by an action
39on a change or by a reference update. Both events share a common set
40of parameters and more specific parameters as follows:
Antoine Mussoe0f5bb42014-03-04 11:30:37 +010041
42Common parameters
43~~~~~~~~~~~~~~~~~
James E. Blaircdd00072012-06-08 19:17:28 -070044
James E. Blair81515ad2012-10-01 18:29:08 -070045**ZUUL_UUID**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010046 Zuul provided key to link builds with Gerrit events.
James E. Blair81515ad2012-10-01 18:29:08 -070047**ZUUL_REF**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010048 Zuul provided ref that includes commit(s) to build.
James E. Blair81515ad2012-10-01 18:29:08 -070049**ZUUL_COMMIT**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010050 The commit SHA1 at the head of ZUUL_REF.
James E. Blair81515ad2012-10-01 18:29:08 -070051**ZUUL_PROJECT**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010052 The project that triggered this build.
James E. Blair81515ad2012-10-01 18:29:08 -070053**ZUUL_PIPELINE**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010054 The Zuul pipeline that is building this job.
Arx Cruzb1b010d2013-10-28 19:49:59 -020055**ZUUL_URL**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010056 The URL for the zuul server as configured in zuul.conf.
Joshua Heskethba8776a2014-01-12 14:35:40 +080057 A test runner may use this URL as the basis for fetching
Arx Cruzb1b010d2013-10-28 19:49:59 -020058 git commits.
Joshua Hesketh6c21dd12014-03-31 12:23:21 +110059**BASE_LOG_PATH**
60 zuul suggests a path to store and address logs. This is deterministic
61 and hence useful for where you want workers to upload to a specific
62 destination or need them to have a specific final URL you can link to
63 in advanced. For changes it is:
64 "last-two-digits-of-change/change-number/patchset-number".
65 For reference updates it is: "first-two-digits-of-newrev/newrev"
66**LOG_PATH**
67 zuul also suggests a unique path for logs to the worker. This is
68 "BASE_LOG_PATH/pipeline-name/job-name/uuid"
James E. Blair5821bd92015-09-16 08:48:15 -070069**ZUUL_VOTING**
70 Whether Zuul considers this job voting or not. Note that if Zuul is
71 reconfigured during the run, the voting status of a job may change
72 and this value will be out of date. Values are '1' if voting, '0'
73 otherwise.
James E. Blaircdd00072012-06-08 19:17:28 -070074
Antoine Mussoe0f5bb42014-03-04 11:30:37 +010075Change related parameters
76~~~~~~~~~~~~~~~~~~~~~~~~~
77
James E. Blair1f4c2bb2013-04-26 08:40:46 -070078The following additional parameters will only be provided for builds
79associated with changes (i.e., in response to patchset-created or
80comment-added events):
James E. Blaircdd00072012-06-08 19:17:28 -070081
James E. Blair81515ad2012-10-01 18:29:08 -070082**ZUUL_BRANCH**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010083 The target branch for the change that triggered this build.
James E. Blair81515ad2012-10-01 18:29:08 -070084**ZUUL_CHANGE**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010085 The Gerrit change ID for the change that triggered this build.
Julia Kreger012c1c52015-04-21 20:11:39 -040086**ZUUL_CHANGES**
87 A caret character separated list of the changes upon which this build
88 is dependent upon in the form of a colon character separated list
89 consisting of project name, target branch, and revision ref.
James E. Blair81515ad2012-10-01 18:29:08 -070090**ZUUL_CHANGE_IDS**
91 All of the Gerrit change IDs that are included in this build (useful
Łukasz Jernaś048acb42014-03-02 18:49:41 +010092 when the DependentPipelineManager combines changes for testing).
James E. Blair81515ad2012-10-01 18:29:08 -070093**ZUUL_PATCHSET**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010094 The Gerrit patchset number for the change that triggered this build.
James E. Blaircdd00072012-06-08 19:17:28 -070095
Antoine Mussoe0f5bb42014-03-04 11:30:37 +010096Reference updated parameters
97~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
James E. Blair1f4c2bb2013-04-26 08:40:46 -070099The following additional parameters will only be provided for
James E. Blair81515ad2012-10-01 18:29:08 -0700100post-merge (ref-updated) builds:
James E. Blaircdd00072012-06-08 19:17:28 -0700101
James E. Blair81515ad2012-10-01 18:29:08 -0700102**ZUUL_OLDREV**
103 The SHA1 of the old revision at this ref (recall the ref name is
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100104 in ZUUL_REF).
James E. Blair81515ad2012-10-01 18:29:08 -0700105**ZUUL_NEWREV**
106 The SHA1 of the new revision at this ref (recall the ref name is
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100107 in ZUUL_REF).
James E. Blair81515ad2012-10-01 18:29:08 -0700108**ZUUL_SHORT_OLDREV**
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100109 The shortened (7 character) SHA1 of the old revision.
James E. Blair81515ad2012-10-01 18:29:08 -0700110**ZUUL_SHORT_NEWREV**
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100111 The shortened (7 character) SHA1 of the new revision.
James E. Blaircdd00072012-06-08 19:17:28 -0700112
Antoine Mussoe0f5bb42014-03-04 11:30:37 +0100113Unset revisions default to 00000000000000000000000000000000.
114
115Examples:
116
117When a reference is created::
118
119 ZUUL_OLDREV=00000000000000000000000000000000
120 ZUUL_NEWREV=123456789abcdef123456789abcdef12
121 ZUUL_SHORT_OLDREV=0000000
122 ZUUL_SHORT_NEWREV=1234567
123
124When a reference is deleted::
125
126 ZUUL_OLDREV=123456789abcdef123456789abcdef12
127 ZUUL_NEWREV=00000000000000000000000000000000
128 ZUUL_SHORT_OLDREV=1234567
129 ZUUL_SHORT_NEWREV=0000000
130
131And finally a reference being altered::
132
133 ZUUL_OLDREV=123456789abcdef123456789abcdef12
134 ZUUL_NEWREV=abcdef123456789abcdef123456789ab
135 ZUUL_SHORT_OLDREV=1234567
136 ZUUL_SHORT_NEWREV=abcdef1
137
138Your jobs can check whether the parameters are ``000000`` to act
139differently on each kind of event.
140
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100141Swift parameters
142~~~~~~~~~~~~~~~~
143
144If swift information has been configured for the job zuul will also
145provide signed credentials for the builder to upload results and
146assets into containers using the `FormPost`_ middleware.
147
148Each zuul container/instruction set will contain each of the following
149parameters where $NAME is the ``name`` defined in the layout.
150
151*SWIFT_$NAME_URL*
152 The swift destination URL. This will be the entire URL including
153 the AUTH, container and path prefix (folder).
154*SWIFT_$NAME_HMAC_BODY*
155 The information signed in the HMAC body. The body is as follows::
156
157 PATH TO OBJECT PREFIX (excluding domain)
158 BLANK LINE (zuul implements no form redirect)
159 MAX FILE SIZE
160 MAX FILE COUNT
161 SIGNATURE EXPIRY
162
163*SWIFT_$NAME_SIGNATURE*
164 The HMAC body signed with the configured key.
165*SWIFT_$NAME_LOGSERVER_PREFIX*
166 The URL to prepend to the object path when returning the results
167 from a build.
168
Joshua Heskethe8987162014-03-13 13:05:33 +1100169Gearman
170-------
171
172Gearman_ is a general-purpose protocol for distributing jobs to any
173number of workers. Zuul works with Gearman by sending specific
174information with job requests to Gearman, and expects certain
175information to be returned on completion. This protocol is described
176in `Zuul-Gearman Protocol`_.
177
178In order for Zuul to run any jobs, you will need a running Gearman
179server. Zuul includes a Gearman server, and it is recommended that it
180be used as it supports the following features needed by Zuul:
181
182* Canceling jobs in the queue (admin protocol command "cancel job").
183* Strict FIFO queue operation (gearmand's round-robin mode may be
184 sufficient, but is untested).
185
186To enable the built-in server, see the ``gearman_server`` section of
187``zuul.conf``. Be sure that the host allows connections from Zuul and
188any workers (e.g., Jenkins masters) on TCP port 4730, and nowhere else
189(as the Gearman protocol does not include any provision for
190authentication).
191
192Gearman Jenkins Plugin
193~~~~~~~~~~~~~~~~~~~~~~
194
195The `Gearman Jenkins Plugin`_ makes it easy to use Jenkins with Zuul
196by providing an interface between Jenkins and Gearman. In this
197configuration, Zuul asks Gearman to run jobs, and Gearman can then
198distribute those jobs to any number of Jenkins systems (including
199multiple Jenkins masters).
200
201The `Gearman Plugin`_ can be installed in Jenkins in order to
202facilitate Jenkins running jobs for Zuul. Install the plugin and
203configure it with the hostname or IP address of your Gearman server
204and the port on which it is listening (4730 by default). It will
205automatically register all known Jenkins jobs as functions that Zuul
206can invoke via Gearman.
207
208Any number of masters can be configured in this way, and Gearman will
209distribute jobs to all of them as appropriate.
210
211No special Jenkins job configuration is needed to support triggering
212by Zuul.
213
214The Gearman Plugin will ensure the `Zuul Parameters`_ are supplied as
215Jenkins build parameters, so they will be available for use in the job
216configuration as well as to the running job as environment variables.
217
Antoine Mussoe0f5bb42014-03-04 11:30:37 +0100218Jenkins git plugin configuration
Joshua Heskethe8987162014-03-13 13:05:33 +1100219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Antoine Mussoe0f5bb42014-03-04 11:30:37 +0100220
James E. Blair81515ad2012-10-01 18:29:08 -0700221In order to test the correct build, configure the Jenkins Git SCM
222plugin as follows::
James E. Blaircdd00072012-06-08 19:17:28 -0700223
James E. Blair81515ad2012-10-01 18:29:08 -0700224 Source Code Management:
225 Git
226 Repositories:
227 Repository URL: <your Gerrit or Zuul repository URL>
228 Advanced:
229 Refspec: ${ZUUL_REF}
230 Branches to build:
231 Branch Specifier: ${ZUUL_COMMIT}
James E. Blaire2819012013-06-28 17:17:26 -0400232 Advanced:
233 Clean after checkout: True
James E. Blaircdd00072012-06-08 19:17:28 -0700234
James E. Blair81515ad2012-10-01 18:29:08 -0700235That should be sufficient for a job that only builds a single project.
236If you have multiple interrelated projects (i.e., they share a Zuul
237Change Queue) that are built together, you may be able to configure
238the Git plugin to prepare them, or you may chose to use a shell script
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700239instead. As an example, the OpenStack project uses the following
240script to prepare the workspace for its integration testing:
James E. Blair81515ad2012-10-01 18:29:08 -0700241
K Jonathan Harker97e457e2013-02-26 13:29:38 -0800242 https://github.com/openstack-infra/devstack-gate/blob/master/devstack-vm-gate-wrap.sh
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700243
Joshua Hesketh6a0a6182014-03-13 13:23:30 +1100244Turbo Hipster Worker
245~~~~~~~~~~~~~~~~~~~~
246
247As an alternative to Jenkins, `Turbo-Hipster`_ is a small python
248project designed specifically as a zuul job worker which can be
249registered with gearman as a job runner. Please see the
250`Turbo-Hipster Documentation`_ for details on how to set it up.
251
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700252Zuul-Gearman Protocol
Joshua Heskethe8987162014-03-13 13:05:33 +1100253~~~~~~~~~~~~~~~~~~~~~
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700254
255This section is only relevant if you intend to implement a new kind of
256worker that runs jobs for Zuul via Gearman. If you just want to use
257Jenkins, see `Gearman Jenkins Plugin`_ instead.
258
259The Zuul protocol as used with Gearman is as follows:
260
261Starting Builds
Joshua Heskethe8987162014-03-13 13:05:33 +1100262^^^^^^^^^^^^^^^
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700263
264To start a build, Zuul invokes a Gearman function with the following
265format:
266
267 build:FUNCTION_NAME
268
269where **FUNCTION_NAME** is the name of the job that should be run. If
270the job should run on a specific node (or class of node), Zuul will
271instead invoke:
272
273 build:FUNCTION_NAME:NODE_NAME
274
275where **NODE_NAME** is the name or class of node on which the job
276should be run. This can be specified by setting the ZUUL_NODE
Antoine Musso7c5db972013-09-26 11:48:26 +0200277parameter in a parameter-function (see :ref:`includes` section in
278:ref:`zuulconf`).
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700279
280Zuul sends the ZUUL_* parameters described in `Zuul Parameters`_
281encoded in JSON format as the argument included with the
282SUBMIT_JOB_UNIQ request to Gearman. A unique ID (equal to the
283ZUUL_UUID parameter) is also supplied to Gearman, and is accessible as
284an added Gearman parameter with GRAB_JOB_UNIQ.
285
286When a Gearman worker starts running a job for Zuul, it should
287immediately send a WORK_DATA packet with the following information
288encoded in JSON format:
289
James E. Blair3c483cf2013-06-04 16:30:43 -0700290**name**
291 The name of the job.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700292
293**number**
294 The build number (unique to this job).
295
James E. Blair3c483cf2013-06-04 16:30:43 -0700296**manager**
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700297 A unique identifier associated with the Gearman worker that can
298 abort this build. See `Stopping Builds`_ for more information.
299
James E. Blair3c483cf2013-06-04 16:30:43 -0700300**url** (optional)
301 The URL with the status or results of the build. Will be used in
302 the status page and the final report.
303
Joshua Heskethba8776a2014-01-12 14:35:40 +0800304To help with debugging builds a worker may send back some optional
305metadata:
306
307**worker_name** (optional)
308 The name of the worker.
309
310**worker_hostname** (optional)
311 The hostname of the worker.
312
313**worker_ips** (optional)
314 A list of IPs for the worker.
315
316**worker_fqdn** (optional)
317 The FQDN of the worker.
318
319**worker_program** (optional)
320 The program name of the worker. For example Jenkins or turbo-hipster.
321
322**worker_version** (optional)
323 The version of the software running the job.
324
325**worker_extra** (optional)
326 A dictionary of any extra metadata you may want to pass along.
327
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700328It should then immediately send a WORK_STATUS packet with a value of 0
329percent complete. It may then optionally send subsequent WORK_STATUS
330packets with updated completion values.
331
332When the build is complete, it should send a final WORK_DATA packet
333with the following in JSON format:
334
335**result**
336 Either the string 'SUCCESS' if the job succeeded, or any other value
337 that describes the result if the job failed.
338
339Finally, it should send either a WORK_FAIL or WORK_COMPLETE packet as
340appropriate. A WORK_EXCEPTION packet will be interpreted as a
341WORK_FAIL, but the exception will be logged in Zuul's error log.
342
343Stopping Builds
Joshua Heskethe8987162014-03-13 13:05:33 +1100344^^^^^^^^^^^^^^^
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700345
346If Zuul needs to abort a build already in progress, it will invoke the
347following function through Gearman:
348
James E. Blair3c483cf2013-06-04 16:30:43 -0700349 stop:MANAGER_NAME
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700350
James E. Blair3c483cf2013-06-04 16:30:43 -0700351Where **MANAGER_NAME** is the name of the manager worker supplied in
352the initial WORK_DATA packet when the job started. This is used to
353direct the stop: function invocation to the correct Gearman worker
354that is capable of stopping that particular job. The argument to the
355function should be the following encoded in JSON format:
356
357**name**
358 The job name of the build to stop.
359
360**number**
361 The build number of the build to stop.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700362
363The original job is expected to complete with a WORK_DATA and
364WORK_FAIL packet as described in `Starting Builds`_.
365
366Build Descriptions
Joshua Heskethe8987162014-03-13 13:05:33 +1100367^^^^^^^^^^^^^^^^^^
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700368
369In order to update the job running system with a description of the
370current state of all related builds, the job runner may optionally
371implement the following Gearman function:
372
James E. Blair3c483cf2013-06-04 16:30:43 -0700373 set_description:MANAGER_NAME
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700374
James E. Blair3c483cf2013-06-04 16:30:43 -0700375Where **MANAGER_NAME** is used as described in `Stopping Builds`_.
376The argument to the function is the following encoded in JSON format:
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700377
James E. Blair3c483cf2013-06-04 16:30:43 -0700378**name**
379 The job name of the build to describe.
380
381**number**
382 The build number of the build to describe.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700383
384**html_description**
385 The description of the build in HTML format.