Change-Id: I718b2dd6fc6c71f67fbb1774ae4b0b625fdf053d Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>
4.1 KiB
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.