3.3 KiB

Raw Blame History

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 components and 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.

3.3 KiB Raw Blame History