124 lines
3.3 KiB
ReStructuredText
124 lines
3.3 KiB
ReStructuredText
Quick Start Guide
|
|
=================
|
|
|
|
This provides a very simple overview of Zuul. It is recommended to
|
|
read the following sections for more details.
|
|
|
|
Install Zuul
|
|
------------
|
|
|
|
You can get zuul from pypi via::
|
|
|
|
pip install zuul
|
|
|
|
Zuul Components
|
|
---------------
|
|
|
|
Zuul provides the following components:
|
|
|
|
- **zuul-scheduler**: The main Zuul process. Handles receiving
|
|
events, executing jobs, collecting results and posting reports.
|
|
Coordinates the work of the other components.
|
|
|
|
- **zuul-merger**: Scale-out component that performs git merge
|
|
operations. Zuul performs a large number of git operations in
|
|
the course of its work. Adding merger processes can help speed
|
|
Zuul's processing. This component is optional (zero or more of
|
|
these can be run).
|
|
|
|
- **zuul-executor**: Scale-out component for executing jobs. At
|
|
least one of these is required. Depending on system
|
|
configuration, you can expect a single executor to handle up to
|
|
about 100 simultaneous jobs. Can handle the functions of a
|
|
merger if dedicated mergers are not provided. One or more of
|
|
these must be run.
|
|
|
|
- **zuul-web**: A web server that currently provides websocket access to
|
|
live-streaming of logs.
|
|
|
|
- **gearman**: optional builtin gearman daemon provided by zuul-scheduler
|
|
|
|
External components:
|
|
|
|
- **gearman**: A gearman daemon if the built-in daemon is not used.
|
|
|
|
- **zookeeper**: A zookeeper cluster (or single host) for
|
|
communicating with Nodepool.
|
|
|
|
- **nodepool**: Provides nodes for Zuul to use when executing jobs.
|
|
|
|
|
|
Zuul Setup
|
|
----------
|
|
|
|
At minimum you need to provide **zuul.conf** and **main.yaml** placed
|
|
in **/etc/zuul/**. The following example uses the builtin gearman
|
|
service in Zuul, and a connection to Gerrit.
|
|
|
|
**zuul.conf**::
|
|
|
|
[scheduler]
|
|
tenant_config=/etc/zuul/main.yaml
|
|
|
|
[gearman_server]
|
|
start=true
|
|
|
|
[gearman]
|
|
server=127.0.0.1
|
|
|
|
[connection gerrit]
|
|
driver=gerrit
|
|
server=git.example.com
|
|
port=29418
|
|
baseurl=https://git.example.com/gerrit/
|
|
user=zuul
|
|
sshkey=/home/zuul/.ssh/id_rsa
|
|
|
|
See :ref:`components` and :ref:`connections` for more details.
|
|
|
|
The following tells Zuul to read its configuration from and operate on
|
|
the *example-project* project:
|
|
|
|
**main.yaml**::
|
|
|
|
- tenant:
|
|
name: example-tenant
|
|
source:
|
|
gerrit:
|
|
untrusted-projects:
|
|
- example-project
|
|
|
|
Starting Zuul
|
|
-------------
|
|
|
|
You can run any zuul process with the **-d** option to make it not
|
|
daemonize. It's a good idea at first to confirm there's no issues with
|
|
your configuration.
|
|
|
|
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::
|
|
|
|
zuul-executor
|
|
|
|
Zuul should now be able to read its configuration from the configured
|
|
repo and process any jobs defined therein.
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
You can use telnet to connect to gearman to check which Zuul
|
|
components are online::
|
|
|
|
telnet <gearman_ip> 4730
|
|
|
|
Useful commands are **workers** and **status** which you can run by just
|
|
typing those commands once connected to gearman.
|