blob: a1709a6f3d513176d4bea2c0164c7712134b7ccb [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Tenant Configuration
2
3.. _tenant-config:
4
5Tenant Configuration
6====================
7
James E. Blairb4eab922017-08-04 09:29:45 -07008After ``zuul.conf`` is configured, Zuul component servers will be able
James E. Blaireff5a9d2017-06-20 00:00:37 -07009to start, but a tenant configuration is required in order for Zuul to
10perform any actions. The tenant configuration file specifies upon
James E. Blairb4eab922017-08-04 09:29:45 -070011which projects Zuul should operate. These repositories are grouped
12into tenants. The configuration of each tenant is separate from the
13rest (no pipelines, jobs, etc are shared between them).
James E. Blaireff5a9d2017-06-20 00:00:37 -070014
15A project may appear in more than one tenant; this may be useful if
16you wish to use common job definitions across multiple tenants.
17
James E. Blairb4eab922017-08-04 09:29:45 -070018The tenant configuration file is specified by the
19:attr:`scheduler.tenant_config` setting in ``zuul.conf``. It is a
20YAML file which, like other Zuul configuration files, is a list of
21configuration objects, though only one type of object is supported:
22``tenant``.
James E. Blaireff5a9d2017-06-20 00:00:37 -070023
24Tenant
25------
26
27A tenant is a collection of projects which share a Zuul
James E. Blairb4eab922017-08-04 09:29:45 -070028configuration. An example tenant definition is:
James E. Blaireff5a9d2017-06-20 00:00:37 -070029
James E. Blairb4eab922017-08-04 09:29:45 -070030.. code-block:: yaml
James E. Blaireff5a9d2017-06-20 00:00:37 -070031
James E. Blairb4eab922017-08-04 09:29:45 -070032 - tenant:
33 name: my-tenant
34 max-nodes-per-job: 5
35 exclude-unprotected-branches: false
36 source:
37 gerrit:
38 config-projects:
39 - common-config
40 - shared-jobs:
41 include: job
42 untrusted-projects:
43 - zuul-jobs:
44 shadow: common-config
45 - project1
46 - project2:
47 exclude-unprotected-branches: true
James E. Blaireff5a9d2017-06-20 00:00:37 -070048
James E. Blairb4eab922017-08-04 09:29:45 -070049.. attr:: tenant
James E. Blaireff5a9d2017-06-20 00:00:37 -070050
James E. Blairb4eab922017-08-04 09:29:45 -070051 The following attributes are supported:
Tristan Cacqueray82f864b2017-08-01 05:54:42 +000052
James E. Blairb4eab922017-08-04 09:29:45 -070053 .. attr:: name
54 :required:
Tobias Henkeleca46202017-08-02 20:27:10 +020055
James E. Blairb4eab922017-08-04 09:29:45 -070056 The name of the tenant. This may appear in URLs, paths, and
57 monitoring fields, and so should be restricted to URL friendly
58 characters (ASCII letters, numbers, hyphen and underscore) and
59 you should avoid changing it unless necessary.
James E. Blaireff5a9d2017-06-20 00:00:37 -070060
James E. Blairb4eab922017-08-04 09:29:45 -070061 .. attr:: source
62 :required:
James E. Blaireff5a9d2017-06-20 00:00:37 -070063
James E. Blairb4eab922017-08-04 09:29:45 -070064 A dictionary of sources to consult for projects. A tenant may
65 contain projects from multiple sources; each of those sources
66 must be listed here, along with the projects it supports. The
67 name of a :ref:`connection<connections>` is used as the
68 dictionary key (e.g. ``gerrit`` in the example above), and the
69 value is a further dictionary containing the keys below.
James E. Blaireff5a9d2017-06-20 00:00:37 -070070
James E. Blairb4eab922017-08-04 09:29:45 -070071 The next two attributes, **config-projects** and
72 **untrusted-projects** provide the bulk of the information for
73 tenant configuration. They list all of the projects upon which
74 Zuul will act.
James E. Blaireff5a9d2017-06-20 00:00:37 -070075
James E. Blairb4eab922017-08-04 09:29:45 -070076 The order of the projects listed in a tenant is important. A job
77 which is defined in one project may not be redefined in another
78 project; therefore, once a job appears in one project, a project
79 listed later will be unable to define a job with that name.
80 Further, some aspects of project configuration (such as the merge
81 mode) may only be set on the first appearance of a project
82 definition.
James E. Blaireff5a9d2017-06-20 00:00:37 -070083
James E. Blairb4eab922017-08-04 09:29:45 -070084 Zuul loads the configuration from all **config-projects** in the
85 order listed, followed by all **untrusted-projects** in order.
James E. Blaireff5a9d2017-06-20 00:00:37 -070086
James E. Blairb4eab922017-08-04 09:29:45 -070087 .. attr:: config-projects
James E. Blair4b42e362017-07-13 13:52:22 -070088
James E. Blairb4eab922017-08-04 09:29:45 -070089 A list of projects to be treated as :term:`config projects
90 <config-project>` in this tenant. The jobs in a config project
91 are trusted, which means they run with extra privileges, do not
92 have their configuration dynamically loaded for proposed
93 changes, and Zuul config files are only searched for in the
94 ``master`` branch.
Tobias Henkeleca46202017-08-02 20:27:10 +020095
James E. Blairb4eab922017-08-04 09:29:45 -070096 The items in the list follow the same format described in
97 **untrusted-projects**.
James E. Blaireff5a9d2017-06-20 00:00:37 -070098
James E. Blairb4eab922017-08-04 09:29:45 -070099 .. attr:: untrusted-projects
100
101 A list of projects to be treated as untrusted in this tenant.
102 An :term:`untrusted-project` is the typical project operated on
103 by Zuul. Their jobs run in a more restrictive environment, they
104 may not define pipelines, their configuration dynamically
105 changes in response to proposed changes, and Zuul will read
106 configuration files in all of their branches.
107
108 .. attr:: <project>:
109
110 The items in the list may either be simple string values of
111 the project names, or a dictionary with the project name as
112 key and the following values:
113
114 .. attr:: include
115
116 Normally Zuul will load all of the configuration classes
117 appropriate for the type of project (config or untrusted)
118 in question. However, if you only want to load some
119 items, the **include** attribute can be used to specify
120 that *only* the specified classes should be loaded.
121 Supplied as a string, or a list of strings.
122
123 .. attr:: exclude
124
125 A list of configuration classes that should not be loaded.
126
127 .. attr:: shadow
128
129 A list of projects which this project is permitted to
130 shadow. Normally, only one project in Zuul may contain
131 definitions for a given job. If a project earlier in the
132 configuration defines a job which a later project
133 redefines, the later definition is considered an error and
134 is not permitted. The **shadow** attribute of a project
135 indicates that job definitions in this project which
136 conflict with the named projects should be ignored, and
137 those in the named project should be used instead. The
138 named projects must still appear earlier in the
139 configuration. In the example above, if a job definition
140 appears in both the ``common-config`` and ``zuul-jobs``
141 projects, the definition in ``common-config`` will be
142 used.
143
144 .. attr:: exclude-unprotected-branches
145
146 Define if unprotected github branches should be
147 processed. Defaults to the tenant wide setting of
148 exclude-unprotected-branches.
149
150 .. attr:: max-nodes-per-job
151 :default: 5
152
153 The maximum number of nodes a job can request. A value of
154 '-1' value removes the limit.
155
156 .. attr:: exclude-unprotected-branches
157 :default: false
158
159 When using a branch and pull model on a shared GitHub repository
160 there are usually one or more protected branches which are gated
161 and a dynamic number of personal/feature branches which are the
162 source for the pull requests. These branches can potentially
163 include broken Zuul config and therefore break the global tenant
164 wide configuration. In order to deal with this Zuul's operations
165 can be limited to the protected branches which are gated. This
166 is a tenant wide setting and can be overridden per project.
167 This currently only affects GitHub projects.
James E. Blair2bab6e72017-08-07 09:52:45 -0700168
169 .. attr:: default-parent
170 :default: base
171
172 If a job is defined without an explicit :attr:`job.parent`
173 attribute, this job will be configured as the job's parent.
174 This allows an administrator to configure a default base job to
175 implement local policies such as node setup and artifact
176 publishing.