- Notifications
You must be signed in to change notification settings - Fork928
chore(docs): update external provisioners documentation#12315
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Changes fromall commits
File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -47,50 +47,91 @@ the [Helm example](#example-running-an-external-provisioner-with-helm) below. | ||
| ## Types of provisioners | ||
| > Provisioners have two important tags: `scope` and `owner`. Coder sets these | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I'm not sure "important" is the right word. Maybe There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Yeah "explicit" vs "implicit" is good wording. | ||
| > tags automatically. | ||
| ### Organization-Scoped Provisioners | ||
| **Organization-scoped Provisioners** can pick up build jobs created by any user. | ||
| These provisioners always have tags `scope=organization owner=""`. | ||
| ```shell | ||
| coder provisionerd start | ||
| ``` | ||
| ### User-scoped Provisioners | ||
| **User-scoped Provisioners** can only pick up build jobs created from | ||
| user-tagged templates. User-scoped provisioners always have tags | ||
| `scope=owner owner=<uuid>`. Unlike the other provisioner types, any Coder user | ||
| can run user provisioners, but they have no impact unless there is at least one | ||
| template with the `scope=user` provisioner tag. | ||
| ```shell | ||
| coder provisionerd start \ | ||
| --tag scope=user | ||
| # In another terminal, create/push | ||
| # a template that requires user provisioners | ||
| coder templates push on-prem \ | ||
| --provisioner-tag scope=user | ||
| ``` | ||
| ### Provisioner Tags | ||
| You can use **provisioner tags** to control which provisioners can pick up build | ||
| jobs from templates (and corresponding workspaces) with matching tags. | ||
| ```shell | ||
| coder provisionerd start \ | ||
| --tag environment=on_prem \ | ||
| --tag data_center=chicago | ||
| # In another terminal, create/push | ||
| # a template that requires this provisioner | ||
| coder templates push on-prem \ | ||
| --provisioner-tag environment=on_prem | ||
| # Or, match the provisioner exactly | ||
| coder templates push on-prem-chicago \ | ||
| --provisioner-tag environment=on_prem \ | ||
| --provisioner-tag data_center=chicago | ||
| ``` | ||
| A provisioner can run a given build job if one of the below is true: | ||
| 1. The provisioner and job tags are both organization-scoped and both have no | ||
| additional tags set, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. What if the job is user-scoped and has no additional tags set? Can it run on a user-scoped provisioner that has tags? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Yes, it currently can. There's no extra special-casing for user-scoped provisioners. | ||
| 1. The set of tags of the build job is a subset of the set of tags of the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. This makes it sound like if the job is organization scoped with no further tags it can run on any org-scoped provisioner. I thought such a job can only run on an org-scoped provisioner with no further tags? The way I would explain it is that An job with no explicit tags can only be run on a provisioner with no explicit tags. This way you can introduce tagging into your deployment without disrupting existing provisioners and jobs. If a job has any explicit tags, it can only run on a provisioner with those explicit tags (the provisioner could have additional tags). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. | ||
| provisioner. | ||
| This is illustrated in the below table: | ||
| | Provisioner Tags | Job Tags | Can run job? | | ||
| | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------ | | ||
| | `{"owner":"","scope":"organization"}` | `{"owner":"","scope":"organization"}` | true | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I think these would be easier to read if it was just in | ||
| | `{"owner":"","scope":"organization"}` | `{"environment":"on_prem","owner":"","scope":"organization"}` | false | | ||
| | `{"environment":"on_prem","owner":"","scope":"organization"}` | `{"owner":"","scope":"organization"}` | false | | ||
| | `{"environment":"on_prem","owner":"","scope":"organization"}` | `{"foo":"bar","owner":"","scope":"organization"}` | true | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. shouldn't this be There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Good catch. I updated this to be auto-generated#12347 | ||
| | `{"environment":"on_prem","owner":"","scope":"organization"}` | `{"data_center":"chicago","foo":"bar","owner":"","scope":"organization"}` | false | | ||
| | `{"data_center":"chicago","environment":"on_prem","owner":"","scope":"organization"}` | `{"foo":"bar","owner":"","scope":"organization"}` | true | | ||
| | `{"data_center":"chicago","environment":"on_prem","owner":"","scope":"organization"}` | `{"data_center":"chicago","foo":"bar","owner":"","scope":"organization"}` | true | | ||
| | `{"owner":"aaa","scope":"owner"}` | `{"owner":"","scope":"organization"}` | false | | ||
| | `{"owner":"aaa","scope":"owner"}` | `{"owner":"aaa","scope":"owner"}` | true | | ||
| | `{"owner":"aaa","scope":"owner"}` | `{"owner":"bbb","scope":"owner"}` | false | | ||
| | `{"owner":"","scope":"organization"}` | `{"owner":"aaa","scope":"owner"}` | false | | ||
| The external provisioner in the above example can run build jobs with tags: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. which is the above example? The one on line 86? If so, this should be moved to before the table | ||
| - `environment=on_prem` | ||
| - `data_center=chicago` | ||
| - `environment=on_prem datacenter=chicago` | ||
| - `environment=cloud datacenter=chicago` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. it shouldn't be able to run | ||
| - `environment=on_prem datacenter=new_york` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. if the provisioner has a | ||
| However, it will not pick up any build jobs that do not have either of the | ||
| `environment` or `datacenter` tags set. It will also not pick up any build jobs | ||
| from templates with the `user` tag set. | ||
| ## Example: Running an external provisioner with Helm | ||