Skip to content

Commit 0ec87ab

Browse files
EdwardAngertEdwardAngert
authored
docs: add new section on managing provisioners from the dashboard (#16563)
closes #16513 [preview](https://coder.com/docs/@16513-manage-ext-provisioners/admin/provisioners/manage-provisioner-jobs) --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
1 parent 0125ff4 commit 0ec87ab

19 files changed

Lines changed: 133 additions & 36 deletions

File tree

‎.vscode/settings.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,8 @@
5757
"[css][html][markdown][yaml]": {
5858
"editor.defaultFormatter": "esbenp.prettier-vscode"
5959
},
60-
"typos.config": ".github/workflows/typos.toml"
60+
"typos.config": ".github/workflows/typos.toml",
61+
"[markdown]": {
62+
"editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
63+
}
6164
}

‎coderd/provisionerdserver/acquirer_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ func TestAcquirer_MatchTags(t *testing.T) {
518518

519519
t.Run("GenTable", func(t *testing.T) {
520520
t.Parallel()
521-
// Generate a table that can be copy-pasted into docs/admin/provisioners.md
521+
// Generate a table that can be copy-pasted into docs/admin/provisioners/index.md
522522
lines := []string{
523523
"\n",
524524
"| Provisioner Tags | Job Tags | Same Org | Can Run Job? |",
@@ -547,7 +547,7 @@ func TestAcquirer_MatchTags(t *testing.T) {
547547
s := fmt.Sprintf("| %s | %s | %s | %s |", kvs(tt.acquireJobTags), kvs(tt.provisionerJobTags), sameOrg, acquire)
548548
lines = append(lines, s)
549549
}
550-
t.Log("You can paste this into docs/admin/provisioners.md")
550+
t.Log("You can paste this into docs/admin/provisioners/index.md")
551551
t.Log(strings.Join(lines, "\n"))
552552
})
553553
}

‎docs/admin/infrastructure/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ _provisionerd_ is the execution context for infrastructure modifying providers.
4242
At the moment, the only provider is Terraform (running `terraform`).
4343

4444
By default, the Coder server runs multiple provisioner daemons.
45-
[External provisioners](../provisioners.md) can be added for security or
45+
[External provisioners](../provisioners/index.md) can be added for security or
4646
scalability purposes.
4747

4848
### Workspaces

‎docs/admin/monitoring/health-check.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ be built until there is at least one provisioner daemon running.
294294
**Solution:**
295295

296296
If you are using
297-
[External Provisioner Daemons](../provisioners.md#external-provisioners), ensure
297+
[External Provisioner Daemons](../provisioners/index.md#external-provisioners), ensure
298298
that they are able to successfully connect to Coder. Otherwise, ensure
299299
[`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons)
300300
is set to a value greater than 0.

‎docs/admin/monitoring/logs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Connect logs are all captured in the `coderd` logs.
2424

2525
## `provisionerd` Logs
2626

27-
Logs for [external provisioners](../provisioners.md) are structured
27+
Logs for [external provisioners](../provisioners/index.md) are structured
2828
[and configured](../../reference/cli/provisioner_start.md#--log-human) similarly
2929
to `coderd` logs. Use these logs to troubleshoot and monitor the Terraform
3030
operations behind workspaces and templates.

docs/admin/provisioners.md renamed to docs/admin/provisioners/index.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# External provisioners
22

33
By default, the Coder server runs
4-
[built-in provisioner daemons](../reference/cli/server.md#--provisioner-daemons),
4+
[built-in provisioner daemons](../../reference/cli/server.md#--provisioner-daemons),
55
which execute `terraform` during workspace and template builds. However, there
66
are often benefits to running external provisioner daemons:
77

@@ -11,27 +11,29 @@ are often benefits to running external provisioner daemons:
1111
- **Isolate APIs:** Deploy provisioners in isolated environments (on-prem, AWS,
1212
Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coder
1313
server. See
14-
[Provider Authentication](../admin/templates/extending-templates/provider-authentication.md)
14+
[Provider Authentication](../../admin/templates/extending-templates/provider-authentication.md)
1515
for more details.
1616

1717
- **Isolate secrets**: Keep Coder unaware of cloud secrets, manage/rotate
1818
secrets on provisioner servers.
1919

2020
- **Reduce server load**: External provisioners reduce load and build queue
2121
times from the Coder server. See
22-
[Scaling Coder](../admin/infrastructure/index.md#scale-tests) for more
22+
[Scaling Coder](../../admin/infrastructure/index.md#scale-tests) for more
2323
details.
2424

2525
Each provisioner runs a single
26-
[concurrent workspace build](../admin/infrastructure/scale-testing.md#control-plane-provisionerd).
26+
[concurrent workspace build](../../admin/infrastructure/scale-testing.md#control-plane-provisionerd).
2727
For example, running 30 provisioner containers will allow 30 users to start
2828
workspaces at the same time.
2929

3030
Provisioners are started with the
31-
[`coder provisioner start`](../reference/cli/provisioner_start.md) command in
31+
[`coder provisioner start`](../../reference/cli/provisioner_start.md) command in
3232
the [full Coder binary](https://github.com/coder/coder/releases). Keep reading
3333
to learn how to start provisioners via Docker, Kubernetes, Systemd, etc.
3434

35+
You can use the dashboard, CLI, or API to [manage provisioners](./manage-provisioner-jobs.md).
36+
3537
## Authentication
3638

3739
The provisioner daemon must authenticate with your Coder deployment.
@@ -83,7 +85,7 @@ Kubernetes/Docker/etc.
8385

8486
A user account with the role `Template Admin` or `Owner` can start provisioners
8587
using their user account. This may be beneficial if you are running provisioners
86-
via [automation](../reference/index.md).
88+
via [automation](../../reference/index.md).
8789

8890
```sh
8991
coder login https://<your-coder-url>
@@ -110,7 +112,7 @@ Global pre-shared keys (PSK) make it difficult to rotate keys or isolate provisi
110112

111113
A deployment-wide PSK can be used to authenticate any provisioner. To use a
112114
global PSK, set a
113-
[provisioner daemon pre-shared key (PSK)](../reference/cli/server.md#--provisioner-daemon-psk)
115+
[provisioner daemon pre-shared key (PSK)](../../reference/cli/server.md#--provisioner-daemon-psk)
114116
on the Coder server.
115117

116118
Next, start the provisioner:
@@ -157,12 +159,12 @@ coder templates push on-prem-chicago \
157159

158160
This can also be done in the UI when building a template:
159161

160-
![template tags](../images/admin/provisioner-tags.png)
162+
![template tags](../../images/admin/provisioner-tags.png)
161163

162164
Alternatively, a template can target a provisioner via
163165
[workspace tags](https://github.com/coder/coder/tree/main/examples/workspace-tags)
164166
inside the Terraform. See the
165-
[workspace tags documentation](../admin/templates/extending-templates/workspace-tags.md)
167+
[workspace tags documentation](../../admin/templates/extending-templates/workspace-tags.md)
166168
for more information.
167169

168170
> [!NOTE]
@@ -237,17 +239,17 @@ This is illustrated in the below table:
237239

238240
Provisioners can broadly be categorized by scope: `organization` or `user`. The
239241
scope of a provisioner can be specified with
240-
[`-tag=scope=<scope>`](../reference/cli/provisioner_start.md#-t---tag) when
242+
[`-tag=scope=<scope>`](../../reference/cli/provisioner_start.md#-t---tag) when
241243
starting the provisioner daemon. Only users with at least the
242-
[Template Admin](./users/index.md#roles) role or higher may create
244+
[Template Admin](../users/index.md#roles) role or higher may create
243245
organization-scoped provisioner daemons.
244246

245247
There are two exceptions:
246248

247-
- [Built-in provisioners](../reference/cli/server.md#--provisioner-daemons) are
249+
- [Built-in provisioners](../../reference/cli/server.md#--provisioner-daemons) are
248250
always organization-scoped.
249251
- External provisioners started using a
250-
[pre-shared key (PSK)](../reference/cli/provisioner_start.md#--psk) are always
252+
[pre-shared key (PSK)](../../reference/cli/provisioner_start.md#--psk) are always
251253
organization-scoped.
252254

253255
### Organization-Scoped Provisioners
@@ -371,7 +373,7 @@ docker run --rm -it \
371373

372374
As mentioned above, the Coder server will run built-in provisioners by default.
373375
This can be disabled with a server-wide
374-
[flag or environment variable](../reference/cli/server.md#--provisioner-daemons).
376+
[flag or environment variable](../../reference/cli/server.md#--provisioner-daemons).
375377

376378
```sh
377379
coder server --provisioner-daemons=0
@@ -390,3 +392,7 @@ address.
390392

391393
If you have provisioners daemons deployed as pods, it is advised to monitor them
392394
separately.
395+
396+
## Next
397+
398+
- [Manage Provisioners](./manage-provisioner-jobs.md)

‎docs/admin/provisioners/manage-provisioner-jobs.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Manage provisioner jobs
2+
3+
[Provisioners](./index.md) start and run provisioner jobs to create or delete workspaces.
4+
Each time a workspace is built, rebuilt, or destroyed, it generates a new job and assigns
5+
the job to an available provisioner daemon for execution.
6+
7+
While most jobs complete smoothly, issues with templates, cloud resources, or misconfigured
8+
provisioners can cause jobs to fail or hang indefinitely (these are in a `Pending` state).
9+
10+
![Provisioner jobs in the dashboard](../../images/admin/provisioners/provisioner-jobs.png)
11+
12+
## How to find provisioner jobs
13+
14+
Coder admins can view and manage provisioner jobs.
15+
16+
Use the dashboard, CLI, or API:
17+
18+
- **Dashboard**:
19+
20+
Select **Admin settings** > **Organizations** > **Provisioner Jobs**
21+
22+
Provisioners are organization-specific. If you have more than one organization, select it first.
23+
24+
- **CLI**: `coder provisioner jobs list`
25+
- **API**: `/api/v2/provisioner/jobs`
26+
27+
## Manage provisioner jobs from the dashboard
28+
29+
View more information about and manage your provisioner jobs from the Coder dashboard.
30+
31+
1. Under **Admin settings** select **Organizations**, then select **Provisioner jobs**.
32+
33+
1. Select the **>** to expand each entry for more information.
34+
35+
1. To delete a job, select the 🚫 at the end of the entry's row.
36+
37+
If your user doesn't have the correct permissions, this option is greyed out.
38+
39+
## Provisioner job status
40+
41+
Each provisioner job has a lifecycle state:
42+
43+
| Status | Description |
44+
|---------------|----------------------------------------------------------------|
45+
| **Pending** | Job is queued but has not yet been picked up by a provisioner. |
46+
| **Running** | A provisioner is actively working on the job. |
47+
| **Completed** | Job succeeded. |
48+
| **Failed** | Provisioner encountered an error while executing the job. |
49+
| **Canceled** | Job was manually terminated by an admin. |
50+
51+
## When to cancel provisioner jobs
52+
53+
A job might need to be cancelled when:
54+
55+
- It has been stuck in **Pending** for too long. This can be due to misconfigured tags or unavailable provisioners.
56+
- It is **Running** indefinitely, often caused by external system failures or buggy templates.
57+
- An admin wants to abort a failed attempt, fix the root cause, and retry provisioning.
58+
- A workspace was deleted in the UI but the underlying cloud resource wasn’t cleaned up, causing a hanging delete job.
59+
60+
Cancelling a job does not automatically retry the operation.
61+
It clears the stuck state and allows the admin or user to trigger the action again if needed.
62+
63+
## Troubleshoot provisioner jobs
64+
65+
Provisioner jobs can fail or slow workspace creation for a number of reasons.
66+
Follow these steps to identify problematic jobs or daemons:
67+
68+
1. Filter jobs by `pending` status in the dashboard, or use the CLI:
69+
70+
```bash
71+
coder provisioner jobs list -s pending
72+
```
73+
74+
1. Look for daemons with multiple failed jobs and for template [tag mismatches](./index.md#provisioner-tags).
75+
76+
1. Cancel the job through the dashboard, or use the CLI:
77+
78+
```shell
79+
coder provisioner jobs cancel <job-id>
80+
```

‎docs/admin/security/secrets.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ guide to
77

88
This article explains how to use secrets in a workspace. To authenticate the
99
workspace provisioner, see the
10-
<a href="../provisioners.md#authentication">provisioners documentation</a>.
10+
<a href="../provisioners/index.md#authentication">provisioners documentation</a>.
1111

1212
## Before you begin
1313

‎docs/admin/setup/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,4 +154,4 @@ more information.
154154
## Up Next
155155

156156
- [Setup and manage templates](../templates/index.md)
157-
- [Setup external provisioners](../provisioners.md)
157+
- [Setup external provisioners](../provisioners/index.md)

‎docs/admin/templates/creating-templates.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ coder templates push
6868
> [!NOTE]
6969
> If `template push` fails, Coder is likely not authorized to deploy
7070
> infrastructure in the given location. Learn how to configure
71-
> [provisioner authentication](../provisioners.md).
71+
> [provisioner authentication](../provisioners/index.md).
7272
7373
You can edit the metadata of the template such as the display name with the
7474
[`templates edit`](../../reference/cli/templates_edit.md) command:

0 commit comments

Comments
 (0)