| James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 1 | Installation |
| 2 | ============ |
| 3 | |
| 4 | Install Zuul |
| 5 | ------------ |
| 6 | |
| 7 | To install a Zuul release from PyPI, run:: |
| 8 | |
| 9 | pip install zuul |
| 10 | |
| 11 | Or from a git checkout, run:: |
| 12 | |
| 13 | pip install . |
| 14 | |
| 15 | That will also install Zuul's python dependencies. To minimize |
| 16 | interaction with other python packages installed on a system, you may |
| 17 | wish to install Zuul within a Python virtualenv. |
| 18 | |
| 19 | Zuul has several system-level dependencies as well. You can find a |
| 20 | list of operating system packages in `bindep.txt` in Zuul's source |
| 21 | directory. |
| 22 | |
| 23 | External Dependencies |
| 24 | --------------------- |
| 25 | |
| 26 | Zuul interacts with several other systems described below. |
| 27 | |
| 28 | Gearman |
| 29 | ~~~~~~~ |
| 30 | |
| 31 | Gearman is a job distribution system that Zuul uses to communicate |
| 32 | with its distributed components. The Zuul scheduler distributes work |
| David Shrewsbury | 1c61c71 | 2017-08-16 16:02:33 -0400 | [diff] [blame] | 33 | to Zuul mergers and executors using Gearman. You may supply your own |
| James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 34 | gearman server, but the Zuul scheduler includes a built-in server |
| 35 | which is recommended. Ensure that all Zuul hosts can communicate with |
| 36 | the gearman server. |
| 37 | |
| 38 | Zuul distributes secrets to executors via gearman, so be sure to |
| 39 | secure it with TLS and certificate authentication. Obtain (or |
| 40 | generate) a certificate for both the server and the clients (they may |
| 41 | use the same certificate or have individual certificates). They must |
| 42 | be signed by a CA, but it can be your own CA. |
| 43 | |
| 44 | Nodepool |
| 45 | ~~~~~~~~ |
| 46 | |
| 47 | In order to run all but the simplest jobs, Zuul uses a companion |
| 48 | program, Nodepool, to supply the nodes (whether dynamic cloud |
| 49 | instances or static hardware) used by jobs. Before starting Zuul, |
| 50 | ensure you have Nodepool installed and any images you require built. |
| 51 | Zuul only makes one requirement of these nodes: that it be able to log |
| 52 | in given a username and ssh private key. |
| 53 | |
| 54 | .. TODO: SpamapS any zookeeper config recommendations? |
| 55 | |
| 56 | Nodepool uses Zookeeper to communicate internally among its |
| 57 | components, and also to communicate with Zuul. You can run a simple |
| 58 | single-node Zookeeper instance, or a multi-node cluster. Ensure that |
| David Shrewsbury | 1c61c71 | 2017-08-16 16:02:33 -0400 | [diff] [blame] | 59 | the host running the Zuul scheduler has access to the cluster. |
| James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 60 | |
| 61 | Ansible |
| 62 | ~~~~~~~ |
| 63 | |
| 64 | Zuul uses Ansible to run jobs. Each version of Zuul is designed to |
| 65 | work with a specific, contemporary version of Ansible. Zuul specifies |
| 66 | that version of Ansible in its python package metadata, and normally |
| 67 | the correct version will be installed automatically with Zuul. |
| 68 | Because of the close integration of Zuul and Ansible, attempting to |
| 69 | use other versions of Ansible with Zuul is not recommended. |