blob: e30966bdb14ddebaba6efa23bc9885bb9a609b74 [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Components
2
3.. _components:
4
5Components
6==========
7
8Zuul is a distributed system consisting of several components, each of
9which is described below. All Zuul processes read the
10**/etc/zuul/zuul.conf** file (an alternate location may be supplied on
11the command line) which uses an INI file syntax. Each component may
12have its own configuration file, though you may find it simpler to use
13the same file for all components.
14
15A minimal Zuul system may consist of a *scheduler* and *executor* both
16running on the same host. Larger installations should consider
17running multiple executors, each on a dedicated host, and running
18mergers on dedicated hosts as well.
19
20Common
21------
22
23The following applies to all Zuul components.
24
25Configuration
26~~~~~~~~~~~~~
27
28The following sections of **zuul.conf** are used by all Zuul components:
29
30gearman
31"""""""
32
33Client connection information for gearman.
34
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040035**server** (required)
36 Hostname or IP address of the Gearman server::
37
38 server=gearman.example.com
James E. Blaireff5a9d2017-06-20 00:00:37 -070039
40**port**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040041 Port on which the Gearman server is listening::
42
43 port=4730
James E. Blaireff5a9d2017-06-20 00:00:37 -070044
45**ssl_ca**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040046 An openssl file containing a set of concatenated “certification
47 authority” certificates in PEM formet.
James E. Blaireff5a9d2017-06-20 00:00:37 -070048
49**ssl_cert**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040050 An openssl file containing the client public certificate in PEM format.
James E. Blaireff5a9d2017-06-20 00:00:37 -070051
52**ssl_key**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040053 An openssl file containing the client private key in PEM format.
James E. Blaireff5a9d2017-06-20 00:00:37 -070054
James E. Blairfdb111d2017-06-23 20:56:05 +010055zookeeper
56"""""""""
57
James E. Blair4f3e6222017-07-05 14:52:08 -070058.. NOTE: this is a white lie at this point, since only the scheduler
59 uses this, however, we expect other components to use it later, so
60 it's reasonable for admins to plan for this now.
61
James E. Blairfdb111d2017-06-23 20:56:05 +010062**hosts**
63 A list of zookeeper hosts for Zuul to use when communicating with
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040064 Nodepool::
65
66 hosts=zk1.example.com,zk2.example.com,zk3.example.com
James E. Blairfdb111d2017-06-23 20:56:05 +010067
James E. Blaireff5a9d2017-06-20 00:00:37 -070068
69Scheduler
70---------
71
72The scheduler is the primary component of Zuul. The scheduler is not
73a scalable component; one, and only one, scheduler must be running at
74all times for Zuul to be operational. It receives events from any
75connections to remote systems which have been configured, enqueues
76items into pipelines, distributes jobs to executors, and reports
77results.
78
79Configuration
80~~~~~~~~~~~~~
81
82The following sections of **zuul.conf** are used by the scheduler:
83
84gearman_server
85""""""""""""""
86
87The builtin gearman server. Zuul can fork a gearman process from itself rather
88than connecting to an external one.
89
90**start**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040091 Whether to start the internal Gearman server (default: False)::
92
93 start=true
James E. Blaireff5a9d2017-06-20 00:00:37 -070094
95**listen_address**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -040096 IP address or domain name on which to listen (default: all addresses)::
97
98 listen_address=127.0.0.1
James E. Blaireff5a9d2017-06-20 00:00:37 -070099
100**log_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400101 Path to log config file for internal Gearman server::
102
103 log_config=/etc/zuul/gearman-logging.yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -0700104
105**ssl_ca**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400106 An openssl file containing a set of concatenated “certification authority”
107 certificates in PEM formet.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700108
109**ssl_cert**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400110 An openssl file containing the server public certificate in PEM format.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700111
112**ssl_key**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400113 An openssl file containing the server private key in PEM format.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700114
115webapp
116""""""
117
118**listen_address**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400119 IP address or domain name on which to listen (default: 0.0.0.0)::
120
121 listen_address=127.0.0.1
James E. Blaireff5a9d2017-06-20 00:00:37 -0700122
123**port**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400124 Port on which the webapp is listening (default: 8001)::
125
126 port=8008
James E. Blaireff5a9d2017-06-20 00:00:37 -0700127
James E. Blaireff5a9d2017-06-20 00:00:37 -0700128**status_expiry**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400129 Zuul will cache the status.json file for this many seconds (default: 1)::
130
131 status_expiry=1
James E. Blaireff5a9d2017-06-20 00:00:37 -0700132
James E. Blair4f3e6222017-07-05 14:52:08 -0700133**status_url**
134 URL that will be posted in Zuul comments made to changes when
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400135 starting jobs for a change. Used by zuul-scheduler only::
136
137 status_url=https://zuul.example.com/status
James E. Blair4f3e6222017-07-05 14:52:08 -0700138
James E. Blaireff5a9d2017-06-20 00:00:37 -0700139scheduler
140"""""""""
James E. Blaireff5a9d2017-06-20 00:00:37 -0700141
142**tenant_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400143 Path to tenant config file::
144
145 layout_config=/etc/zuul/tenant.yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -0700146
147**log_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400148 Path to log config file::
149
150 log_config=/etc/zuul/scheduler-logging.yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -0700151
152**pidfile**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400153 Path to PID lock file::
154
155 pidfile=/var/run/zuul/scheduler.pid
James E. Blaireff5a9d2017-06-20 00:00:37 -0700156
157**state_dir**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400158 Path to directory that Zuul should save state to::
159
160 state_dir=/var/lib/zuul
James E. Blaireff5a9d2017-06-20 00:00:37 -0700161
162Operation
163~~~~~~~~~
164
165To start the scheduler, run ``zuul-scheduler``. To stop it, kill the
166PID which was saved in the pidfile specified in the configuration.
167
168Most of Zuul's configuration is automatically updated as changes to
169the repositories which contain it are merged. However, Zuul must be
170explicitly notified of changes to the tenant config file, since it is
171not read from a git repository. To do so, send the scheduler PID
172(saved in the pidfile specified in the configuration) a SIGHUP signal.
173
174Merger
175------
176
177Mergers are an optional Zuul service; they are not required for Zuul
178to operate, but some high volume sites may benefit from running them.
179Zuul performs quite a lot of git operations in the course of its work.
180Each change that is to be tested must be speculatively merged with the
181current state of its target branch to ensure that it can merge, and to
182ensure that the tests that Zuul perform accurately represent the
183outcome of merging the change. Because Zuul's configuration is stored
184in the git repos it interacts with, and is dynamically evaluated, Zuul
185often needs to perform a speculative merge in order to determine
186whether it needs to perform any further actions.
187
188All of these git operations add up, and while Zuul executors can also
189perform them, large numbers may impact their ability to run jobs.
190Therefore, administrators may wish to run standalone mergers in order
191to reduce the load on executors.
192
193Configuration
194~~~~~~~~~~~~~
195
196The following section of **zuul.conf** is used by the merger:
197
198merger
199""""""
200
201**git_dir**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400202 Directory that Zuul should clone local git repositories to::
203
204 git_dir=/var/lib/zuul/git
James E. Blaireff5a9d2017-06-20 00:00:37 -0700205
206**git_user_email**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400207 Value to pass to `git config user.email`::
208
209 git_user_email=zuul@example.com
James E. Blaireff5a9d2017-06-20 00:00:37 -0700210
211**git_user_name**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400212 Value to pass to `git config user.name`::
213
214 git_user_name=zuul
James E. Blaireff5a9d2017-06-20 00:00:37 -0700215
216**log_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400217 Path to log config file for the merger process::
218
219 log_config=/etc/zuul/logging.yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -0700220
221**pidfile**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400222 Path to PID lock file for the merger process::
223
224 pidfile=/var/run/zuul-merger/merger.pid
James E. Blaireff5a9d2017-06-20 00:00:37 -0700225
226Operation
227~~~~~~~~~
228
229To start the merger, run ``zuul-merger``. To stop it, kill the
230PID which was saved in the pidfile specified in the configuration.
231
232Executor
233--------
234
235Executors are responsible for running jobs. At the start of each job,
236an executor prepares an environment in which to run Ansible which
237contains all of the git repositories specified by the job with all
238dependent changes merged into their appropriate branches. The branch
239corresponding to the proposed change will be checked out (in all
240projects, if it exists). Any roles specified by the job will also be
241present (also with dependent changes merged, if appropriate) and added
242to the Ansible role path. The executor also prepares an Ansible
243inventory file with all of the nodes requested by the job.
244
245The executor also contains a merger. This is used by the executor to
246prepare the git repositories used by jobs, but is also available to
247perform any tasks normally performed by standalone mergers. Because
248the executor performs both roles, small Zuul installations may not
249need to run standalone mergers.
250
251Trusted and Untrusted Playbooks
252~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253
254The executor runs playbooks in one of two execution contexts depending
255on whether the project containing the playbook is a *config project*
256or an *untrusted project*. If the playbook is in a *config project*,
257the executor runs the playbook in the *trusted* execution context,
258otherwise, it is run in the *untrusted* execution context.
259
260Both execution contexts use `bubblewrap`_ to create a namespace to
261ensure that playbook executions are isolated and are unable to access
262files outside of a restricted environment. The administrator may
263configure additional local directories on the executor to be made
264available to the restricted environment.
265
266The *trusted* execution context has access to all Ansible features,
267including the ability to load custom Ansible modules. Needless to
268say, extra scrutiny should be given to code that runs in a trusted
269context as it could be used to compromise other jobs running on the
270executor, or the executor itself, especially if the administrator has
271granted additional access through bubblewrap, or a method of escaping
272the restricted environment created by bubblewrap is found.
273
274Playbooks run in the *untrusted* execution context are not permitted
275to load additional Ansible modules or access files outside of the
276restricted environment prepared for them by the executor. In addition
277to the bubblewrap environment applied to both execution contexts, in
278the *untrusted* context some standard Ansible modules are replaced
279with versions which prohibit some actions, including attempts to
280access files outside of the restricted execution context. These
281redundant protections are made as part of a defense-in-depth strategy.
282
283.. _bubblewrap: https://github.com/projectatomic/bubblewrap
284
285Configuration
286~~~~~~~~~~~~~
287
288The following sections of **zuul.conf** are used by the executor:
289
290executor
291""""""""
292
293**finger_port**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400294 Port to use for finger log streamer::
295
296 finger_port=79
James E. Blaireff5a9d2017-06-20 00:00:37 -0700297
298**git_dir**
James E. Blair7e6e0a12017-07-25 11:04:42 -0700299 Directory that Zuul should clone local git repositories to. The
300 executor keeps a local copy of every git repository it works with to
301 speed operations and perform speculative merging.
302
303 This should be on the same filesystem as **job_dir** so that when
304 git repos are cloned into the job workspaces, they can be
305 hard-linked to the local git cache. Example::
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400306
307 git_dir=/var/lib/zuul/git
James E. Blaireff5a9d2017-06-20 00:00:37 -0700308
James E. Blair7e6e0a12017-07-25 11:04:42 -0700309**job_dir**
310 Directory that Zuul should use to hold temporary job directories.
311 When each job is run, a new entry will be created under this
312 directory to hold the configuration and scratch workspace for that
313 job. It will be deleted at the end of the job (unless the
314 `--keep-jobdir` command line option is specified).
315
316 This should be on the same filesystem as **git_dir** so that when
317 git repos are cloned into the job workspaces, they can be
318 hard-linked to the local git cache. Example::
319
320 job_dir=/var/lib/zuul/jobs
321
James E. Blaireff5a9d2017-06-20 00:00:37 -0700322**log_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400323 Path to log config file for the executor process::
324
325 log_config=/etc/zuul/logging.yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -0700326
327**private_key_file**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400328 SSH private key file to be used when logging into worker nodes::
329
330 private_key_file=~/.ssh/id_rsa
James E. Blaireff5a9d2017-06-20 00:00:37 -0700331
332**user**
333 User ID for the zuul-executor process. In normal operation as a daemon,
334 the executor should be started as the ``root`` user, but it will drop
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400335 privileges to this user during startup::
336
337 user=zuul
James E. Blaireff5a9d2017-06-20 00:00:37 -0700338
Jamie Lennox7655b552017-03-17 12:33:38 +1100339.. _admin_sitewide_variables:
340
341**variables**
342 Path to an Ansible variables file to supply site-wide variables.
343 This should be a YAML-formatted file consisting of a single
344 dictionary. The contents will be made available to all jobs as
345 Ansible variables. These variables take precedence over all other
346 forms (job variables and secrets). Care should be taken when naming
347 these variables to avoid potential collisions with those used by
348 jobs. Prefixing variable names with a site-specific identifier is
349 recommended. The default is not to add any site-wide variables.
350 See the :ref:`User's Guide <user_sitewide_variables>` for more
351 information.
352
353 Example::
354
355 variables=/etc/zuul/variables.yaml
356
Clint Byrumdc8a0902017-07-20 16:36:27 -0700357**disk_limit_per_job**
358 This integer is the maximum number of megabytes that any one job is
359 allowed to consume on disk while it is running. If a job's scratch
360 space has more than this much space consumed, it will be aborted::
361
362 disk_limit_per_job=100
363
Monty Taylor01380dd2017-07-28 16:01:20 -0500364**trusted_ro_paths**
365
366 List of paths, separated by ':' to read-only bind mount into trusted
367 bubblewrap contexts.
368
369**trusted_rw_paths**
370
371 List of paths, separated by ':' to read-write bind mount into trusted
372 bubblewrap contexts.
373
374**untrusted_ro_paths**
375
376 List of paths, separated by ':' to read-only bind mount into untrusted
377 bubblewrap contexts.
378
379**untrusted_rw_paths**
380
381 List of paths, separated by ':' to read-write bind mount into untrusted
382 bubblewrap contexts.
383
James E. Blaireff5a9d2017-06-20 00:00:37 -0700384merger
385""""""
386
387**git_user_email**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400388 Value to pass to `git config user.email`::
389
390 git_user_email=zuul@example.com
James E. Blaireff5a9d2017-06-20 00:00:37 -0700391
392**git_user_name**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400393 Value to pass to `git config user.name`::
394
395 git_user_name=zuul
James E. Blaireff5a9d2017-06-20 00:00:37 -0700396
397Operation
398~~~~~~~~~
399
400To start the executor, run ``zuul-executor``.
401
402There are several commands which can be run to control the executor's
403behavior once it is running.
404
405To stop the executor immediately, aborting all jobs (they may be
406relaunched according to their retry policy), run ``zuul-executor
407stop``.
408
409To request that the executor stop executing new jobs and exit when all
410currently running jobs have completed, run ``zuul-executor graceful``.
411
412To enable or disable running Ansible in verbose mode (with the '-vvv'
413argument to ansible-playbook) run ``zuul-executor verbose`` and
414``zuul-executor unverbose``.
David Shrewsburyae734d12017-07-11 12:41:59 -0400415
416Web Server
417----------
418
419The Zuul web server currently acts as a websocket interface to live log
420streaming. Eventually, it will serve as the single process handling all
421HTTP interactions with Zuul.
422
423Configuration
424~~~~~~~~~~~~~
425
426In addition to the ``gearman`` common configuration section, the following
427sections of **zuul.conf** are used by the web server:
428
429web
430"""
431
432**listen_address**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400433 IP address or domain name on which to listen (default: 127.0.0.1)::
434
435 listen_address=127.0.0.1
David Shrewsburyae734d12017-07-11 12:41:59 -0400436
437**log_config**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400438 Path to log config file for the web server process::
439
440 log_config=/etc/zuul/logging.yaml
David Shrewsburyae734d12017-07-11 12:41:59 -0400441
442**pidfile**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400443 Path to PID lock file for the web server process::
444
445 pidfile=/var/run/zuul-web/zuul-web.pid
David Shrewsburyae734d12017-07-11 12:41:59 -0400446
447**port**
David Shrewsbury6b3b49b2017-07-11 13:00:38 -0400448 Port to use for web server process::
449
450 port=9000
David Shrewsburyae734d12017-07-11 12:41:59 -0400451
Tobias Henkelb4407fc2017-07-07 13:52:56 +0200452**websocket_url**
453 Base URL on which the websocket service is exposed, if different than the
454 base URL of the web app.
455
David Shrewsburyae734d12017-07-11 12:41:59 -0400456Operation
457~~~~~~~~~
458
459To start the web server, run ``zuul-web``. To stop it, kill the
460PID which was saved in the pidfile specified in the configuration.