Docs: convert some component config to zuul directives

This updates common and scheduler.

Also adds a note to the docs style guide about booleans because
I was reminded of it while I was updating this.

Change-Id: I56b3e3c8f99548887056b881f9b3d77e9f45b275
This commit is contained in:
James E. Blair 2017-08-03 14:47:47 -07:00
parent 32df6d8fb1
commit 979401944a
2 changed files with 110 additions and 79 deletions

View File

@ -7,15 +7,35 @@ Components
Zuul is a distributed system consisting of several components, each of Zuul is a distributed system consisting of several components, each of
which is described below. All Zuul processes read the which is described below. All Zuul processes read the
**/etc/zuul/zuul.conf** file (an alternate location may be supplied on ``/etc/zuul/zuul.conf`` file (an alternate location may be supplied on
the command line) which uses an INI file syntax. Each component may the command line) which uses an INI file syntax. Each component may
have its own configuration file, though you may find it simpler to use have its own configuration file, though you may find it simpler to use
the same file for all components. the same file for all components.
A minimal Zuul system may consist of a *scheduler* and *executor* both An example ``zuul.conf``:
running on the same host. Larger installations should consider
running multiple executors, each on a dedicated host, and running .. code-block:: ini
mergers on dedicated hosts as well.
[gearman]
server=localhost
[gearman_server]
start=true
log_config=/etc/zuul/gearman-logging.yaml
[zookeeper]
hosts=zk1.example.com,zk2.example.com,zk3.example.com
[webapp]
status_url=https://zuul.example.com/status
[scheduler]
log_config=/etc/zuul/scheduler-logging.yaml
A minimal Zuul system may consist of a :ref:`scheduler` and
:ref:`executor` both running on the same host. Larger installations
should consider running multiple executors, each on a dedicated host,
and running mergers on dedicated hosts as well.
Common Common
------ ------
@ -25,46 +45,52 @@ The following applies to all Zuul components.
Configuration Configuration
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The following sections of **zuul.conf** are used by all Zuul components: The following sections of ``zuul.conf`` are used by all Zuul components:
gearman
"""""""
Client connection information for gearman. .. attr:: gearman
**server** (required) Client connection information for Gearman.
Hostname or IP address of the Gearman server::
server=gearman.example.com .. attr:: server
:required:
**port** Hostname or IP address of the Gearman server.
Port on which the Gearman server is listening::
port=4730 .. attr:: port
:default: 4730
**ssl_ca** Port on which the Gearman server is listening.
An openssl file containing a set of concatenated “certification
authority” certificates in PEM formet.
**ssl_cert** .. attr:: ssl_ca
An openssl file containing the client public certificate in PEM format.
**ssl_key** An openssl file containing a set of concatenated “certification
An openssl file containing the client private key in PEM format. authority” certificates in PEM formet.
zookeeper .. attr:: ssl_cert
"""""""""
An openssl file containing the client public certificate in PEM format.
.. attr:: ssl_key
An openssl file containing the client private key in PEM format.
.. NOTE: this is a white lie at this point, since only the scheduler .. NOTE: this is a white lie at this point, since only the scheduler
uses this, however, we expect other components to use it later, so uses this, however, we expect other components to use it later, so
it's reasonable for admins to plan for this now. it's reasonable for admins to plan for this now.
**hosts** .. attr:: zookeeper
A list of zookeeper hosts for Zuul to use when communicating with
Nodepool::
hosts=zk1.example.com,zk2.example.com,zk3.example.com Client connection information for ZooKeeper
.. attr:: hosts
:required:
A list of zookeeper hosts for Zuul to use when communicating
with Nodepool.
.. _scheduler:
Scheduler Scheduler
--------- ---------
@ -79,85 +105,84 @@ results.
Configuration Configuration
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The following sections of **zuul.conf** are used by the scheduler: The following sections of ``zuul.conf`` are used by the scheduler:
gearman_server
""""""""""""""
The builtin gearman server. Zuul can fork a gearman process from itself rather .. attr:: gearman_server
than connecting to an external one.
**start** The builtin gearman server. Zuul can fork a gearman process from
Whether to start the internal Gearman server (default: False):: itself rather than connecting to an external one.
start=true .. attr:: start
:default: false
**listen_address** Whether to start the internal Gearman server.
IP address or domain name on which to listen (default: all addresses)::
listen_address=127.0.0.1 .. attr:: listen_address
:default: all addresses
**log_config** IP address or domain name on which to listen.
Path to log config file for internal Gearman server::
log_config=/etc/zuul/gearman-logging.yaml .. attr:: log_config
**ssl_ca** Path to log config file for internal Gearman server.
An openssl file containing a set of concatenated “certification authority”
certificates in PEM formet.
**ssl_cert** .. attr:: ssl_ca
An openssl file containing the server public certificate in PEM format.
**ssl_key** An openssl file containing a set of concatenated “certification
An openssl file containing the server private key in PEM format. authority” certificates in PEM formet.
webapp .. attr:: ssl_cert
""""""
**listen_address** An openssl file containing the server public certificate in PEM
IP address or domain name on which to listen (default: 0.0.0.0):: format.
listen_address=127.0.0.1 .. attr:: ssl_key
**port** An openssl file containing the server private key in PEM format.
Port on which the webapp is listening (default: 8001)::
port=8008 .. attr:: webapp
**status_expiry** .. attr:: listen_address
Zuul will cache the status.json file for this many seconds (default: 1):: :default: all addresses
status_expiry=1 IP address or domain name on which to listen.
**status_url** .. attr:: port
URL that will be posted in Zuul comments made to changes when :default: 8001
starting jobs for a change. Used by zuul-scheduler only::
status_url=https://zuul.example.com/status Port on which the webapp is listening.
scheduler .. attr:: status_expiry
""""""""" :default: 1
**tenant_config** Zuul will cache the status.json file for this many seconds.
Path to tenant config file::
layout_config=/etc/zuul/tenant.yaml .. attr:: status_url
**log_config** URL that will be posted in Zuul comments made to changes when
Path to log config file:: starting jobs for a change.
log_config=/etc/zuul/scheduler-logging.yaml .. TODO: is this effectively required?
**pidfile** .. attr:: scheduler
Path to PID lock file::
pidfile=/var/run/zuul/scheduler.pid .. attr:: tenant_config
:required:
**state_dir** Path to :ref:`tenant-config` file.
Path to directory that Zuul should save state to::
state_dir=/var/lib/zuul .. attr:: log_config
Path to log config file.
.. attr:: pidfile
Path to PID lock file.
.. attr:: state_dir
Path to directory in which Zuul should save its state.
Operation Operation
~~~~~~~~~ ~~~~~~~~~
@ -169,7 +194,8 @@ Most of Zuul's configuration is automatically updated as changes to
the repositories which contain it are merged. However, Zuul must be the repositories which contain it are merged. However, Zuul must be
explicitly notified of changes to the tenant config file, since it is explicitly notified of changes to the tenant config file, since it is
not read from a git repository. To do so, send the scheduler PID not read from a git repository. To do so, send the scheduler PID
(saved in the pidfile specified in the configuration) a SIGHUP signal. (saved in the pidfile specified in the configuration) a `SIGHUP`
signal.
Merger Merger
------ ------

View File

@ -20,6 +20,11 @@ Filenames and literal values (such as when we instruct a user to type
a specific string into a configuration file) should use the RST a specific string into a configuration file) should use the RST
````literal```` syntax. ````literal```` syntax.
YAML supports boolean values expressed with or without an initial
capital letter. In examples and documentation, use ``true`` and
``false`` in lowercase type because the resulting YAML is easier for
users to type and read.
Terminology Terminology
~~~~~~~~~~~ ~~~~~~~~~~~