Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit0ec87ab

Browse files
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 parent0125ff4 commit0ec87ab

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.mdrenamed 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 beneficialif 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 bedonein 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)
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 provisionerjobs 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 provisionerjobs 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-
<ahref="../provisioners.md#authentication">provisioners documentation</a>.
10+
<ahref="../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>
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)
[8]ページ先頭
©2009-2025 Movatter.jp