Docs: reformat tenant config docs

Change-Id: If749e43b21f11144e8b8fdbd90558247e7e9905c
This commit is contained in:
James E. Blair 2017-08-04 09:29:45 -07:00
parent 9b0d277270
commit b4eab9274d
1 changed files with 134 additions and 99 deletions

View File

@ -5,128 +5,163 @@
Tenant Configuration
====================
After *zuul.conf* is configured, Zuul component servers will be able
After ``zuul.conf`` is configured, Zuul component servers will be able
to start, but a tenant configuration is required in order for Zuul to
perform any actions. The tenant configuration file specifies upon
which projects Zuul should operate. These repositories are
grouped into tenants. The configuration of each tenant is separate
from the rest (no pipelines, jobs, etc are shared between them).
which projects Zuul should operate. These repositories are grouped
into tenants. The configuration of each tenant is separate from the
rest (no pipelines, jobs, etc are shared between them).
A project may appear in more than one tenant; this may be useful if
you wish to use common job definitions across multiple tenants.
The tenant configuration file is specified by the *tenant_config*
setting in the *scheduler* section of *zuul.yaml*. It is a YAML file
which, like other Zuul configuration files, is a list of configuration
objects, though only one type of object is supported, *tenant*.
The tenant configuration file is specified by the
:attr:`scheduler.tenant_config` setting in ``zuul.conf``. It is a
YAML file which, like other Zuul configuration files, is a list of
configuration objects, though only one type of object is supported:
``tenant``.
Tenant
------
A tenant is a collection of projects which share a Zuul
configuration. An example tenant definition is::
configuration. An example tenant definition is:
- tenant:
name: my-tenant
max-nodes-per-job: 5
exclude-unprotected-branches: false
source:
gerrit:
config-projects:
- common-config
- shared-jobs:
include: job
untrusted-projects:
- zuul-jobs:
shadow: common-config
- project1
- project2:
exclude-unprotected-branches: true
.. code-block:: yaml
The following attributes are supported:
- tenant:
name: my-tenant
max-nodes-per-job: 5
exclude-unprotected-branches: false
source:
gerrit:
config-projects:
- common-config
- shared-jobs:
include: job
untrusted-projects:
- zuul-jobs:
shadow: common-config
- project1
- project2:
exclude-unprotected-branches: true
**name** (required)
The name of the tenant. This may appear in URLs, paths, and
monitoring fields, and so should be restricted to URL friendly
characters (ASCII letters, numbers, hyphen and underscore) and you
should avoid changing it unless necessary.
.. attr:: tenant
**max-nodes-per-job** (optional)
The maximum number of nodes a job can request, default to 5.
A '-1' value removes the limit.
The following attributes are supported:
**exclude-unprotected-branches** (optional)
When using a branch and pull model on a shared github repository there are
usually one or more protected branches which are gated and a dynamic number of
personal/feature branches which are the source for the pull requests. These
branches can potentially include broken zuul config and therefore break the
global tenant wide configuration. In order to deal with this zuul's operations
can be limited to the protected branches which are gated. This is a tenant
wide setting and can be overridden per project. If not specified, defaults
to ``false``.
.. attr:: name
:required:
**source** (required)
A dictionary of sources to consult for projects. A tenant may
contain projects from multiple sources; each of those sources must
be listed here, along with the projects it supports. The name of a
:ref:`connection<connections>` is used as the dictionary key
(e.g. `gerrit` in the example above), and the value is a further
dictionary containing the keys below.
The name of the tenant. This may appear in URLs, paths, and
monitoring fields, and so should be restricted to URL friendly
characters (ASCII letters, numbers, hyphen and underscore) and
you should avoid changing it unless necessary.
**config-projects**
A list of projects to be treated as config projects in this
tenant. The jobs in a config project are trusted, which means
they run with extra privileges, do not have their configuration
dynamically loaded for proposed changes, and zuul.yaml files are
only searched for in the master branch.
.. attr:: source
:required:
**untrusted-projects**
A list of projects to be treated as untrusted in this tenant. An
untrusted project is the typical project operated on by Zuul.
Their jobs run in a more restrictive environment, they may not
define pipelines, their configuration dynamically changes in
response to proposed changes, Zuul will read configuration files
in all of their branches.
A dictionary of sources to consult for projects. A tenant may
contain projects from multiple sources; each of those sources
must be listed here, along with the projects it supports. The
name of a :ref:`connection<connections>` is used as the
dictionary key (e.g. ``gerrit`` in the example above), and the
value is a further dictionary containing the keys below.
Each of the projects listed may be either a simple string value, or
it may be a dictionary with the following keys:
The next two attributes, **config-projects** and
**untrusted-projects** provide the bulk of the information for
tenant configuration. They list all of the projects upon which
Zuul will act.
**include**
Normally Zuul will load all of the configuration classes
appropriate for the type of project (config or untrusted) in
question. However, if you only want to load some items, the
*include* attribute can be used to specify that *only* the
specified classes should be loaded. Supplied as a string, or a
list of strings.
The order of the projects listed in a tenant is important. A job
which is defined in one project may not be redefined in another
project; therefore, once a job appears in one project, a project
listed later will be unable to define a job with that name.
Further, some aspects of project configuration (such as the merge
mode) may only be set on the first appearance of a project
definition.
**exclude**
A list of configuration classes that should not be loaded.
Zuul loads the configuration from all **config-projects** in the
order listed, followed by all **untrusted-projects** in order.
**shadow**
A list of projects which this project is permitted to shadow.
Normally, only one project in Zuul may contain definitions for a
given job. If a project earlier in the configuration defines a
job which a later project redefines, the later definition is
considered an error and is not permitted. The "shadow" attribute
of a project indicates that job definitions in this project which
conflict with the named projects should be ignored, and those in
the named project should be used instead. The named projects must
still appear earlier in the configuration. In the example above,
if a job definition appears in both the "common-config" and
"zuul-jobs" projects, the definition in "common-config" will be
used.
.. attr:: config-projects
**exclude-unprotected-branches**
Define if unprotected github branches should be processed. Defaults to the
tenant wide setting of exclude-unprotected-branches.
A list of projects to be treated as :term:`config projects
<config-project>` in this tenant. The jobs in a config project
are trusted, which means they run with extra privileges, do not
have their configuration dynamically loaded for proposed
changes, and Zuul config files are only searched for in the
``master`` branch.
The order of the projects listed in a tenant is important. A job
which is defined in one project may not be redefined in another
project; therefore, once a job appears in one project, a project
listed later will be unable to define a job with that name.
Further, some aspects of project configuration (such as the merge
mode) may only be set on the first appearance of a project
definition.
The items in the list follow the same format described in
**untrusted-projects**.
Zuul loads the configuration from all *config-projects* in the order
listed, followed by all *trusted-projects* in order.
.. attr:: untrusted-projects
A list of projects to be treated as untrusted in this tenant.
An :term:`untrusted-project` is the typical project operated on
by Zuul. Their jobs run in a more restrictive environment, they
may not define pipelines, their configuration dynamically
changes in response to proposed changes, and Zuul will read
configuration files in all of their branches.
.. attr:: <project>:
The items in the list may either be simple string values of
the project names, or a dictionary with the project name as
key and the following values:
.. attr:: include
Normally Zuul will load all of the configuration classes
appropriate for the type of project (config or untrusted)
in question. However, if you only want to load some
items, the **include** attribute can be used to specify
that *only* the specified classes should be loaded.
Supplied as a string, or a list of strings.
.. attr:: exclude
A list of configuration classes that should not be loaded.
.. attr:: shadow
A list of projects which this project is permitted to
shadow. Normally, only one project in Zuul may contain
definitions for a given job. If a project earlier in the
configuration defines a job which a later project
redefines, the later definition is considered an error and
is not permitted. The **shadow** attribute of a project
indicates that job definitions in this project which
conflict with the named projects should be ignored, and
those in the named project should be used instead. The
named projects must still appear earlier in the
configuration. In the example above, if a job definition
appears in both the ``common-config`` and ``zuul-jobs``
projects, the definition in ``common-config`` will be
used.
.. attr:: exclude-unprotected-branches
Define if unprotected github branches should be
processed. Defaults to the tenant wide setting of
exclude-unprotected-branches.
.. attr:: max-nodes-per-job
:default: 5
The maximum number of nodes a job can request. A value of
'-1' value removes the limit.
.. attr:: exclude-unprotected-branches
:default: false
When using a branch and pull model on a shared GitHub repository
there are usually one or more protected branches which are gated
and a dynamic number of personal/feature branches which are the
source for the pull requests. These branches can potentially
include broken Zuul config and therefore break the global tenant
wide configuration. In order to deal with this Zuul's operations
can be limited to the protected branches which are gated. This
is a tenant wide setting and can be overridden per project.
This currently only affects GitHub projects.