Docs: reformat tenant config docs
Change-Id: If749e43b21f11144e8b8fdbd90558247e7e9905c
diff --git a/doc/source/admin/tenants.rst b/doc/source/admin/tenants.rst
index b3b2d9c..b518c91 100644
--- a/doc/source/admin/tenants.rst
+++ b/doc/source/admin/tenants.rst
@@ -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.