6.1 KiB
Installation
Install Zuul
To install a Zuul release from PyPI, run:
pip install zuul
Or from a git checkout, run:
pip install .
That will also install Zuul's python dependencies. To minimize interaction with other python packages installed on a system, you may wish to install Zuul within a Python virtualenv.
Zuul has several system-level dependencies as well. You can find a list of operating system packages in bindep.txt in Zuul's source directory.
External Dependencies
Zuul interacts with several other systems described below.
Gearman
Gearman is a job distribution system that Zuul uses to communicate with its distributed components. The Zuul scheduler distributes work to Zuul mergers and executors using Gearman. You may supply your own gearman server, but the Zuul scheduler includes a built-in server which is recommended. Ensure that all Zuul hosts can communicate with the gearman server.
Zuul distributes secrets to executors via gearman, so be sure to secure it with TLS and certificate authentication. Obtain (or generate) a certificate for both the server and the clients (they may use the same certificate or have individual certificates). They must be signed by a CA, but it can be your own CA.
Nodepool
In order to run all but the simplest jobs, Zuul uses a companion program, Nodepool, to supply the nodes (whether dynamic cloud instances or static hardware) used by jobs. Before starting Zuul, ensure you have Nodepool installed and any images you require built. Zuul only makes one requirement of these nodes: that it be able to log in given a username and ssh private key.
Nodepool uses Zookeeper to communicate internally among its components, and also to communicate with Zuul. You can run a simple single-node Zookeeper instance, or a multi-node cluster. Ensure that the host running the Zuul scheduler has access to the cluster.
Ansible
Zuul uses Ansible to run jobs. Each version of Zuul is designed to work with a specific, contemporary version of Ansible. Zuul specifies that version of Ansible in its python package metadata, and normally the correct version will be installed automatically with Zuul. Because of the close integration of Zuul and Ansible, attempting to use other versions of Ansible with Zuul is not recommended.
Web Deployment Options
The zuul-web
service provides an web dashboard, a REST
API and a websocket log streaming service as a single holistic web
application. For production use it is recommended to run it behind a
reverse proxy, such as Apache or Nginx.
More advanced users may desire to do one or more exciting things such as:
- White Label
-
Serve the dashboard of an individual tenant at the root of its own domain. https://zuul.openstack.org is an example of a Zuul dashboard that has been white labeled for the
openstack
tenant of its Zuul. - Static Offload
-
Shift the duties of serving static files, such as HTML, Javascript, CSS or images to the Reverse Proxy server.
- Static External
-
Serve the static files from a completely separate location that does not support programmatic rewrite rules such as a Swift Object Store.
- Sub-URL
-
Serve a Zuul dashboard from a location below the root URL as part of presenting integration with other application. https://softwarefactory-project.io/zuul3/ is an example of a Zuul dashboard that is being served from a Sub-URL.
None of those make any sense for simple non-production oriented
deployments, so all discussion will assume that the
zuul-web
service is exposed via a Reverse Proxy. Where
rewrite rule examples are given, they will be given with Apache syntax,
but any other Reverse Proxy should work just fine.
Basic Reverse Proxy
Using Apache as the Reverse Proxy requires the
mod_proxy
, mod_proxy_http
and
mod_proxy_wstunnel
modules to be installed and enabled.
Static Offload and White Label additionally require
mod_rewrite
.
All of the cases require a rewrite rule for the websocket streaming, so the simplest reverse-proxy case is:
RewriteEngine on
RewriteRule ^/api/tenant/(.*)/console-stream ws://localhost:9000/api/tenant/$1/console-stream [P]
RewriteRule ^/(.*)$ http://localhost:9000/$1 [P]
Static Offload
To have the Reverse Proxy serve the static html/javscript assets instead of proxying them to the REST layer, register the location where you unpacked the web application as the document root and add a simple rewrite rule:
DocumentRoot /var/lib/html
<Directory /var/lib/html>
Require all granted
</Directory>
RewriteEngine on
RewriteRule ^/t/.*/(.*)$ /$1 [L]
RewriteRule ^/api/tenant/(.*)/console-stream ws://localhost:9000/api/tenant/$1/console-stream [P]
RewriteRule ^/api/(.*)$ http://localhost:9000/api/$1 [P]
White Labeled Tenant
Running a white-labeled tenant is similar to the offload case, but adds a rule to ensure connection webhooks don't try to get put into the tenant scope.
Note
It's possible to do white-labelling without static offload, but it is more complex with no benefit.
Assuming the zuul tenant name is "example", the rewrite rules are:
DocumentRoot /var/lib/html
<Directory /var/lib/html>
Require all granted
</Directory>
RewriteEngine on
RewriteRule ^/api/connection/(.*)$ http://localhost:9000/api/connection/$1 [P]
RewriteRule ^/api/console-stream ws://localhost:9000/api/tenant/example/console-stream [P]
RewriteRule ^/api/(.*)$ http://localhost:9000/api/tenant/example/$1 [P]
Static External
Note
Hosting zuul dashboard on an external static location that does not support dynamic url rewrite rules only works for white-labeled deployments.
In order to serve the zuul dashboard code from an external static
location, ZUUL_API_URL
must be set at javascript build time
by passing the --define
flag to the
npm build:dist
command.
npm build:dist -- --define "ZUUL_API_URL='http://zuul-web.example.com'"