33ccffe302
Change-Id: I718b2dd6fc6c71f67fbb1774ae4b0b625fdf053d Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>
163 lines
4.1 KiB
ReStructuredText
163 lines
4.1 KiB
ReStructuredText
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 :doc:`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.
|