Skip to content

chore: update provisioner tag documentation with suggestions from #12315 #12347

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 29, 2024
Merged

chore: update provisioner tag documentation with suggestions from #12315 #12347

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a65b90b
chore(coderd): add more test cases to TestAcquirer_MatchTags, generat…
johnstcn Feb 28, 2024
5ec3ed5
chore(docs): update provisioner tag documentation with suggestions fr…
johnstcn Feb 28, 2024
865b73a
rm unused func
johnstcn Feb 28, 2024
4f774df
address PR comments
johnstcn Feb 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
chore(docs): update provisioner tag documentation with suggestions from 
#12315
  • Loading branch information
@johnstcn
johnstcn committed Feb 28, 2024
commit 5ec3ed5ac87929e8a951ed1896e4cf3026cb7c50
88 changes: 53 additions & 35 deletions docs/admin/provisioners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,12 @@ 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
> tags automatically.
Provisioners can broadly be categorized by scope: `organization` or `user`.

### Organization-Scoped Provisioners

**Organization-scoped Provisioners** can pick up build jobs created by any user.
These provisioners always have tags `scope=organization owner=""`.
These provisioners always have the implicit tags `scope=organization owner=""`.

```shell
coder provisionerd start
Expand All @@ -62,10 +61,9 @@ 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.
user-tagged templates. Unlike the other provisioner types, any Coder user can
run user provisioners, but they have no impact unless there is at least one
other template with the `scope=user` provisioner tag.

```shell
coder provisionerd start \
Expand All @@ -80,59 +78,79 @@ coder templates push on-prem \
### Provisioner Tags

You can use **provisioner tags** to control which provisioners can pick up build
jobs from templates (and corresponding workspaces) with matching tags.
jobs from templates (and corresponding workspaces) with matching explicit tags.

Provisioners have two implicit tags: `scope` and `owner`. Coder sets these tags
automatically.

- Organization-scoped provisioners always have the implicit tags
`scope=organization owner=""`
- User-scoped provisioners always have the implicit tags
`scope=owner owner=<uuid>`

For example:

```shell
# Start a provisioner with the explicit tags
# environment=on_prem and datacenter=chicago
coder provisionerd start \
--tag environment=on_prem \
--tag data_center=chicago
--tag datacenter=chicago

# In another terminal, create/push
# a template that requires this provisioner
# a template that requires the explicit
# tag environment=on_prem
coder templates push on-prem \
--provisioner-tag environment=on_prem

# Or, match the provisioner exactly
# Or, match the provisioner's explicit tags exactly
coder templates push on-prem-chicago \
--provisioner-tag environment=on_prem \
--provisioner-tag data_center=chicago
--provisioner-tag datacenter=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,
1. The set of tags of the build job is a subset of the set of tags of the
provisioner.

This is illustrated in the below table:

| Provisioner Tags | Job Tags | Can run job? |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------ |
| `{"owner":"","scope":"organization"}` | `{"owner":"","scope":"organization"}` | true |
| `{"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 |
| `{"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 |
1. A 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.
1. If a job has any explicit tags, it can only run on a provisioner with those
explicit tags (the provisioner could have additional tags).

The external provisioner in the above example can run build jobs with tags:

- `environment=on_prem`
- `data_center=chicago`
- `datacenter=chicago`
- `environment=on_prem datacenter=chicago`
- `environment=cloud datacenter=chicago`
- `environment=on_prem datacenter=new_york`

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.

This is illustrated in the below table:

| Provisioner Tags | Job Tags | Can Run Job? |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ |
| scope=organization owner= | scope=organization owner= | ✅ |
| scope=organization owner= | scope=organization owner= environment=on-prem | ❌ |
| scope=organization owner= environment=on-prem | scope=organization owner= | ❌ |
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem | ✅ |
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem datacenter=chicago | ❌ |
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem | ✅ |
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem datacenter=chicago | ✅ |
| scope=owner owner=aaa | scope=organization owner= | ❌ |
| scope=owner owner=aaa | scope=owner owner=aaa | ✅ |
| scope=owner owner=aaa | scope=owner owner=bbb | ❌ |
| scope=organization owner= | scope=owner owner=aaa | ❌ |
| scope=organization owner= | scope=owner owner=aaa environment=on-prem | ❌ |
| scope=owner owner=aaa environment=on-prem | scope=owner owner=aaa | ✅ |
| scope=owner owner=aaa | scope=owner owner=aaa environment=on-prem | ❌ |
| scope=owner owner=aaa environment=on-prem | scope=owner owner=aaa environment=on-prem | ✅ |
| scope=owner owner=aaa environment=on-prem datacenter=chicago | scope=owner owner=aaa environment=on-prem | ✅ |
| scope=owner owner=aaa environment=on-prem | scope=owner owner=aaa environment=on-prem datacenter=chicago | ❌ |
| scope=owner owner=aaa environment=on-prem datacenter=chicago | scope=owner owner=aaa environment=on-prem datacenter=chicago | ✅ |
| scope=owner owner=aaa environment=on-prem datacenter=chicago | scope=owner owner=aaa environment=on-prem datacenter=new_york | ❌ |

## Example: Running an external provisioner with Helm

Coder provides a Helm chart for running external provisioner daemons, which you
Expand Down