Skip to content

chore(docs): fix inconsistencies in external provisioner docs #15416

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 7 commits into from
Nov 7, 2024
Merged

chore(docs): fix inconsistencies in external provisioner docs #15416

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f2680df
chore(docs): fix inconsistencies in external provisioner docs
johnstcn Nov 6, 2024
919aaaf
fixup! chore(docs): fix inconsistencies in external provisioner docs
johnstcn Nov 6, 2024
8c1964f
fixup! fixup! chore(docs): fix inconsistencies in external provisione…
johnstcn Nov 6, 2024
633899b
fixup! fixup! fixup! chore(docs): fix inconsistencies in external pro…
johnstcn Nov 6, 2024
938be05
fixup! fixup! fixup! fixup! chore(docs): fix inconsistencies in exter…
johnstcn Nov 6, 2024
f600308
make fmt
johnstcn Nov 6, 2024
f66a877
Update docs/admin/provisioners.md
bpmct Nov 7, 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
Next Next commit
chore(docs): fix inconsistencies in external provisioner docs
  • Loading branch information
@johnstcn
johnstcn committed Nov 6, 2024
commit f2680df0e8eeb7101993fecb5c1f438097d6ec10
10 changes: 7 additions & 3 deletions coderd/provisionerdserver/acquirer_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -523,8 +523,8 @@ func TestAcquirer_MatchTags(t *testing.T) {
// Generate a table that can be copy-pasted into docs/admin/provisioners.md
lines := []string{
"\n",
"| Provisioner Tags | Job Tags | Can Run Job? |",
"|------------------|----------|--------------|",
"| Provisioner Tags | Job Tags | Same Org | Can Run Job? |",
"|------------------|----------|----------|--------------|",
}
// turn the JSON map into k=v for readability
kvs := func(m map[string]string) string {
Expand All @@ -539,10 +539,14 @@ func TestAcquirer_MatchTags(t *testing.T) {
}
for _, tt := range testCases {
acquire := "✅"
sameOrg := "✅"
if !tt.expectAcquire {
acquire = "❌"
}
s := fmt.Sprintf("| %s | %s | %s |", kvs(tt.acquireJobTags), kvs(tt.provisionerJobTags), acquire)
if tt.unmatchedOrg {
sameOrg = "❌"
}
s := fmt.Sprintf("| %s | %s | %s | %s |", kvs(tt.acquireJobTags), kvs(tt.provisionerJobTags), sameOrg, acquire)
lines = append(lines, s)
}
t.Logf("You can paste this into docs/admin/provisioners.md")
Expand Down
98 changes: 42 additions & 56 deletions docs/admin/provisioners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,15 +178,17 @@ A provisioner can run a given build job if one of the below is true:
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:
The external provisioner in the above example can run build jobs in the same
organization with tags:

- `environment=on_prem`
- `datacenter=chicago`
- `environment=on_prem datacenter=chicago`

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 tag `scope=user` set.
from templates with the tag `scope=user` set, or build jobs from templates in
different organizations.

> [!NOTE] If you only run tagged provisioners, you will need to specify a set of
> tags that matches at least one provisioner for _all_ template import jobs and
Expand All @@ -198,34 +200,35 @@ from templates with the tag `scope=user` set.

This is illustrated in the below table:

| Provisioner Tags | Job Tags | Can Run Job? |
| ----------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ |
| scope=organization owner= | scope=organization owner= | ✅ |
| 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 | ✅ |
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem datacenter=chicago | ✅ |
| scope=user owner=aaa | scope=user owner=aaa | ✅ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa | ✅ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem | ✅ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem | ✅ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ |
| 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 datacenter=chicago | ❌ |
| scope=organization owner= environment=on-prem datacenter=new_york | scope=organization owner= environment=on-prem datacenter=chicago | ❌ |
| scope=user owner=aaa | scope=organization owner= | ❌ |
| scope=user owner=aaa | scope=user owner=bbb | ❌ |
| scope=organization owner= | scope=user owner=aaa | ❌ |
| scope=organization owner= | scope=user owner=aaa environment=on-prem | ❌ |
| scope=user owner=aaa | scope=user owner=aaa environment=on-prem | ❌ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem datacenter=chicago | ❌ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=new_york | ❌ |
| Provisioner Tags | Job Tags | Same Org | Can Run Job? |
| ----------------------------------------------------------------- | ---------------------------------------------------------------- | -------- | ------------ |
| scope=organization owner= | scope=organization owner= | ✅ | ✅ |
| 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 | ✅ | ✅ |
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem datacenter=chicago | ✅ | ✅ |
| scope=user owner=aaa | scope=user owner=aaa | ✅ | ✅ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa | ✅ | ✅ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem | ✅ | ✅ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem | ✅ | ✅ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ | ✅ |
| 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 datacenter=chicago | ✅ | ❌ |
| scope=organization owner= environment=on-prem datacenter=new_york | scope=organization owner= environment=on-prem datacenter=chicago | ✅ | ❌ |
| scope=user owner=aaa | scope=organization owner= | ✅ | ❌ |
| scope=user owner=aaa | scope=user owner=bbb | ✅ | ❌ |
| scope=organization owner= | scope=user owner=aaa | ✅ | ❌ |
| scope=organization owner= | scope=user owner=aaa environment=on-prem | ✅ | ❌ |
| scope=user owner=aaa | scope=user owner=aaa environment=on-prem | ✅ | ❌ |
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ | ❌ |
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=new_york | ✅ | ❌ |
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem | ❌ | ❌ |

> **Note to maintainers:** to generate this table, run the following command and
> copy the output:
>
> ```
> go test -v -count=1 ./coderd/provisionerserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
> go test -v -count=1 ./coderd/provisionerdserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
> ```

## Types of provisioners
Expand Down Expand Up @@ -270,12 +273,12 @@ template with the `scope=user` provisioner tag.

```sh
coder provisioner start \
--tag scope=user
--tag scope=user

# In another terminal, create/push
# a template that requires user provisioners
coder templates push on-prem \
--provisioner-tag scope=user
--provisioner-tag scope=user
```

## Example: Running an external provisioner with Helm
Expand All @@ -288,8 +291,7 @@ will use in concert with the Helm chart for deploying the Coder server.
```sh
coder provisioner keys create my-cool-key --org default
# Optionally, you can specify tags for the provisioner key:
# coder provisioner keys create my-cool-key --org default --tags location=auh kind=k8s
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

review: --tags is incorrect -> --tag A --tag B

```
# coder provisioner keys create my-cool-key --org default --tag location=auh --tag kind=k8s

Successfully created provisioner key kubernetes-key! Save this authentication
token, it will not be shown again.
Expand All @@ -300,25 +302,7 @@ will use in concert with the Helm chart for deploying the Coder server.
1. Store the key in a kubernetes secret:

```sh
kubectl create secret generic coder-provisioner-psk --from-literal=key1=`<key omitted>`
```

1. Modify your Coder `values.yaml` to include

```yaml
provisionerDaemon:
keySecretName: "coder-provisioner-keys"
keySecretKey: "key1"
```

1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit
`--version <your version>` to also upgrade Coder to the latest version.

```sh
helm upgrade coder coder-v2/coder \
--namespace coder \
--version <your version> \
--values values.yaml
Comment on lines -306 to -321
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

review: this is no longer required when using provisioner keys, removed.

kubectl create secret generic coder-provisioner-psk --from-literal=my-cool-key=`<key omitted>`
```

1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm
Expand All @@ -331,13 +315,15 @@ will use in concert with the Helm chart for deploying the Coder server.
value: "https://coder.example.com"
replicaCount: 10
provisionerDaemon:
# NOTE: in some versions of the Helm chart, it is required to set this to an empty string.
pskSecretName: ""
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

review: PR to address this workaround is here: #15417

keySecretName: "coder-provisioner-keys"
keySecretKey: "key1"
keySecretKey: "my-cool-key"
```

This example creates a deployment of 10 provisioner daemons (for 10
concurrent builds) with the listed tags. For generic provisioners, remove the
tags.
concurrent builds) authenticating using the above key. The daemons will
authenticate using tags fetched directly from the key.

> Refer to the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml)
Expand Down Expand Up @@ -370,11 +356,11 @@ coder provisioner start

```sh
docker run --rm -it \
-e CODER_URL=https://coder.example.com/ \
-e CODER_SESSION_TOKEN=your_token \
--entrypoint /opt/coder \
ghcr.io/coder/coder:latest \
provisioner start
-e CODER_URL=https://coder.example.com/ \
-e CODER_SESSION_TOKEN=your_token \
--entrypoint /opt/coder \
ghcr.io/coder/coder:latest \
provisioner start
```

## Disable built-in provisioners
Expand Down