Docs: reformat tenant config docs
Change-Id: If749e43b21f11144e8b8fdbd90558247e7e9905c
This commit is contained in:
parent
9b0d277270
commit
b4eab9274d
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue