From f2680df0e8eeb7101993fecb5c1f438097d6ec10 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:09:46 +0000 Subject: [PATCH 1/7] chore(docs): fix inconsistencies in external provisioner docs --- coderd/provisionerdserver/acquirer_test.go | 10 ++- docs/admin/provisioners.md | 98 ++++++++++------------ 2 files changed, 49 insertions(+), 59 deletions(-) diff --git a/coderd/provisionerdserver/acquirer_test.go b/coderd/provisionerdserver/acquirer_test.go index a916cb68fba1f..12429bf5ccb3c 100644 --- a/coderd/provisionerdserver/acquirer_test.go +++ b/coderd/provisionerdserver/acquirer_test.go @@ -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 { @@ -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") diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index b8350f9237e5e..e10ef0342cdfa 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -178,7 +178,8 @@ 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` @@ -186,7 +187,8 @@ The external provisioner in the above example can run build jobs with tags: 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 @@ -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 @@ -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 @@ -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 - ``` + # 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. @@ -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=`` - ``` - -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 ` to also upgrade Coder to the latest version. - - ```sh - helm upgrade coder coder-v2/coder \ - --namespace coder \ - --version \ - --values values.yaml + kubectl create secret generic coder-provisioner-psk --from-literal=my-cool-key=`` ``` 1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm @@ -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: "" 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) @@ -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 From 919aaaf98e1812ec424f61dfaee96e40fa78ee2d Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:11:55 +0000 Subject: [PATCH 2/7] fixup! chore(docs): fix inconsistencies in external provisioner docs --- docs/admin/provisioners.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index e10ef0342cdfa..8a4e90e836826 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -273,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 From 8c1964fe5904faa626b94715f12cf7ad31e990ec Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:12:15 +0000 Subject: [PATCH 3/7] fixup! fixup! chore(docs): fix inconsistencies in external provisioner docs --- docs/admin/provisioners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 8a4e90e836826..20747c0bf95cb 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -315,7 +315,7 @@ 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. + # NOTE: in older versions of the Helm chart, it is required to set this to an empty string. pskSecretName: "" keySecretName: "coder-provisioner-keys" keySecretKey: "my-cool-key" From 633899b2ef25a5d4e2e68a64e856b8e2cf722c0b Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:14:31 +0000 Subject: [PATCH 4/7] fixup! fixup! fixup! chore(docs): fix inconsistencies in external provisioner docs --- docs/admin/provisioners.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 20747c0bf95cb..532c2306f5875 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -323,7 +323,9 @@ will use in concert with the Helm chart for deploying the Coder server. This example creates a deployment of 10 provisioner daemons (for 10 concurrent builds) authenticating using the above key. The daemons will - authenticate using tags fetched directly from the key. + authenticate using the provisioner key created in the previous step and + acquire jobs matching the tags specified when the provisioner key was created. + The set of tags is inferred automatically from the provisioner key. > Refer to the > [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml) From 938be055cd8aa0cd9e64eb4d3a84e1f19c96aac6 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:14:49 +0000 Subject: [PATCH 5/7] fixup! fixup! fixup! fixup! chore(docs): fix inconsistencies in external provisioner docs --- docs/admin/provisioners.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 532c2306f5875..c935dd78799ed 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -358,11 +358,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 From f600308a9515cbae044be0a43936f139e6102599 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 6 Nov 2024 22:22:26 +0000 Subject: [PATCH 6/7] make fmt --- docs/admin/provisioners.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index c935dd78799ed..1f5e933617500 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -324,8 +324,8 @@ will use in concert with the Helm chart for deploying the Coder server. This example creates a deployment of 10 provisioner daemons (for 10 concurrent builds) authenticating using the above key. The daemons will authenticate using the provisioner key created in the previous step and - acquire jobs matching the tags specified when the provisioner key was created. - The set of tags is inferred automatically from the provisioner key. + acquire jobs matching the tags specified when the provisioner key was + created. The set of tags is inferred automatically from the provisioner key. > Refer to the > [values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml) From f66a87747ea24122fde6175aff4edab2c116edce Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Thu, 7 Nov 2024 07:01:36 -0600 Subject: [PATCH 7/7] Update docs/admin/provisioners.md --- docs/admin/provisioners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 1f5e933617500..159ef79332de4 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -315,7 +315,7 @@ will use in concert with the Helm chart for deploying the Coder server. value: "https://coder.example.com" replicaCount: 10 provisionerDaemon: - # NOTE: in older versions of the Helm chart, it is required to set this to an empty string. + # NOTE: in older versions of the Helm chart (2.17.0 and below), it is required to set this to an empty string. pskSecretName: "" keySecretName: "coder-provisioner-keys" keySecretKey: "my-cool-key"