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:
parent
32df6d8fb1
commit
979401944a
|
@ -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
|
||||||
------
|
------
|
||||||
|
|
|
@ -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
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue