From 59f145cba6a4ecfaccc360936b2e72af15d36e01 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Mon, 21 Oct 2024 10:25:40 +0100 Subject: [PATCH 1/4] chore(docs): update external provisioners helm docs --- docs/admin/provisioners.md | 48 ++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 27b080085d803..9e8d00f05e6ca 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -40,8 +40,10 @@ The provisioner daemon must authenticate with your Coder deployment. ## Scoped Key (Recommended) -We recommend creating finely-scoped keys for provisioners. Keys are scoped to an -organization. +We recommend creating finely-scoped keys for provisioners. +Keys are scoped to an organization, and optionally to a specific set of tags. + +To create a key for an organization that will match untagged jobs: ```sh coder provisioner keys create my-key \ @@ -52,7 +54,7 @@ Successfully created provisioner key my-key! Save this authentication token, it ``` -Or, restrict the provisioner to jobs with specific tags +To restrict the provisioner to jobs with specific tags: ```sh coder provisioner keys create kubernetes-key \ @@ -64,7 +66,7 @@ Successfully created provisioner key kubernetes-key! Save this authentication to ``` -To start the provisioner: +You can then start the provisioner with the specified key: ```sh export CODER_URL=https:// @@ -98,11 +100,12 @@ Note: Any user can start [user-scoped provisioners](#user-scoped-provisioners), but this will also require a template on your deployment with the corresponding tags. -## Global PSK +## Global PSK (Not Recommended) + +> [!NOTE] We do not recommend this approach anymore, as it makes +> key rotation or isolating provisioners far more difficult. -A deployment-wide PSK can be used to authenticate any provisioner. We do not -recommend this approach anymore, as it makes key rotation or isolating -provisioners far more difficult. To use a global PSK, set a +A deployment-wide PSK can be used to authenticate any provisioner. To use a global PSK, set a [provisioner daemon pre-shared key (PSK)](../reference/cli/server.md#--provisioner-daemon-psk) on the Coder server. @@ -275,18 +278,31 @@ coder templates push on-prem \ Coder provides a Helm chart for running external provisioner daemons, which you will use in concert with the Helm chart for deploying the Coder server. -1. Create a long, random pre-shared key (PSK) and store it in a Kubernetes - secret +1. Create a provisioner key: + + ```sh + coder provisioner keys create my-cool-key --org default + # Optionally, you can specify tags for the provsioner key: + # coder provisioner keys create my-cool-key --org default --tags location=auh kind=k8s + ``` + + Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again. + + + ``` + + Store the key in a kubernetes secret: ```sh - kubectl create secret generic coder-provisioner-psk --from-literal=psk=`head /dev/urandom | base64 | tr -dc A-Za-z0-9 | head -c 26` + kubectl create secret generic coder-provisioner-psk --from-literal=key1=`` ``` 1. Modify your Coder `values.yaml` to include ```yaml provisionerDaemon: - pskSecretName: "coder-provisioner-psk" + keySecretName: "coder-provisioner-keys" + keySecretKey: "key1" ``` 1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit @@ -300,7 +316,7 @@ will use in concert with the Helm chart for deploying the Coder server. ``` 1. Create a `provisioner-values.yaml` file for the provisioner daemons Helm - chart. For example + chart. For example: ```yaml coder: @@ -309,10 +325,8 @@ will use in concert with the Helm chart for deploying the Coder server. value: "https://coder.example.com" replicaCount: 10 provisionerDaemon: - pskSecretName: "coder-provisioner-psk" - tags: - location: auh - kind: k8s + keySecretName: "coder-provisioner-keys" + keySecretKey: "key1" ``` This example creates a deployment of 10 provisioner daemons (for 10 From 2a02f3f885b94443de425ddf9c613c5e5d471acd Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Mon, 21 Oct 2024 10:54:46 +0100 Subject: [PATCH 2/4] make fmt --- docs/admin/provisioners.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 9e8d00f05e6ca..0b32b23650594 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -40,8 +40,8 @@ The provisioner daemon must authenticate with your Coder deployment. ## Scoped Key (Recommended) -We recommend creating finely-scoped keys for provisioners. -Keys are scoped to an organization, and optionally to a specific set of tags. +We recommend creating finely-scoped keys for provisioners. Keys are scoped to an +organization, and optionally to a specific set of tags. To create a key for an organization that will match untagged jobs: @@ -102,10 +102,11 @@ tags. ## Global PSK (Not Recommended) -> [!NOTE] We do not recommend this approach anymore, as it makes -> key rotation or isolating provisioners far more difficult. +> [!NOTE] We do not recommend this approach anymore, as it makes key rotation or +> isolating provisioners far more difficult. -A deployment-wide PSK can be used to authenticate any provisioner. To use a global PSK, set a +A deployment-wide PSK can be used to authenticate any provisioner. To use a +global PSK, set a [provisioner daemon pre-shared key (PSK)](../reference/cli/server.md#--provisioner-daemon-psk) on the Coder server. @@ -286,7 +287,8 @@ will use in concert with the Helm chart for deploying the Coder server. # coder provisioner keys create my-cool-key --org default --tags location=auh kind=k8s ``` - Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again. + Successfully created provisioner key kubernetes-key! Save this authentication + token, it will not be shown again. ``` @@ -302,7 +304,7 @@ will use in concert with the Helm chart for deploying the Coder server. ```yaml provisionerDaemon: keySecretName: "coder-provisioner-keys" - keySecretKey: "key1" + keySecretKey: "key1" ``` 1. Redeploy Coder with the new `values.yaml` to roll out the PSK. You can omit @@ -326,7 +328,7 @@ will use in concert with the Helm chart for deploying the Coder server. replicaCount: 10 provisionerDaemon: keySecretName: "coder-provisioner-keys" - keySecretKey: "key1" + keySecretKey: "key1" ``` This example creates a deployment of 10 provisioner daemons (for 10 From 13ae8fa57a5af70d798500436442e3f0c2e529d9 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 22 Oct 2024 17:53:07 +0000 Subject: [PATCH 3/4] scoped key steps --- docs/admin/provisioners.md | 44 ++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 0b32b23650594..1d7a016102828 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -43,36 +43,38 @@ The provisioner daemon must authenticate with your Coder deployment. We recommend creating finely-scoped keys for provisioners. Keys are scoped to an organization, and optionally to a specific set of tags. -To create a key for an organization that will match untagged jobs: +1. Use `coder provisioner` to create the key: -```sh -coder provisioner keys create my-key \ - --org default + - To create a key for an organization that will match untagged jobs: -Successfully created provisioner key my-key! Save this authentication token, it will not be shown again. + ```sh + coder provisioner keys create my-key \ + --org default - -``` + Successfully created provisioner key my-key! Save this authentication token, it will not be shown again. -To restrict the provisioner to jobs with specific tags: + + ``` -```sh -coder provisioner keys create kubernetes-key \ - --org default \ - --tag environment=kubernetes + - To restrict the provisioner to jobs with specific tags: -Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again. + ```sh + coder provisioner keys create kubernetes-key \ + --org default \ + --tag environment=kubernetes - -``` + Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again. -You can then start the provisioner with the specified key: + + ``` -```sh -export CODER_URL=https:// -export CODER_PROVISIONER_DAEMON_KEY= -coder provisioner start -``` +1. Start the provisioner with the specified key: + + ```sh + export CODER_URL=https:// + export CODER_PROVISIONER_DAEMON_KEY= + coder provisioner start + ``` Keep reading to see instructions for running provisioners on Kubernetes/Docker/etc. From 46d62caec7259169b4aa21fa15ffc1a838849557 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Tue, 22 Oct 2024 20:09:51 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Edward Angert --- docs/admin/provisioners.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 1d7a016102828..b8350f9237e5e 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -104,8 +104,10 @@ tags. ## Global PSK (Not Recommended) -> [!NOTE] We do not recommend this approach anymore, as it makes key rotation or -> isolating provisioners far more difficult. +> Global pre-shared keys (PSK) make it difficult to rotate keys or isolate +> provisioners. +> +> We do not recommend using global PSK. A deployment-wide PSK can be used to authenticate any provisioner. To use a global PSK, set a @@ -285,7 +287,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 provsioner key: + # Optionally, you can specify tags for the provisioner key: # coder provisioner keys create my-cool-key --org default --tags location=auh kind=k8s ``` @@ -295,7 +297,7 @@ will use in concert with the Helm chart for deploying the Coder server. ``` - Store the key in a kubernetes secret: +1. Store the key in a kubernetes secret: ```sh kubectl create secret generic coder-provisioner-psk --from-literal=key1=``