8000 docs: add new section on managing provisioners from the dashboard (#1… · coder/coder@0ec87ab · GitHub
[go: up one dir, main page]
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

File tree

19 files changed

+133
-36
lines changed

19 files changed

+133
-36
lines changed

‎.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:

‎docs/admin/templates/extending-templates/modules.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ template as the underlying module.
120120
### Private git repository
121121

122122
If you are importing a module from a private git repository, the Coder server or
123-
[provisioner](../../provisioners.md) needs git credentials. Since this token
123+
[provisioner](../../provisioners/index.md) needs git credentials. Since this token
124124
will only be used for cloning your repositories with modules, it is best to
125125
create a token with access limited to the repository and no extra permissions.
126126
In GitHub, you can generate a

‎docs/admin/templates/extending-templates/provider-authentication.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ There are two ways to use a remote Docker host for authentication:
4646

4747
- Configure the Docker provider to use a
4848
[remote host over SSH or TCP](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts).
49-
- Run an [external provisioner](../../provisioners.md) on the remote docker
49+
- Run an [external provisioner](../../provisioners/index.md) on the remote docker
5050
host.
5151

5252
Other providers might also support authenticated environments. Check the

‎docs/admin/users/groups-roles.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Roles determine which actions users can take within the platform.
2424
| Manage **ALL** Templates | | | ✅ | ✅ |
2525
| View **ALL** Workspaces | | | ✅ | ✅ |
2626
| Update and delete **ALL** Workspaces | | | | ✅ |
27-
| Run [external provisioners](../provisioners.md) | | | ✅ | ✅ |
27+
| Run [external provisioners](../provisioners/index.md) | | | ✅ | ✅ |
2828
| Execute and use **ALL** Workspaces | | | | ✅ |
2929
| View all user operation [Audit Logs](../security/audit-logs.md) | ✅ | | | ✅ |
3030

@@ -80,7 +80,7 @@ Note that these permissions only apply to the scope of an
8080
A malicious Template Admin could write a template that executes commands on the
8181
host (or `coder server` container), which potentially escalates their privileges
8282
or shuts down the Coder server. To avoid this, run
83-
[external provisioners](../provisioners.md).
83+
[external provisioners](../provisioners/index.md).
8484

8585
In low-trust environments, we do not recommend giving users direct access to
8686
edit templates. Instead, use

‎docs/admin/users/organizations.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ From there, you can manage the name, icon, description, users, and groups:
3737

3838
Any additional organizations have unique admins, users, templates, provisioners,
3939
groups, and workspaces. Each organization must have at least one dedicated
40-
[provisioner](../provisioners.md) since the built-in provisioners only apply to
40+
[provisioner](../provisioners/index.md) since the built-in provisioners only apply to
4141
the default organization.
4242

4343
You can configure [organization/role/group sync](./idp-sync.md) from your
@@ -71,7 +71,7 @@ Next deploy a provisioner and template for this organization.
7171

7272
### 2. Deploy a provisioner
7373

74-
[Provisioners](../provisioners.md) are organization-scoped and are responsible
74+
[Provisioners](../provisioners/index.md) are organization-scoped and are responsible
7575
for executing Terraform/OpenTofu to provision the infrastructure for workspaces
7676
and testing templates. Before creating templates, we must deploy at least one
7777
provisioner as the built-in provisioners are scoped to the default organization.
@@ -90,7 +90,7 @@ provisioner as the built-in provisioners are scoped to the default organization.
9090

9191
In this example, start the provisioner using the Coder CLI on a host with
9292
Docker. For instructions on using other platforms like Kubernetes, see our
93-
[provisioner documentation](../provisioners.md).
93+
[provisioner documentation](../provisioners/index.md).
9494

9595
```sh
9696
export CODER_URL=https://<your-coder-url>

‎docs/images/admin/provisioners/provisioner-jobs.png

77.8 KB
Loading

‎docs/manifest.json

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -499,9 +499,17 @@
499499
{
500500
"title": "External Provisioners",
501501
"description": "Learn how to run external provisioners with Coder",
502-
"path": "./admin/provisioners.md",
502+
"path": "./admin/provisioners/index.md",
503503
"icon_path": "./images/icons/key.svg",
504-
"state": ["enterprise", "premium"]
504+
"state": ["enterprise", "premium"],
505+
"children": [
506+
{
507+
"title": "Manage Provisioner Jobs",
508+
"description": "Learn how to run external provisioners with Coder",
509+
"path": "./admin/provisioners/manage-provisioner-jobs.md",
510+
"state": ["enterprise", "premium"]
511+
}
512+
]
505513
},
506514
{
507515
"title": "External Auth",

‎docs/tutorials/best-practices/scale-coder.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ maintenance window to minimize disruption.
141141
### Locality
142142

143143
We recommend that you run one or more
144-
[provisioner daemon deployments external to Coder Server](../../admin/provisioners.md)
144+
[provisioner daemon deployments external to Coder Server](../../admin/provisioners/index.md)
145145
and disable provisioner daemons within your Coder Server.
146146
This allows you to scale them independently of the Coder Server:
147147

‎docs/tutorials/best-practices/security-best-practices.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ provision:
161161

162162
### Authentication
163163

164-
1. Use a [scoped key](../../admin/provisioners.md#scoped-key-recommended) to
164+
1. Use a [scoped key](../../admin/provisioners/index.md#scoped-key-recommended) to
165165
authenticate the provisioner daemons with Coder. These keys can only be used
166166
to authenticate provisioner daemons (not other APIs on the Coder Server).
167167

‎docs/tutorials/best-practices/speed-up-templates.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ config option.
8383
You risk overloading Coder if you use too many built-in provisioners, so we
8484
recommend a maximum of five built-in provisioners per `coderd` replica. For more
8585
than five provisioners, we recommend that you move to
86-
[External Provisioners](../../admin/provisioners.md) and also consider
86+
[External Provisioners](../../admin/provisioners/index.md) and also consider
8787
[High Availability](../../admin/networking/high-availability.md) to run multiple
8888
`coderd` replicas.
8989

@@ -165,4 +165,4 @@ directory.
165165

166166
Ensure that this directory is set to a location on disk which will persist
167167
across restarts of Coder or
168-
[external provisioners](../../admin/provisioners.md), if you're using them.
168+
[external provisioners](../../admin/provisioners/index.md), if you're using them.

0 commit comments

Comments
 (0)
0