From b4eab9274dcea97aa741a9b0030f593c1709b10c Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Fri, 4 Aug 2017 09:29:45 -0700 Subject: [PATCH] Docs: reformat tenant config docs Change-Id: If749e43b21f11144e8b8fdbd90558247e7e9905c --- doc/source/admin/tenants.rst | 233 ++++++++++++++++++++--------------- 1 file changed, 134 insertions(+), 99 deletions(-) diff --git a/doc/source/admin/tenants.rst b/doc/source/admin/tenants.rst index b3b2d9cef9..b518c913d8 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` 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` 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 + ` 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:: : + + 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.