@@ -47,50 +47,91 @@ the [Helm example](#example-running-an-external-provisioner-with-helm) below.
4747
4848##Types of provisioners
4949
50- - ** Generic provisioners** can pick up any build job from templates without
51- provisioner tags.
52-
53- ``` shell
54- coder provisionerd start
55- ```
56-
57- - ** Tagged provisioners** can be used to pick up build jobs from templates (and
58- corresponding workspaces) with matching tags.
59-
60- ``` shell
61- coder provisionerd start \
62- --tag environment=on_prem \
63- --tag data_center=chicago
64-
65- # In another terminal, create/push
66- # a template that requires this provisioner
67- coder templates push on-prem \
68- --provisioner-tag environment=on_prem
69-
70- # Or, match the provisioner exactly
71- coder templates push on-prem-chicago \
72- --provisioner-tag environment=on_prem \
73- --provisioner-tag data_center=chicago
74- ```
75-
76- > At this time, tagged provisioners can also pick jobs from untagged
77- > templates. This behavior is
78- > [ subject to change] ( https://github.com/coder/coder/issues/6442 ) .
79-
80- - ** User provisioners** can only pick up jobs from user-tagged templates. Unlike
81- the other provisioner types, any Coder user can run user provisioners, but
82- they have no impact unless there is at least one template with the
83- ` scope=user ` provisioner tag.
84-
85- ``` shell
86- coder provisionerd start \
87- --tag scope=user
88-
89- # In another terminal, create/push
90- # a template that requires user provisioners
91- coder templates push on-prem \
92- --provisioner-tag scope=user
93- ```
50+ > Provisioners have two important tags:` scope ` and` owner ` . Coder sets these
51+ > tags automatically.
52+
53+ ###Organization-Scoped Provisioners
54+
55+ ** Organization-scoped Provisioners** can pick up build jobs created by any user.
56+ These provisioners always have tags` scope=organization owner="" ` .
57+
58+ ``` shell
59+ coder provisionerd start
60+ ```
61+
62+ ###User-scoped Provisioners
63+
64+ ** User-scoped Provisioners** can only pick up build jobs created from
65+ user-tagged templates. User-scoped provisioners always have tags
66+ ` scope=owner owner=<uuid> ` . Unlike the other provisioner types, any Coder user
67+ can run user provisioners, but they have no impact unless there is at least one
68+ template with the` scope=user ` provisioner tag.
69+
70+ ``` shell
71+ coder provisionerd start \
72+ --tag scope=user
73+
74+ # In another terminal, create/push
75+ # a template that requires user provisioners
76+ coder templates push on-prem \
77+ --provisioner-tag scope=user
78+ ```
79+
80+ ###Provisioner Tags
81+
82+ You can use** provisioner tags** to control which provisioners can pick up build
83+ jobs from templates (and corresponding workspaces) with matching tags.
84+
85+ ``` shell
86+ coder provisionerd start \
87+ --tag environment=on_prem \
88+ --tag data_center=chicago
89+
90+ # In another terminal, create/push
91+ # a template that requires this provisioner
92+ coder templates push on-prem \
93+ --provisioner-tag environment=on_prem
94+
95+ # Or, match the provisioner exactly
96+ coder templates push on-prem-chicago \
97+ --provisioner-tag environment=on_prem \
98+ --provisioner-tag data_center=chicago
99+ ```
100+
101+ A provisioner can run a given build job if one of the below is true:
102+
103+ 1 . The provisioner and job tags are both organization-scoped and both have no
104+ additional tags set,
105+ 1 . The set of tags of the build job is a subset of the set of tags of the
106+ provisioner.
107+
108+ This is illustrated in the below table:
109+
110+ | Provisioner Tags| Job Tags| Can run job?|
111+ | -------------------------------------------------------------------------------------| -------------------------------------------------------------------------| ------------|
112+ | ` {"owner":"","scope":"organization"} ` | ` {"owner":"","scope":"organization"} ` | true|
113+ | ` {"owner":"","scope":"organization"} ` | ` {"environment":"on_prem","owner":"","scope":"organization"} ` | false|
114+ | ` {"environment":"on_prem","owner":"","scope":"organization"} ` | ` {"owner":"","scope":"organization"} ` | false|
115+ | ` {"environment":"on_prem","owner":"","scope":"organization"} ` | ` {"foo":"bar","owner":"","scope":"organization"} ` | true|
116+ | ` {"environment":"on_prem","owner":"","scope":"organization"} ` | ` {"data_center":"chicago","foo":"bar","owner":"","scope":"organization"} ` | false|
117+ | ` {"data_center":"chicago","environment":"on_prem","owner":"","scope":"organization"} ` | ` {"foo":"bar","owner":"","scope":"organization"} ` | true|
118+ | ` {"data_center":"chicago","environment":"on_prem","owner":"","scope":"organization"} ` | ` {"data_center":"chicago","foo":"bar","owner":"","scope":"organization"} ` | true|
119+ | ` {"owner":"aaa","scope":"owner"} ` | ` {"owner":"","scope":"organization"} ` | false|
120+ | ` {"owner":"aaa","scope":"owner"} ` | ` {"owner":"aaa","scope":"owner"} ` | true|
121+ | ` {"owner":"aaa","scope":"owner"} ` | ` {"owner":"bbb","scope":"owner"} ` | false|
122+ | ` {"owner":"","scope":"organization"} ` | ` {"owner":"aaa","scope":"owner"} ` | false|
123+
124+ The external provisioner in the above example can run build jobs with tags:
125+
126+ - ` environment=on_prem `
127+ - ` data_center=chicago `
128+ - ` environment=on_prem datacenter=chicago `
129+ - ` environment=cloud datacenter=chicago `
130+ - ` environment=on_prem datacenter=new_york `
131+
132+ However, it will not pick up any build jobs that do not have either of the
133+ ` environment ` or` datacenter ` tags set. It will also not pick up any build jobs
134+ from templates with the` user ` tag set.
94135
95136##Example: Running an external provisioner with Helm
96137