zuul
/
zuul
Code Issues Proposed changes

Add more explanatory text to zuul-from-scratch 

Change-Id: I489fcb06d36998ba4287ce45fef1064fe6f2a3c3
This commit is contained in:
James E. Blair 2018-05-18 11:04:35 -07:00
parent 9dee755bb1
commit ebb4c4a6be
9 changed files with 92 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/source/admin/centos7_setup.rst
View File

@ -8,8 +8,8 @@ We're going to be using CentOS 7 on a cloud server for this installation.
Prerequisites
-------------
- Port 9000 must be open and accessible from the internet so that
Github can communicate with the Zuul web service.
- Port 9000 must be open and accessible from the Internet so that
GitHub can communicate with the Zuul web service.
Login to your environment
-------------------------
@ -35,6 +35,12 @@ The repositories and the packages installed from those are listed below.
* ius-release: python35u, python35u-pip, python35u-devel
* bigtop: zookeeper
First, make sure the system packages are up to date, and then install
some packages which will be required later. Most of Zuul's binary
dependencies are handled by the bindep program, but a few additional
dependencies are needed to install bindep, and for other commands
which we will use in these instructions.
.. code-block:: console
$ sudo yum update -y
@ -48,6 +54,10 @@ The repositories and the packages installed from those are listed below.
Install Zookeeper
-----------------
Nodepool uses Zookeeper to keep track of information about the
resources it manages, and it's also how Zuul makes requests to
Nodepool for nodes.
.. code-block:: console
$ sudo bash -c "cat << EOF > /etc/yum.repos.d/bigtop.repo

14
doc/source/admin/fedora27_setup.rst
View File

@ -8,8 +8,8 @@ We're going to be using Fedora 27 on a cloud server for this installation.
Prerequisites
-------------
- Port 9000 must be open and accessible from the internet so that
Github can communicate with the Zuul web service.
- Port 9000 must be open and accessible from the Internet so that
GitHub can communicate with the Zuul web service.
Login to your environment
-------------------------
@ -25,6 +25,12 @@ To get started, ssh to your machine as the ``fedora`` user::
Environment Setup
-----------------
First, make sure the system packages are up to date, and then install
some packages which will be required later. Most of Zuul's binary
dependencies are handled by the bindep program, but a few additional
dependencies are needed to install bindep, and for other commands
which we will use in these instructions.
::
sudo dnf update -y
@ -35,6 +41,10 @@ Environment Setup
Install Zookeeper
-----------------
Nodepool uses Zookeeper to keep track of information about the
resources it manages, and it's also how Zuul makes requests to
Nodepool for nodes.
::
sudo dnf install zookeeper -y

50
doc/source/admin/gerrit_setup.rst
View File

@ -6,44 +6,52 @@ Gerrit
Installation
------------
Gerrit can be downloaded from the `Gerrit Code Review <https:///www.gerritcodereview.com>`_ web site, and also contains Gerrit documentation with
installation instructions.
Gerrit can be downloaded from the `Gerrit Code Review
<https:///www.gerritcodereview.com>`_ web site, and also contains
Gerrit documentation with installation instructions.
Create a Zuul User
------------------
The Gerrit documentation walks you through adding a first user, which will
end up being the admin user. Once the admin user is created, and SSH access
has been setup for that user, you can use that account to create a new 'zuul'
user. This user, which will be used by our Zuul installation, must have SSH
access to gerrit, and have the `stream-events <https://gerrit-review.googlesource.com/Documentation/access-control.html#global_capabilities>`_ ACL enabled.
The Gerrit documentation walks you through adding a first user, which
will end up being the admin user. Once the admin user is created, and
SSH access has been setup for that user, you can use that account to
create a new ``zuul`` user. This user, which will be used by our Zuul
installation, must have SSH access to gerrit, and have the
`stream-events <https://gerrit-review.googlesource.com/Documentation/access-control.html#global_capabilities>`_
ACL enabled.
As the admin user, create the 'zuul' user, and import an SSH key for 'zuul'::
.. TODO: Instructions to create the ssh key used here
As the admin user, create the ``zuul`` user, and import an SSH key for ``zuul``::
$ cat $PUBKEY | ssh -p 29418 $USER@localhost gerrit create-account \
--group "'Registered Users'" --ssh-key - zuul
`$PUBKEY` is the location of the SSH public key for the 'zuul' user. `$USER` is
the username for the admin user.
``$PUBKEY`` is the location of the SSH public key for the ``zuul``
user. ``$USER`` is the username for the admin user.
The 'zuul' user should now be able to stream events::
The ``zuul`` user should now be able to stream events::
$ ssh -p 29418 zuul@localhost gerrit stream-events
Configure Gerrit
----------------
The 'zuul' user (and any other users you may create, for that matter) will
need to be able to leave review votes on any project hosted in your Gerrit.
This is done with the use of Gerrit `Review Labels <https://gerrit-review.googlesource.com/Documentation/access-control.html#category_review_labels>`_.
You may need to add the proper label permissions to the All-Projects project,
which defines ACLs that all other projects will inherit.
The ``zuul`` user (and any other users you may create, for that
matter) will need to be able to leave review votes on any project
hosted in your Gerrit. This is done with the use of Gerrit
`Review Labels <https://gerrit-review.googlesource.com/Documentation/access-control.html#category_review_labels>`_.
You may need to add the proper label permissions to the ``All-Projects``
project, which defines ACLs that all other projects will inherit.
Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your Gerrit lets
you see the current access permissions. In the ``Reference: refs/heads/*``
section, you will need to add a permisson for the `Label Code-Review` for
the `Registered Users` group (we added the 'zuul' user to this group when we
created it).
.. TODO: Instructions to create a Verified label?
Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your
Gerrit lets you see the current access permissions. In the
``Reference: refs/heads/*`` section, you will need to add a permisson
for the ``Label Code-Review`` for the ``Registered Users`` group (we
added the ``zuul`` user to this group when we created it).
.. note:: The label you configure here must match the label referenced in
your Zuul pipeline definitions. We've chosen the Code-Review label

17
doc/source/admin/github_setup.rst
View File

@ -6,8 +6,11 @@ GitHub
Configure GitHub
----------------
You'll need an organization in Github for this, so create one if you
haven't already. In this example we will use `my-org`.
The recommended way to use Zuul with GitHub is by creating a GitHub
App. This allows you to easily add it to GitHub projects, and reduces
the likelihood of running into GitHub rate limits. You'll need an
organization in Github for this, so create one if you haven't already.
In this example we will use `my-org`.
.. NOTE Duplicate content here and in drivers/github.rst. Keep them
in sync.
@ -83,8 +86,8 @@ configured.
Create two new repositories in your org. One will hold the
configuration for this tenant in Zuul, the other should be a normal
project repo to use for testing. We'll call them `zuul-test-config`
and `zuul-test`, respectively.
project repo to use for testing. We'll call them ``zuul-test-config``
and ``zuul-test``, respectively.
Visit the public app page on GitHub,
https://github.com/apps/my-org-zuul, and install the app into your org.
@ -105,9 +108,9 @@ Edit ``/etc/zuul/main.yaml`` so that it looks like this::
untrusted-projects:
- my-org/zuul-test
The first section, under 'zuul-git' imports the "standard library" of
Zuul jobs, a collection of jobs that can be used by any Zuul
installation.
The first section, under ``zuul-git`` imports the standard library of
Zuul jobs that we configured earlier. This adds a number of jobs that
you can immediately use in your Zuul installation.
The second section is your GitHub configuration.

8
doc/source/admin/nodepool_install.rst
View File

@ -6,6 +6,10 @@ Install Nodepool
Initial Setup
-------------
First we'll create the nodepool user and set up some directories it
needs. We also need to create an SSH key for Zuul to use when it logs
into the nodes that Nodepool provides.
.. code-block:: console
$ sudo adduser --system nodepool --home-dir /var/lib/nodepool --create-home
@ -18,6 +22,10 @@ Initial Setup
Installation
------------
Clone the Nodepool git repository and install it. The ``bindep``
program is used to determine any additional binary dependencies which
are required.
.. code-block:: console
$ git clone https://git.zuul-ci.org/nodepool

5
doc/source/admin/nodepool_openstack.rst
View File

@ -8,7 +8,7 @@ Setup
Before starting on this, you need to download your `openrc`
configuration from your OpenStack cloud. Put it on your server in the
fedora user's home directory. It should be called
staging user's home directory. It should be called
``<username>-openrc.sh``. Once that is done, create a new keypair
that will be installed when instantiating the servers::
@ -41,7 +41,8 @@ have been filled out.
Configuration
-------------
Inputs needed for this file:
You'll need the following information in order to create the Nodepool
configuration file:
* cloud name / region name - from clouds.yaml
* flavor-name

5
doc/source/admin/nodepool_static.rst
View File

@ -26,7 +26,10 @@ the command::
Nodepool Configuration
----------------------
Below is a sample nodepool.yaml file that sets up static nodes::
Below is a sample Nodepool configuration file that sets up static
nodes. Place this file in ``/etc/nodepool/nodepool.yaml``.
::
zookeeper-servers:
- host: localhost

6
doc/source/admin/zuul-from-scratch.rst
View File

@ -88,6 +88,10 @@ start Nodepool and Zuul services with::
Use Zuul Jobs
-------------
Zuul provides a `standard library`_ of jobs and roles. To take advantage
of these jobs, add the ``zuul-jobs`` repo, which is hosted by the Zuul
project, to your system.
Add to ``/etc/zuul/zuul.conf``::
sudo bash -c "cat >> /etc/zuul/zuul.conf <<EOF
@ -102,6 +106,8 @@ Restart executor and scheduler::
sudo systemctl restart zuul-executor.service
sudo systemctl restart zuul-scheduler.service
.. _standard library: https://zuul-ci.org/docs/zuul-jobs/
Setup Your Repo
---------------

8
doc/source/admin/zuul_install.rst
View File

@ -6,6 +6,10 @@ Install Zuul
Initial Setup
-------------
First we'll create the zuul user and set up some directories it needs.
We'll also install the SSH private key that we previously created
during the Nodepool setup.
.. code-block:: console
$ sudo adduser --system zuul --home-dir /var/lib/zuul --create-home
@ -20,6 +24,10 @@ Initial Setup
Installation
------------
Clone the Zuul git repository and install it. The ``bindep`` program
is used to determine any additional binary dependencies which are
required.
.. code-block:: console
$ git clone https://git.zuul-ci.org/zuul