From 84f0cf215f5e1b0d8341fd603f6bd958f782cc4b Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Wed, 23 Oct 2024 09:25:53 +0100
Subject: [PATCH] chore(docs): update external provisioners helm docs (#15155)

Closes https://github.com/coder/coder/issues/14985

Updates external provisioner documentation to show steps for using
provisioner keys via Helm:

---------

Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
---
 docs/admin/provisioners.md | 88 +++++++++++++++++++++++---------------
 1 file changed, 54 insertions(+), 34 deletions(-)

diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md
index 27b080085d..b8350f9237 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:
 
-<key omitted>
-```
+     ```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
+     <key omitted>
+     ```
 
-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:
 
-<key omitted>
-```
+     ```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://<your-coder-url>
-export CODER_PROVISIONER_DAEMON_KEY=<key>
-coder provisioner start
-```
+     <key omitted>
+     ```
+
+1. Start the provisioner with the specified key:
+
+   ```sh
+   export CODER_URL=https://<your-coder-url>
+   export CODER_PROVISIONER_DAEMON_KEY=<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)
 
-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
+> 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
 [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
-   kubectl create secret generic coder-provisioner-psk --from-literal=psk=`head /dev/urandom | base64 | tr -dc A-Za-z0-9 | head -c 26`
+   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.
+
+   <key omitted>
+   ```
+
+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:
-     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