Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9f05b19

Browse files
johnstcnbpmct
johnstcn
and
bpmct
authored
chore(docs): fix inconsistencies in external provisioner docs (#15416)
This PR: - Updates the table in `docs/admin/provisioners.md` to include highlight multi-org changes - Updates the instructions for the provisionerd helm chart when using provisioner keys --------- Co-authored-by: Ben Potter <[email protected]>
1 parent 2d061e6 commit 9f05b19

File tree

2 files changed

+44
-52
lines changed

2 files changed

+44
-52
lines changed

‎coderd/provisionerdserver/acquirer_test.go

+7-3
Original file line numberDiff line numberDiff line change
@@ -523,8 +523,8 @@ func TestAcquirer_MatchTags(t *testing.T) {
523523
// Generate a table that can be copy-pasted into docs/admin/provisioners.md
524524
lines := []string{
525525
"\n",
526-
"| Provisioner Tags | Job Tags | Can Run Job? |",
527-
"|------------------|----------|--------------|",
526+
"| Provisioner Tags | Job Tags | Same Org | Can Run Job? |",
527+
"|------------------|----------|----------|--------------|",
528528
}
529529
// turn the JSON map into k=v for readability
530530
kvs := func(m map[string]string) string {
@@ -539,10 +539,14 @@ func TestAcquirer_MatchTags(t *testing.T) {
539539
}
540540
for _, tt := range testCases {
541541
acquire := "✅"
542+
sameOrg := "✅"
542543
if !tt.expectAcquire {
543544
acquire = "❌"
544545
}
545-
s := fmt.Sprintf("| %s | %s | %s |", kvs(tt.acquireJobTags), kvs(tt.provisionerJobTags), acquire)
546+
if tt.unmatchedOrg {
547+
sameOrg = "❌"
548+
}
549+
s := fmt.Sprintf("| %s | %s | %s | %s |", kvs(tt.acquireJobTags), kvs(tt.provisionerJobTags), sameOrg, acquire)
546550
lines = append(lines, s)
547551
}
548552
t.Logf("You can paste this into docs/admin/provisioners.md")

‎docs/admin/provisioners.md

+37-49
Original file line numberDiff line numberDiff line change
@@ -178,15 +178,17 @@ A provisioner can run a given build job if one of the below is true:
178178
1. If a job has any explicit tags, it can only run on a provisioner with those
179179
explicit tags (the provisioner could have additional tags).
180180

181-
The external provisioner in the above example can run build jobs with tags:
181+
The external provisioner in the above example can run build jobs in the same
182+
organization with tags:
182183

183184
- `environment=on_prem`
184185
- `datacenter=chicago`
185186
- `environment=on_prem datacenter=chicago`
186187

187188
However, it will not pick up any build jobs that do not have either of the
188189
`environment` or `datacenter` tags set. It will also not pick up any build jobs
189-
from templates with the tag `scope=user` set.
190+
from templates with the tag `scope=user` set, or build jobs from templates in
191+
different organizations.
190192

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

199201
This is illustrated in the below table:
200202

201-
| Provisioner Tags | Job Tags | Can Run Job? |
202-
| ----------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ |
203-
| scope=organization owner= | scope=organization owner= | ✅ |
204-
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem | ✅ |
205-
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem | ✅ |
206-
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem datacenter=chicago | ✅ |
207-
| scope=user owner=aaa | scope=user owner=aaa | ✅ |
208-
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa | ✅ |
209-
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem | ✅ |
210-
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem | ✅ |
211-
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ |
212-
| scope=organization owner= | scope=organization owner= environment=on-prem | ❌ |
213-
| scope=organization owner= environment=on-prem | scope=organization owner= | ❌ |
214-
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem datacenter=chicago | ❌ |
215-
| scope=organization owner= environment=on-prem datacenter=new_york | scope=organization owner= environment=on-prem datacenter=chicago | ❌ |
216-
| scope=user owner=aaa | scope=organization owner= | ❌ |
217-
| scope=user owner=aaa | scope=user owner=bbb | ❌ |
218-
| scope=organization owner= | scope=user owner=aaa | ❌ |
219-
| scope=organization owner= | scope=user owner=aaa environment=on-prem | ❌ |
220-
| scope=user owner=aaa | scope=user owner=aaa environment=on-prem | ❌ |
221-
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem datacenter=chicago | ❌ |
222-
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=new_york | ❌ |
203+
| Provisioner Tags | Job Tags | Same Org | Can Run Job? |
204+
| ----------------------------------------------------------------- | ---------------------------------------------------------------- | -------- | ------------ |
205+
| scope=organization owner= | scope=organization owner= | ✅ | ✅ |
206+
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem | ✅ | ✅ |
207+
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem | ✅ | ✅ |
208+
| scope=organization owner= environment=on-prem datacenter=chicago | scope=organization owner= environment=on-prem datacenter=chicago | ✅ | ✅ |
209+
| scope=user owner=aaa | scope=user owner=aaa | ✅ | ✅ |
210+
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa | ✅ | ✅ |
211+
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem | ✅ | ✅ |
212+
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem | ✅ | ✅ |
213+
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ | ✅ |
214+
| scope=organization owner= | scope=organization owner= environment=on-prem | ✅ | ❌ |
215+
| scope=organization owner= environment=on-prem | scope=organization owner= | ✅ | ❌ |
216+
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem datacenter=chicago | ✅ | ❌ |
217+
| scope=organization owner= environment=on-prem datacenter=new_york | scope=organization owner= environment=on-prem datacenter=chicago | ✅ | ❌ |
218+
| scope=user owner=aaa | scope=organization owner= | ✅ | ❌ |
219+
| scope=user owner=aaa | scope=user owner=bbb | ✅ | ❌ |
220+
| scope=organization owner= | scope=user owner=aaa | ✅ | ❌ |
221+
| scope=organization owner= | scope=user owner=aaa environment=on-prem | ✅ | ❌ |
222+
| scope=user owner=aaa | scope=user owner=aaa environment=on-prem | ✅ | ❌ |
223+
| scope=user owner=aaa environment=on-prem | scope=user owner=aaa environment=on-prem datacenter=chicago | ✅ | ❌ |
224+
| scope=user owner=aaa environment=on-prem datacenter=chicago | scope=user owner=aaa environment=on-prem datacenter=new_york | ✅ | ❌ |
225+
| scope=organization owner= environment=on-prem | scope=organization owner= environment=on-prem | ❌ | ❌ |
223226

224227
> **Note to maintainers:** to generate this table, run the following command and
225228
> copy the output:
226229
>
227230
> ```
228-
> go test -v -count=1 ./coderd/provisionerserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
231+
> go test -v -count=1 ./coderd/provisionerdserver/ -test.run='^TestAcquirer_MatchTags/GenTable$'
229232
> ```
230233

231234
## Types of provisioners
@@ -288,8 +291,7 @@ will use in concert with the Helm chart for deploying the Coder server.
288291
```sh
289292
coder provisioner keys create my-cool-key --org default
290293
# Optionally, you can specify tags for the provisioner key:
291-
# coder provisioner keys create my-cool-key --org default --tags location=auh kind=k8s
292-
```
294+
# coder provisioner keys create my-cool-key --org default --tag location=auh --tag kind=k8s
293295
294296
Successfully created provisioner key kubernetes-key! Save this authentication
295297
token, it will not be shown again.
@@ -300,25 +302,7 @@ will use in concert with the Helm chart for deploying the Coder server.
300302
1. Store the key in a kubernetes secret:
301303

302304
```sh
303-
kubectl create secret generic coder-provisioner-psk --from-literal=key1=`<key omitted>`
304-
```
305-
306-
1. Modify your Coder `values.yaml` to include
307-
308-
```yaml
309-
provisionerDaemon:
310-
keySecretName: "coder-provisioner-keys"
311-
keySecretKey: "key1"
312-
```
313-
314-
1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit
315-
`--version <your version>` to also upgrade Coder to the latest version.
316-
317-
```sh
318-
helm upgrade coder coder-v2/coder \
319-
--namespace coder \
320-
--version <your version> \
321-
--values values.yaml
305+
kubectl create secret generic coder-provisioner-psk --from-literal=my-cool-key=`<key omitted>`
322306
```
323307

324308
1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm
@@ -331,13 +315,17 @@ will use in concert with the Helm chart for deploying the Coder server.
331315
value: "https://coder.example.com"
332316
replicaCount: 10
333317
provisionerDaemon:
318+
# NOTE: in older versions of the Helm chart (2.17.0 and below), it is required to set this to an empty string.
319+
pskSecretName: ""
334320
keySecretName: "coder-provisioner-keys"
335-
keySecretKey: "key1"
321+
keySecretKey: "my-cool-key"
336322
```
337323

338324
This example creates a deployment of 10 provisioner daemons (for 10
339-
concurrent builds) with the listed tags. For generic provisioners, remove the
340-
tags.
325+
concurrent builds) authenticating using the above key. The daemons will
326+
authenticate using the provisioner key created in the previous step and
327+
acquire jobs matching the tags specified when the provisioner key was
328+
created. The set of tags is inferred automatically from the provisioner key.
341329

342330
> Refer to the
343331
> [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml)

0 commit comments

Comments
 (0)