The Gatekeeper, or a project gating system
Go to file
Monty Taylor 51139a0682 Add web-based console log streaming
zuul now provides socket-based console streaming, which is super cool.
In order to have jenkins parity with web streaming, we need to provide a
websocket (javascript in browsers can't really connect to random ports
on servers)

After surveying the existing python websocket options, basically all of
them are based around twisted, eventlet, gevent or asyncio. It's not
just a thing we can easily deal with from our current webob/paste
structure, because it is a change to the fundamental HTTP handling.
While we could write our own websocket server implementation that was
threaded like the rest of zuul, that's a pretty giant amount of work.

Instead, we can run an async-based server that's just for the
websockets, so that we're not all of a sudden putting async code into
the rest of zuul and winding up frankensteined. Since this is new code,
using asyncio and python3 seems like an excellent starting place.

aiohttp supports running a websocket server in a thread. It also
supports doing other HTTP/REST calls, so by going aiohttp we can set
ourselves up for a single answer for the HTTP tier.

In order to keep us from being an open socket relay, we'll expect two
parameters as the first message on the websocket - what's the zuul build
uuid, and what log file do we want to stream. (the second thing,
multiple log files, isn't supported yet by the rest of zuul, but one can
imagine a future where we'd like to support that too, so it's in the
protocol) The websocket server will then ask zuul over gearman for the
IP and port associated with the build and logfile and will start
streaming it to the socket.

Ultimately we'll want the status page to make links of the form:

  /console.html?uuid=<uuid>&logfile=console.log

and we'll want to have apache map the websocket server to something like
/console.

Co-Authored-By: Monty Taylor <mordred@inaugust.com>

Change-Id: Idd0d3f9259e81fa9a60d7540664ce8d5ad2c298f
2017-07-10 10:32:28 -04:00
doc Use worker_name for job cancellation and remove manager 2017-06-29 15:31:29 -04:00
etc Add web-based console log streaming 2017-07-10 10:32:28 -04:00
tests Add web-based console log streaming 2017-07-10 10:32:28 -04:00
tools Remove use of six library 2017-06-19 10:34:57 -05:00
zuul Add web-based console log streaming 2017-07-10 10:32:28 -04:00
.gitignore Add coverage artifacts to .gitignore 2017-06-08 10:10:39 -07:00
.gitreview Set default branch to feature/zuulv3 2015-12-07 11:28:01 -08:00
.mailmap Fix pep8 E127 violations 2012-09-26 14:23:10 +00:00
.testr.conf Tests: store debug logs on error 2017-02-06 10:10:48 -08:00
.zuul.yaml Stop supporting python2 2017-06-16 10:51:03 -05:00
LICENSE Initial commit. 2012-05-29 14:49:32 -07:00
MANIFEST.in Migrate to pbr. 2013-06-25 19:04:30 +00:00
NEWS.rst Fix two typos on zuul documentation 2015-07-28 22:16:32 +09:00
README.rst Add note to README about Python3 2017-06-16 15:43:14 -05:00
TESTING.rst Rename zuul-launcher to zuul-executor 2017-03-15 12:21:24 -04:00
bindep.txt Add redhat-rpm-config to rpm build deps 2017-06-16 15:30:58 -07:00
requirements.txt Add web-based console log streaming 2017-07-10 10:32:28 -04:00
setup.cfg Add web-based console log streaming 2017-07-10 10:32:28 -04:00
setup.py Partial sync with OpenStack requirements. 2013-09-25 15:30:37 -07:00
test-requirements.txt Remove use of hacking lib 2017-05-18 14:23:55 -04:00
tox.ini Stop supporting python2 2017-06-16 10:51:03 -05:00

README.rst

Zuul

Zuul is a project gating system developed for the OpenStack Project.

We are currently engaged in a significant development effort in preparation for the third major version of Zuul. We call this effort Zuul v3 and it is described in more detail below.

Contributing

We are currently engaged in a significant development effort in preparation for the third major version of Zuul. We call this effort Zuul v3 and it is described in this file in the feature/zuulv3 branch of this repo.

To browse the latest code, see: https://git.openstack.org/cgit/openstack-infra/zuul/tree/ To clone the latest code, use git clone git://git.openstack.org/openstack-infra/zuul

Bugs are handled at: https://storyboard.openstack.org/#!/project/679

Code reviews are, as you might expect, handled by gerrit at https://review.openstack.org

Use git review to submit patches (after creating a Gerrit account that links to your launchpad account). Example:

# Do your commits
$ git review
# Enter your username if prompted

Zuul v3

The Zuul v3 effort involves significant changes to Zuul, and its companion program, Nodepool. The intent is for Zuul to become more generally useful outside of the OpenStack community. This is the best way to get started with this effort:

  1. Read the Zuul v3 spec: http://specs.openstack.org/openstack-infra/infra-specs/specs/zuulv3.html

    We use specification documents like this to describe large efforts where we want to make sure that all the participants are in agreement about what will happen and generally how before starting development. These specs should contain enough information for people to evaluate the proposal generally, and sometimes include specific details that need to be agreed upon in advance. They are living documents which can change as work gets underway. However, every change or detail does not need to be reflected in the spec --most work is simply done with patches (and revised if necessary in code review).

  2. Read the Nodepool build-workers spec: http://specs.openstack.org/openstack-infra/infra-specs/specs/nodepool-zookeeper-workers.html

  3. Review any proposed updates to these specs: https://review.openstack.org/#/q/status:open+project:openstack-infra/infra-specs+topic:zuulv3

    Some of the information in the specs may be effectively superceded by changes here, which are still undergoing review.

  4. Read developer documentation on the internal data model and testing: http://docs.openstack.org/infra/zuul/feature/zuulv3/developer.html

    The general philosophy for Zuul tests is to perform functional testing of either the individual component or the entire end-to-end system with external systems (such as Gerrit) replaced with fakes. Before adding additional unit tests with a narrower focus, consider whether they add value to this system or are merely duplicative of functional tests.

  5. Review open changes: https://review.openstack.org/#/q/status:open+branch:feature/zuulv3

    We find that the most valuable code reviews are ones that spot problems with the proposed change, or raise questions about how that might affect other systems or subsequent work. It is also a great way to stay involved as a team in work performed by others (for instance, by observing and asking questions about development while it is in progress). We try not to sweat the small things and don't worry too much about style suggestions or other nitpicky things (unless they are relevant -- for instance, a -1 vote on a change that introduces a yaml change out of character with existing conventions is useful because it makes the system more user-friendly; a -1 vote on a change which uses a sub-optimal line breaking strategy is probably not the best use of anyone's time).

  6. Join #zuul on Freenode. Let others (especially jeblair who is trying to coordinate and prioritize work) know what you would like to work on.

  7. Check storyboard for status of current work items: https://storyboard.openstack.org/#!/board/41

    Work items tagged with low-hanging-fruit are tasks that have been identified as not requiring an expansive knowledge of the system. They may still require either some knowledge or investigation into a specific area, but should be suitable for a developer who is becoming acquainted with the system. Those items can be found at: https://storyboard.openstack.org/#!/story/list?tags=low-hanging-fruit&tags=zuulv3

Once you are up to speed on those items, it will be helpful to know the following:

  • Zuul v3 includes some substantial changes to Zuul, and in order to implement them quickly and simultaneously, we temporarily disabled most of the test suite. That test suite still has relevance, but tests are likely to need updating individually, with reasons ranging from something simple such as a test-framework method changing its name, to more substantial issues, such as a feature being removed as part of the v3 work. Each test will need to be evaluated individually. Feel free to, at any time, claim a test name in this story and work on re-enabling it: https://storyboard.openstack.org/#!/story/2000773

  • Because of the importance of external systems, as well as the number of internal Zuul components, actually running Zuul in a development mode quickly becomes unweildy (imagine uploading changes to Gerrit repeatedly while altering Zuul source code). Instead, the best way to develop with Zuul is in fact to write a functional test. Construct a test to fully simulate the series of events you want to see, then run it in the foreground. For example:

    .tox/py27/bin/python -m testtools.run tests.unit.test_scheduler.TestScheduler.test_jobs_executed

    See TESTING.rst for more information.

  • There are many occasions, when working on sweeping changes to Zuul v3, we left notes for future work items in the code marked with "TODOv3". These represent potentially serious missing functionality or other issues which must be resolved before an initial v3 release (unlike a more conventional TODO note, these really can not be left indefinitely). These present an opportunity to identify work items not otherwise tracked. The names associated with TODO or TODOv3 items do not mean that only that person can address them -- they simply reflect who to ask to explain the item in more detail if it is too cryptic. In your own work, feel free to leave TODOv3 notes if a change would otherwise become too large or unweildy.

Python Version Support

Zuul v3 requires Python 3. It does not support Python 2.

As Ansible is used for the execution of jobs, it's important to note that while Ansible does support Python 3, not all of Ansible's modules do. Zuul currently sets ansible_python_interpreter to python2 so that remote content will be executed with Python2.

Roadmap

  • Begin using Zuul v3 to run jobs for Zuul itself
  • Implement a shim to translate Zuul v2 demand into Nodepool Zookeeper launcher requests
  • Begin using Zookeeper based Nodepool launchers with Zuul v2.5 in OpenStack Infra
  • Move OpenStack Infra to use Zuul v3
  • Implement Github support
  • Begin using Zuul v3 to run tests on Ansible repos
  • Implement support in Nodepool for non-OpenStack clouds
  • Add native container support to Zuul / Nodepool