diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 27b080085d803..b8350f9237e5e 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -41,36 +41,40 @@ 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. +organization, and optionally to a specific set of tags. -```sh -coder provisioner keys create my-key \ - --org default +1. Use `coder provisioner` to create the key: -Successfully created provisioner key my-key! Save this authentication token, it will not be shown again. + - To create a key for an organization that will match untagged jobs: - -``` + ```sh + coder provisioner keys create my-key \ + --org default -Or, restrict the provisioner to jobs with specific tags + Successfully created provisioner key my-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. + - To restrict the provisioner to jobs with specific tags: - -``` + ```sh + coder provisioner keys create kubernetes-key \ + --org default \ + --tag environment=kubernetes -To start the provisioner: + Successfully created provisioner key kubernetes-key! Save this authentication token, it will not be shown again. -```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. @@ -98,11 +102,15 @@ 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) + +> 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. 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 +283,32 @@ 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 provisioner 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. + + + ``` + +1. 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 +322,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 +331,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