Quick Start Guide

System Requirements

For most deployments zuul only needs 1-2GB. OpenStack uses a 30GB setup.

Install Zuul

You can get zuul from pypi via:

pip install zuul

Zuul Components

Zuul provides the following components:

• zuul-server: scheduler daemon which communicates with Gerrit and Gearman. Handles receiving events, launching jobs, collecting results and postingreports.
• zuul-merger: speculative-merger which communicates with Gearman. Prepares Git repositories for jobs to test against. This additionally requires a web server hosting the Git repositories which can be cloned by the jobs.
• zuul-cloner: client side script used to setup job workspace. It is used to clone the repositories prepared by the zuul-merger described previously.
• gearmand: optional builtin gearman daemon provided by zuul-server

External components:

• Jenkins Gearman plugin: Used by Jenkins to connect to Gearman

Zuul Communication

All the Zuul components communicate with each other using Gearman. As well as the following communication channels:

zuul-server:

• Gerrit
• Gearman Daemon

zuul-merger:

• Gerrit
• Gearman Daemon

zuul-cloner:

• http hosted zuul-merger git repos

Jenkins:

• Gearman Daemon via Jenkins Gearman Plugin

Zuul Setup

At minimum we need to provide zuul.conf and layout.yaml and placed in /etc/zuul/ directory. You will also need a zuul user and ssh key for the zuul user in Gerrit. The following example uses the builtin gearmand service in zuul.

zuul.conf:

[zuul]
layout_config=/etc/zuul/layout.yaml

[merger]
git_dir=/git
zuul_url=http://zuul.example.com/p

[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 Zuul for more details.

The following sets up a basic timer triggered job using zuul.

layout.yaml:

pipelines:
  - name: periodic
    source: gerrit
    manager: IndependentPipelineManager
    trigger:
      timer:
        - time: '0 * * * *'

projects:
  - name: aproject
    periodic:
      - aproject-periodic-build

Starting Zuul

You can run zuul-server 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.

Simply run:

zuul-server

Once run you should have 2 zuul-server processes:

zuul     12102     1  0 Jan21 ?        00:15:45 /home/zuul/zuulvenv/bin/python /home/zuul/zuulvenv/bin/zuul-server -d
zuul     12107 12102  0 Jan21 ?        00:00:01 /home/zuul/zuulvenv/bin/python /home/zuul/zuulvenv/bin/zuul-server -d

Note: In this example zuul was installed in a virtualenv.

The 2nd zuul-server process is gearmand running if you are using the builtin gearmand server, otherwise there will only be 1 process.

Zuul won’t actually process your Job queue however unless you also have a zuul-merger process running.

Simply run:

zuul-merger

Zuul should now be able to process your periodic job as configured above once the Jenkins side of things is configured.

Jenkins Setup

Install the Jenkins Gearman Plugin via Jenkins Plugin management interface. Then naviage to Manage > Configuration > Gearman and setup the Jenkins server hostname/ip and port to connect to gearman.

At this point gearman should be running your Jenkins jobs.

Troubleshooting

Checking Gearman function registration (jobs). You can use telnet to connect to gearman to check that Jenkins is registering your configured jobs in gearman:

telnet <gearman_ip> 4730

Useful commands are workers and status which you can run by just typing those commands once connected to gearman. Every job in your Jenkins master must appear when you run workers for Zuul to be able to run jobs against your Jenkins instance.