Skip to content

chore(docs): update external provisioners helm docs #15155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 23, 2024
Merged

chore(docs): update external provisioners helm docs #15155

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
59f145c
chore(docs): update external provisioners helm docs
johnstcn Oct 21, 2024
2a02f3f
make fmt
johnstcn Oct 21, 2024
13ae8fa
scoped key steps
EdwardAngert Oct 22, 2024
46d62ca
Apply suggestions from code review
johnstcn Oct 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 54 additions & 34 deletions docs/admin/provisioners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

<key omitted>
```

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=`<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
Expand All @@ -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:
Expand All @@ -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
Expand Down