Skip to content

Commit 43b97f6

Browse files
matifalimatifali
committed
add automation page and fiox links in workspace page
1 parent a3bf62b commit 43b97f6

File tree

8 files changed

+216
-9
lines changed

8 files changed

+216
-9
lines changed

‎docs/admin/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,5 @@ Guides for day 2+ operations with Coder, including preparing for production and
3838
- Measure user adoption (weekly active users)
3939
- Identifying Coder power users
4040
- Reading template usage metrics
41+
42+
<children></children>

‎docs/admin/automation.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Automation
2+
3+
All actions possible through the Coder dashboard can also be automated as it
4+
utilizes the same public REST API. There are several ways to extend/automate
5+
Coder:
6+
7+
- [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
8+
- [CLI](../reference/cli/README.md)
9+
- [REST API](../reference/api/README.md)
10+
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
11+
12+
## Quickstart
13+
14+
Generate a token on your Coder deployment by visiting:
15+
16+
```shell
17+
https://coder.example.com/settings/tokens
18+
```
19+
20+
List your workspaces
21+
22+
```shell
23+
# CLI
24+
coder ls \
25+
--url https://coder.example.com \
26+
--token <your-token> \
27+
--output json
28+
29+
# REST API (with curl)
30+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
31+
-H "Coder-Session-Token: <your-token>"
32+
```
33+
34+
## Documentation
35+
36+
We publish an [API reference](../reference/api/README.md) in our documentation. You can
37+
also enable a [Swagger endpoint](../reference/cli/server.md#--swagger-enable) on
38+
your Coder deployment.
39+
40+
## Use cases
41+
42+
We strive to keep the following use cases up to date, but please note that
43+
changes to API queries and routes can occur. For the most recent queries and
44+
payloads, we recommend checking the relevant documentation.
45+
46+
### Users & Groups
47+
48+
- [Manage Users via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/user)
49+
- [Manage Groups via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/group)
50+
51+
### Templates
52+
53+
- [Manage templates via Terraform or CLI](../admin/templates/managing-templates/change-management.md):
54+
Store all templates in git and update them in CI/CD pipelines.
55+
56+
### Workspace agents
57+
58+
Workspace agents have a special token that can send logs, metrics, and workspace
59+
activity.
60+
61+
- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-logs):
62+
Expose messages prior to the Coder init script running (e.g. pulling image, VM
63+
starting, restoring snapshot).
64+
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
65+
this to show Kubernetes events, such as image pulls or ResourceQuota
66+
restrictions.
67+
68+
```shell
69+
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
70+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
71+
-d "{
72+
\"logs\": [
73+
{
74+
\"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
75+
\"level\": \"info\",
76+
\"output\": \"Restoring workspace from snapshot: 05%...\"
77+
}
78+
]
79+
}"
80+
```
81+
82+
- [Manually send workspace activity](../reference/api/agents.md#submit-workspace-agent-stats):
83+
Keep a workspace "active," even if there is not an open connection (e.g. for a
84+
long-running machine learning job).
85+
86+
```shell
87+
#!/bin/bash
88+
# Send workspace activity as long as the job is still running
89+
90+
while true
91+
do
92+
if pgrep -f "my_training_script.py" > /dev/null
93+
then
94+
curl -X POST "https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
95+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
96+
-d '{
97+
"connection_count": 1
98+
}'
99+
100+
# Sleep for 30 minutes (1800 seconds) if the job is running
101+
sleep 1800
102+
else
103+
# Sleep for 1 minute (60 seconds) if the job is not running
104+
sleep 60
105+
fi
106+
done
107+
```

‎docs/admin/templates/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,4 @@ We recommend starting with a universal template that can be used for basic tasks
3838

3939
## Template permissions & policies (enterprise)
4040

41-
TODO
41+
TODO Link permissions page.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,5 +131,5 @@ Refer to the following resources:
131131

132132
## Next steps
133133

134-
- [Extending templates](#TODO)
135-
- [TODO](#TODO)
134+
- [Extending templates](./extending-templates/README.md)
135+
- [Managing templates](./managing-templates/README.md)

‎docs/admin/templates/extending-templates/resource-persistence.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Resource persistence
2+
3+
By default, all Coder resources are persistent, but production templates
4+
**must** use the practices laid out in this document to prevent accidental
5+
deletion.
6+
7+
Coder templates have full control over workspace ephemerality. In a completely
8+
ephemeral workspace, there are zero resources in the Off state. In a completely
9+
persistent workspace, there is no difference between the Off and On states.
10+
11+
The needs of most workspaces fall somewhere in the middle, persisting user data
12+
like filesystem volumes, but deleting expensive, reproducible resources such as
13+
compute instances.
14+
15+
## Disabling persistence
16+
17+
The Terraform
18+
[`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
19+
exposes the `start_count = [0 | 1]` attribute. To make a resource ephemeral, you
20+
can assign the `start_count` attribute to resource's
21+
[`count`](https://developer.hashicorp.com/terraform/language/meta-arguments/count)
22+
meta-argument.
23+
24+
In this example, Coder will provision or tear down the `docker_container`
25+
resource:
26+
27+
```hcl
28+
data "coder_workspace" "me" {
29+
}
30+
31+
resource "docker_container" "workspace" {
32+
# When `start_count` is 0, `count` is 0, so no `docker_container` is created.
33+
count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started)
34+
# ... other config
35+
}
36+
```
37+
38+
## ⚠️ Persistence pitfalls
39+
40+
Take this example resource:
41+
42+
```hcl
43+
data "coder_workspace" "me" {
44+
}
45+
46+
resource "docker_volume" "home_volume" {
47+
name = "coder-${data.coder_workspace.me.owner}-home"
48+
}
49+
```
50+
51+
Because we depend on `coder_workspace.me.owner`, if the owner changes their
52+
username, Terraform will recreate the volume (wiping its data!) the next time
53+
that Coder starts the workspace.
54+
55+
To prevent this, use immutable IDs:
56+
57+
- `coder_workspace.me.owner_id`
58+
- `coder_workspace.me.id`
59+
60+
```hcl
61+
data "coder_workspace" "me" {
62+
}
63+
64+
resource "docker_volume" "home_volume" {
65+
# This volume will survive until the Workspace is deleted or the template
66+
# admin changes this resource block.
67+
name = "coder-${data.coder_workspace.id}-home"
68+
}
69+
```
70+
71+
## 🛡 Bulletproofing
72+
73+
Even if your persistent resource depends exclusively on immutable IDs, a change
74+
to the `name` format or other attributes would cause Terraform to rebuild the
75+
resource.
76+
77+
You can prevent Terraform from recreating a resource under any circumstance by
78+
setting the
79+
[`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
80+
81+
```hcl
82+
data "coder_workspace" "me" {
83+
}
84+
85+
resource "docker_volume" "home_volume" {
86+
# This resource will survive until either the entire block is deleted
87+
# or the workspace is.
88+
name = "coder-${data.coder_workspace.me.id}-home"
89+
lifecycle {
90+
ignore_changes = all
91+
}
92+
}
93+
```

‎docs/manifest.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,11 @@
428428
"path": "./admin/security/secrets.md"
429429
}
430430
]
431+
},
432+
{
433+
"title": "Automation",
434+
"description": "DIfferent ways to automate Coder actions and workflows",
435+
"path": "./admin/automation.md"
431436
}
432437
]
433438
},

‎docs/tutorials/template-from-scratch.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -299,7 +299,7 @@ resource "docker_volume" "home_volume" {
299299
300300
```
301301

302-
For details, see [Resource persistence](./resource-persistence.md).
302+
For details, see [Resource persistence](../admin/templates/extending-templates/resource-persistence.md).
303303

304304
## 6. Set up the Docker container
305305

‎docs/workspaces.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Workspaces
22

33
A workspace is the environment that a developer works in. Developers in a team
4-
each work from their own workspace and can use [multiple IDEs](./ides.md).
4+
each work from their own workspace and can use [multiple IDEs](./user-guides/workspace-access/README.md).
55

6-
A developer creates a workspace from a [shared template](./templates/index.md).
6+
A developer creates a workspace from a [shared template](./admin/templates/README.md).
77
This lets an entire team work in environments that are identically configured
88
and provisioned with the same resources.
99

@@ -22,7 +22,7 @@ You can manage your existing templates in the **Workspaces** tab.
2222
You can also create a workspace from the command line:
2323

2424
Each Coder user has their own workspaces created from
25-
[shared templates](./templates/index.md):
25+
[templates](./admin/templates/README.md):
2626

2727
```shell
2828
# create a workspace from the template; specify any variables
@@ -67,7 +67,7 @@ To set a workspace's schedule, go to the workspace, then **Settings** >
6767
![Scheduling UI](./images/schedule.png)
6868

6969
Coder might also stop a workspace automatically if there is a
70-
[template update](./templates/index.md#Start/stop) available.
70+
[template update](./admin/templates/README.md#Start/stop) available.
7171

7272
### Autostart and autostop
7373

@@ -170,7 +170,7 @@ any activity or if there was a
170170

171171
Resources are often destroyed and re-created when a workspace is restarted,
172172
though the exact behavior depends on the template. For more information, see
173-
[Resource Persistence](./templates/resource-persistence.md).
173+
[Resource Persistence](./admin/templates/extending-templates/resource-persistence.md).
174174

175175
> ⚠️ To avoid data loss, refer to your template documentation for information on
176176
> where to store files, install software, etc., so that they persist. Default

0 commit comments

Comments
 (0)