zuul
/
zuul
Code Issues Proposed changes

Remove gearman from docs 

Change-Id: Id10e41b23b2b01bcd4ec1b0f69645d1200acf415
This commit is contained in:
James E. Blair 2021-11-29 11:03:13 -08:00 committed by Clark Boylan
parent 215c96f500
commit 07b0b5c5fa
9 changed files with 51 additions and 295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/source/client.rst
View File

@ -4,8 +4,7 @@ Zuul Client
===========
Zuul includes a simple command line client that may be used to affect Zuul's
behavior while running. It must be run on a host that has access to the Gearman
server (e.g., locally on the Zuul host), or on a host with access to Zuul's web
behavior while running. It must be run on a host with access to Zuul's web
server.
Configuration
@ -14,9 +13,7 @@ Configuration
The client uses the same zuul.conf file as the server, and will look
for it in the same locations if not specified on the command line.
If both sections are present, the ``gearman`` section takes precedence over the
``webclient`` section, meaning the client will execute commands using the Gearman
server over the REST API.
The ``webclient`` section is required.
It is also possible to run the client without a configuration file, by using the
``--zuul-url`` option to specify the base URL of the Zuul web server.
@ -162,22 +159,9 @@ may not pass validation if applied on top of the current patch queue in the gate
If the queue of a dependent pipeline is targeted by the promote, all the ongoing
jobs in that queue will be canceled and restarted on top of the promoted changes.
Show
^^^^
.. note:: This command is only available through a Gearman connection.
.. program-output:: zuul show --help
Example::
zuul show running-jobs
tenant-conf-check
^^^^^^^^^^^^^^^^^
.. note:: This command is only available through a Gearman connection.
.. program-output:: zuul tenant-conf-check --help
Example::

35
doc/source/components.rst
View File

@ -16,7 +16,6 @@ which is described below.
Database [fontcolor=grey]
Executor [href="#executor"]
Finger [href="#finger-gateway"]
Gearman [shape=ellipse]
Gerrit [fontcolor=grey]
Merger [href="#merger"]
Statsd [shape=ellipse fontcolor=grey]
@ -26,18 +25,14 @@ which is described below.
GitHub [fontcolor=grey]
Web [href="#web-server"]
Merger -- Gearman
Executor -- Statsd
Executor -- "Job Node"
Web -- Database
Web -- Gearman
Web -- GitHub
Web -- Zookeeper
Web -- Executor
Finger -- Gearman
Finger -- Executor
Gearman -- Scheduler;
Scheduler -- Database;
Scheduler -- Gerrit;
Scheduler -- Zookeeper;
@ -55,34 +50,30 @@ which is described below.
:backlinks: none
Each of the Zuul processes may run on the same host, or different
hosts. Within Zuul, the components communicate with the scheduler via
the Gearman protocol, so each Zuul component needs to be able to
connect to the host running the Gearman server (the scheduler has a
built-in Gearman server which is recommended) on the Gearman port --
TCP port 4730 by default.
hosts.
The Zuul scheduler communicates with Nodepool via the ZooKeeper
protocol. Nodepool requires an external ZooKeeper cluster, and the
Zuul scheduler needs to be able to connect to the hosts in that
cluster on TCP port 2181 or 2281.
Zuul requires an external ZooKeeper cluster running at least ZooKeeper
version 3.5.1, and all Zuul and Nodepool components need to be able to
connect to the hosts in that cluster on a TLS-encrypted TCP port,
typically 2281.
Both the Nodepool launchers and Zuul executors need to be able to
communicate with the hosts which nodepool provides. If these are on
private networks, the Executors will need to be able to route traffic
communicate with the hosts which Nodepool provides. If these are on
private networks, the executors will need to be able to route traffic
to them.
Only Zuul fingergw and Zuul web need to be publicly accessible;
executors never do. Executors should be accessible on TCP port 7900
by fingergw and web.
executors never do. Executors should be accessible on TCP port 7900 by
fingergw and web.
A database is required and configured in ``database`` section of
``/etc/zuul/zuul.conf``. Both Zuul scheduler and Zuul web will need
access to it.
If statsd is enabled, the executors and scheduler needs to be able to
emit data to statsd. Statsd can be configured to run on each host
and forward data, or services may emit to a centralized statsd
collector. Statsd listens on UDP port 8125 by default.
If statsd is enabled, the executors and schedulers need to be able to
emit data to statsd. Statsd can be configured to run on each host and
forward data, or services may emit to a centralized statsd collector.
Statsd listens on UDP port 8125 by default.
A minimal Zuul system may consist of a :ref:`scheduler` and
:ref:`executor` both running on the same host. Larger installations

127
doc/source/configuration.rst
View File

@ -17,13 +17,6 @@ An example ``zuul.conf``:
.. code-block:: ini
[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
@ -44,37 +37,6 @@ Common Options
The following sections of ``zuul.conf`` are used by all Zuul components:
Gearman
~~~~~~~
.. attr:: gearman
Client connection information for Gearman.
.. attr:: server
:required:
Hostname or IP address of the Gearman server.
.. attr:: port
:default: 4730
Port on which the Gearman server is listening.
.. attr:: ssl_ca
An openssl file containing a set of concatenated “certification
authority” certificates in PEM formet.
.. 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.
Statsd
~~~~~~
@ -176,26 +138,17 @@ Database
Scheduler
---------
The scheduler is the primary component of Zuul. The scheduler is not
a scalable component; one, and only one, scheduler must be running at
all times for Zuul to be operational. It receives events from any
The scheduler is the primary component of Zuul. The scheduler is a
scalable component; one or more schedulers must be running at all
times for Zuul to be operational. It receives events from any
connections to remote systems which have been configured, enqueues
items into pipelines, distributes jobs to executors, and reports
results.
The scheduler includes a Gearman server which is used to communicate
with other components of Zuul. It is possible to use an external
Gearman server, but the built-in server is well-tested and
recommended. If the built-in server is used, other Zuul hosts will
need to be able to connect to the scheduler on the Gearman port, TCP
port 4730. It is also strongly recommended to use SSL certs with
Gearman, as secrets are transferred from the scheduler to executors
over this link.
The scheduler must be able to connect to the ZooKeeper cluster used by
Nodepool in order to request nodes. It does not need to connect
directly to the nodes themselves, however -- that function is handled
by the Executors.
The scheduler must be able to connect to the ZooKeeper cluster shared
by Zuul and Nodepool in order to request nodes. It does not need to
connect directly to the nodes themselves, however -- that function is
handled by the Executors.
It must also be able to connect to any services for which connections
are configured (Gerrit, GitHub, etc).
@ -203,44 +156,6 @@ are configured (Gerrit, GitHub, etc).
The following sections of ``zuul.conf`` are used by the scheduler:
.. attr:: gearman_server
The builtin gearman server. Zuul can fork a gearman process from
itself rather than connecting to an external one.
.. attr:: start
:default: false
Whether to start the internal Gearman server.
.. attr:: listen_address
:default: all addresses
IP address or domain name on which to listen.
.. attr:: port
:default: 4730
TCP port on which to listen.
.. attr:: log_config
Path to log config file for internal Gearman server.
.. attr:: ssl_ca
An openssl file containing a set of concatenated “certification
authority” certificates in PEM formet.
.. attr:: ssl_cert
An openssl file containing the server public certificate in PEM
format.
.. attr:: ssl_key
An openssl file containing the server private key in PEM format.
.. attr:: web
.. attr:: root
@ -377,9 +292,9 @@ perform them, large numbers may impact their ability to run jobs.
Therefore, administrators may wish to run standalone mergers in order
to reduce the load on executors.
Mergers need to be able to connect to the Gearman server (usually the
scheduler host) as well as any services for which connections are
configured (Gerrit, GitHub, etc).
Mergers need to be able to connect to the ZooKeeper cluster as well as
any services for which connections are configured (Gerrit, GitHub,
etc).
The following section of ``zuul.conf`` is used by the merger:
@ -461,10 +376,9 @@ perform any tasks normally performed by standalone mergers. Because
the executor performs both roles, small Zuul installations may not
need to run standalone mergers.
Executors need to be able to connect to the Gearman server (usually
the scheduler host), any services for which connections are configured
(Gerrit, GitHub, etc), as well as directly to the hosts which Nodepool
provides.
Executors need to be able to connect to the ZooKeeper cluster, any
services for which connections are configured (Gerrit, GitHub, etc),
as well as directly to the hosts which Nodepool provides.
Trusted and Untrusted Playbooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -854,11 +768,10 @@ log streaming, the REST API and the html/javascript dashboard. All three are
served as a holistic web application. For information on additional supported
deployment schemes, see :ref:`web-deployment-options`.
Web servers need to be able to connect to the Gearman server (usually
the scheduler host). If the SQL reporter is used, they need to be
able to connect to the database it reports to in order to support the
dashboard. If a GitHub connection is configured, they need to be
reachable by GitHub so they may receive notifications.
Web servers need to be able to connect to the ZooKeeper cluster and
the SQL database. If a GitHub, Gitlab, or Pagure connection is
configured, they need to be reachable so they may receive
notifications.
In addition to the common configuration sections, the following
sections of ``zuul.conf`` are used by the web server:
@ -1115,9 +1028,9 @@ For example::
The above would stream the logs for the build identified by `UUID`.
Finger gateway servers need to be able to connect to the Gearman
server (usually the scheduler host), as well as the console streaming
port on the executors (usually 7900).
Finger gateway servers need to be able to connect to the ZooKeeper
cluster, as well as the console streaming port on the executors
(usually 7900).
Finger gateways are optional. They may be run for either or both of
the following purposes:

6
doc/source/examples/keycloak/etc_zuul/zuul.conf
View File

@ -1,9 +1,3 @@
[gearman]
server=scheduler
[gearman_server]
start=true
[zookeeper]
hosts=zk:2281
tls_cert=/var/certs/certs/client.pem

77
doc/source/installation.rst
View File

@ -6,22 +6,6 @@ External Dependencies
Zuul interacts with several other systems described below.
Gearman
~~~~~~~
Gearman is a job distribution system that Zuul uses to communicate
with its distributed components. The Zuul scheduler distributes work
to Zuul mergers and executors using Gearman. You may supply your own
gearman server, but the Zuul scheduler includes a built-in server
which is recommended. Ensure that all Zuul hosts can communicate with
the gearman server.
Zuul distributes secrets to executors via gearman, so be sure to
secure it with TLS and certificate authentication. Obtain (or
generate) a certificate for both the server and the clients (they may
use the same certificate or have individual certificates). They must
be signed by a CA, but it can be your own CA.
Nodepool
~~~~~~~~
@ -35,63 +19,12 @@ in given a username and ssh private key.
ZooKeeper
~~~~~~~~~
Nodepool uses ZooKeeper to communicate internally among its
components, and also to communicate with Zuul. You can run a simple
single-node ZooKeeper instance, or a multi-node cluster. Ensure that
the host running the Zuul scheduler has access to the cluster. Zuul
requires its connections to ZooKeeper be TLS encrypted. ZooKeeper
TLS connectivity requires ZooKeeper 3.5.1 or newer. See
:ref:`howto-zookeeper` for recommendations for operating a small
ZooKeeper cluster that meet these requirements.
.. TODO: SpamapS any zookeeper config recommendations?
Zuul stores private keys for each project it knows about in ZooKeeper.
It is recommended that you periodically back up the private keys in
case the ZooKeeper data store is lost or damaged. The :title:`Zuul
Client` provides two sub-commands for use in this case:
:title:`export-keys` and :title:`import-keys`. Each takes an argument to
a filesystem path and will write the keys to, or read the keys from
that path. The data in the exported files are still secured with the
keystore passphrase, so be sure to retain it as well.
Database
~~~~~~~~
Zuul requires an SQL database; either MariaDB, MySQL, or PostgreSQL.
Installation from PyPI
----------------------
Zuul is a Python application which can be installed from the Python
Package Index (PyPI).
To install a Zuul release from PyPI, run::
pip install zuul
Or from a git checkout, run::
pip install .
That will also install Zuul's python dependencies. To minimize
interaction with other python packages installed on a system, you may
wish to install Zuul within a Python virtualenv.
Zuul has several system-level dependencies as well. You can find a
list of operating system packages in ``bindep.txt`` in Zuul's source
directory.
It is also required to run ``zuul-manage-ansible`` on the
zuul-executor in order to install all supported Ansible versions so
Zuul can use them. See :ref:`ansible-installation-options` for
details.
Installation from Containers
----------------------------
The Zuul project also builds and releases container images on
DockerHub. These are available at: https://hub.docker.com/u/zuul
There is a container image for each of the Zuul :ref:`components <components>`.
Zuul and Nodepool use ZooKeeper to communicate internally among their
components, and also to communicate with each other. You can run a
simple single-node ZooKeeper instance, or a multi-node cluster.
Ensure that all Zuul and Nodepool hosts have access to the cluster.
.. _ansible-installation-options:

31
doc/source/monitoring.rst
View File

@ -501,37 +501,6 @@ These metrics are emitted by the Zuul :ref:`scheduler`:
performance metric of how long the SQL query takes; it is not
the estimated time value itself.
.. stat:: zuul.geard
Gearman job distribution statistics. Gearman jobs encompass the
wide variety of distributed jobs running within the scheduler and
across mergers and executors. These stats are emitted by the `gear
<https://pypi.org/project/gear/>`__ library.
.. stat:: running
:type: gauge
Jobs that Gearman has actively running. The longest running
jobs will usually relate to active job execution so you would
expect this to have a lower bound around there. Note this may
be lower than active nodes, as a multiple-node job will only
have one active Gearman job.
.. stat:: waiting
:type: gauge
Jobs waiting in the gearman queue. This would be expected to be
around zero; note that this is *not* related to the backlogged
queue of jobs waiting for a node allocation (node allocations
are via Zookeeper). If this is unexpectedly high, see
:ref:`debug_gearman` for queue debugging tips to find out which
particular function calls are waiting.
.. stat:: total
:type: gauge
The sum of the `running` and `waiting` jobs.
As an example, given a job named `myjob` in `mytenant` triggered by a
change to `myproject` on the `master` branch in the `gate` pipeline
which took 40 seconds to build, the Zuul scheduler will emit the

3
doc/source/operation.rst
View File

@ -11,9 +11,6 @@ To start, simply run::
zuul-scheduler
Once run you should have two zuul-scheduler processes (if using the
built-in gearman server, or one process otherwise).
Before Zuul can run any jobs, it needs to load its configuration, most
of which is in the git repositories that Zuul operates on. Start an
executor to allow zuul to do that::

36
doc/source/troubleshooting.rst
View File

@ -4,42 +4,6 @@ Troubleshooting
Some advanced troubleshooting options are provided below. These are
generally very low-level and are not normally required.
.. _debug_gearman:
Gearman Jobs
============
Connecting to Gearman can allow you see if any Zuul components appear
to not be accepting requests correctly.
For unencrypted Gearman connections, you can use telnet to connect to
and check which Zuul components are online::
telnet <gearman_ip> 4730
For encrypted connections, you will need to provide suitable keys,
e.g::
openssl s_client -connect localhost:4730 -cert /etc/zuul/ssl/client.pem -key /etc/zuul/ssl/client.key
Commands available are discussed in the Gearman `administrative
protocol <http://gearman.org/protocol>`__. Useful commands are
``workers`` and ``status`` which you can run by just typing those
commands once connected to gearman.
For ``status`` you will see output for internal Zuul functions in the
form ``FUNCTION\tTOTAL\tRUNNING\tAVAILABLE_WORKERS``::
...
executor:resume:ze06.openstack.org 0 0 1
zuul:config_errors_list 0 0 1
zuul:status_get 0 0 1
executor:stop:ze11.openstack.org 0 0 1
zuul:job_list 0 0 1
zuul:tenant_sql_connection 0 0 1
executor:resume:ze09.openstack.org 0 0 1
...
Thread Dumps and Profiling
==========================

11
releasenotes/notes/gearmanectomy-ecec32b3764eafc1.yaml Normal file
View File

@ -0,0 +1,11 @@
---
upgrade:
- |
Zuul no longer uses gearman. It is no longer required to run a
Gearman server, and the Zuul scheduler no longer does so. All
gearman-related settings in zuul.conf files are now ignored and
may be removed.
Commands such as `zuul enqueue` which were previously executed via
Gearman may still be used by creating an authentication token and
adding a `web` section to zuul.conf.