Browse Source

initial commit with current state of doc

master
Brennen Bearnes 2 years ago
commit
fffb0319ee
2 changed files with 262 additions and 0 deletions
  1. BIN
      arch.png
  2. +262
    -0
      index.md

BIN
arch.png View File

Before After
Width: 658  |  Height: 539  |  Size: 48 KiB

+ 262
- 0
index.md View File

@ -0,0 +1,262 @@
# Zuul v3 Proof of Concept
Brennen Bearnes <bbearnes@wikimedia.org>, August 2019
## Configuration
I spun up Zuul on DigitalOcean droplets under my personal account. I initially
tried to get Zuul working from scratch, following [Zuul From Scratch][scratch]
on a Debian Buster system. This proved difficult. I encountered
incompatibilities with Java runtimes and various other dependencies.
Eventually, I fell back to [the docker-compose quick start][quick], as
described in the [initial evaluation task, T218138][T218138], with the addition
of a separate Buster droplet as a test node.
From the quick start's [`docker-compose.yaml`][docker-compose], I use the
following services:
- Gerrit
- MariaDB
- zuul-web
- zuul-executor
- zuul-scheduler
- Zookeeper
- Nodepool launcher
- an Apache log server
Initial configuration files for these services are mounted from
[doc/source/admin/examples][example-conf] in the zuul repo, where they can be
modified in place.
### Zuul
Zuul configuration includes:
- `etc_zuul/zuul.conf`: ini-format config for various services
- `etc_zuul/main.yaml`: YAML tenant config: projects are grouped into
tenants, which share configuration and jobs
- `etc_zuul/scheduler_logging.conf`: ini-format Python logging config
Finally, docker-compose runs an Ansible playbook to create an empty
`zuul-config` repo on the Gerrit instance, and instructions are provided for
adding pipelines and Ansible playbooks. Zuul configuration changes from the
`zuul-config` repo take effect as soon as they're reviewed and merged in
Gerrit.
`zuul-config` is listed under _config-projects_ in the tenant config in
`etc_zuul/main.yaml`, which means that it runs with elevated privileges.
Normal projects (such as blubber) and a sort of standard library of Ansible
jobs called `zuul-jobs` are listed under _untrusted-projects_:
```yaml
- tenant:
name: example-tenant
source:
gerrit:
config-projects:
- zuul-config
untrusted-projects:
- test1
- test2
- blubber
opendev.org:
untrusted-projects:
- zuul/zuul-jobs:
include:
- job
```
In `zuul-config`, I have the following structure:
```
brennen@lostsnail-0:~/zuul-config$ tree
.
├── playbooks
│   └── base
│   ├── post-logs.yaml
│   ├── post-ssh.yaml
│   └── pre.yaml
└── zuul.d
├── jobs.yaml
├── pipelines.yaml
└── projects.yaml
3 directories, 6 files
```
`playbooks` contain base Ansible playbooks which are inherited by all jobs.
`zuul.d` contains the following:
```
# Project definitions - the first uses a regex to match on all projects:
brennen@lostsnail-0:~/zuul-config/zuul.d$ cat projects.yaml
- project:
name: ^.*$
check:
jobs: []
gate:
jobs: []
- project:
name: zuul-config
check:
jobs:
- noop
gate:
jobs:
- noop
```
```
# Job definitions:
brennen@lostsnail-0:~/zuul-config/zuul.d$ cat jobs.yaml
- job:
name: base
parent: null
description: |
The recommended base job.
All jobs ultimately inherit from this. It runs a pre-playbook
which copies all of the job's prepared git repos on to all of
the nodes in the nodeset.
It also sets a default timeout value (which may be overidden).
pre-run: playbooks/base/pre.yaml
post-run:
- playbooks/base/post-ssh.yaml
- playbooks/base/post-logs.yaml
roles:
- zuul: zuul/zuul-jobs
timeout: 1800
nodeset:
nodes:
- name: debian-buster
label: debian-buster
```
```
# Check and gate pipelines:
brennen@lostsnail-0:~/zuul-config/zuul.d$ cat pipelines.yaml
- pipeline:
name: check
description: |
Newly uploaded patchsets enter this pipeline to receive an
initial +/-1 Verified vote.
manager: independent
require:
gerrit:
open: True
current-patchset: True
trigger:
gerrit:
- event: patchset-created
- event: change-restored
- event: comment-added
comment: (?i)^(Patch Set [0-9]+:)?( [\w\\+-]*)*(\n\n)?\s*recheck
success:
gerrit:
Verified: 1
mysql:
failure:
gerrit:
Verified: -1
mysql:
- pipeline:
name: gate
description: |
Changes that have been approved are enqueued in order in this
pipeline, and if they pass tests, will be merged.
manager: dependent
post-review: True
require:
gerrit:
open: True
current-patchset: True
approval:
- Workflow: 1
trigger:
gerrit:
- event: comment-added
approval:
- Workflow: 1
start:
gerrit:
Verified: 0
success:
gerrit:
Verified: 2
submit: true
mysql:
failure:
gerrit:
Verified: -2
mysql:
```
### Nodepool
Nodepool's configuration in `etc_nodepool/nodepool.yaml` includes a list of
static nodes for running jobs - in this case, there's only one:
```yaml
providers:
- name: static-vms
driver: static
pools:
- name: main
nodes:
- name: "167.71.188.58"
labels: debian-buster
host-key: "actual-host-key-goes-here"
# Probably commented out because I couldn't get it to work:
host-key-checking: false
python-path: /usr/bin/python3
username: root
```
### Individual Projects
Individual projects work essentially the same way `zuul-config` does: A
`.zuul.yaml` or a `.zuul.d/` is written to define jobs, which run Ansible
playbooks, and these jobs are added to pipelines for the project.
As I understand it, all of this configuration is shared between all the
projects in a tenant - so a project can run playbooks from a different
project, for example.
Here's the `.zuul.yaml` I wrote for blubber:
```
brennen@lostsnail-0:~/blubber$ cat .zuul.yaml
- job:
name: blubber-build
run: playbooks/blubber-build.yaml
- job:
name: blubber-test
run: playbooks/blubber-test.yaml
- project:
check:
jobs:
- blubber-build
- blubber-test
gate:
jobs:
- blubber-build
- blubber-test
```
## Remaining Problems
We obviously don't want to run CI jobs as root on a continuously reused VM. In
principle, this is very solvable, but there is some work to be done.
[quick]: https://zuul-ci.org/docs/zuul/admin/quick-start.html
[scratch]: https://zuul-ci.org/docs/zuul/admin/zuul-from-scratch.html
[T218138]: https://phabricator.wikimedia.org/T218138
[docker-compose]: https://opendev.org/zuul/zuul/src/branch/master/doc/source/admin/examples/docker-compose.yaml
[example-conf]: https://opendev.org/zuul/zuul/src/branch/master/doc/source/admin/examples/
[zuul-jobs]: https://opendev.org/zuul/zuul-jobs

Loading…
Cancel
Save