Skip to content

Commit 0585372

Browse files
bpmctKatie Horne
bpmct
and
Katie Horne
authored
add enhanced docs for creating & troubleshooting templates (#2546)
Co-authored-by: Katie Horne <katie@coder.com>
1 parent 9d02a37 commit 0585372

File tree

1 file changed

+187
-14
lines changed

1 file changed

+187
-14
lines changed

‎docs/templates.md

+187-14
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
# Templates
22

3-
Templates define the infrastructure underlying workspaces. Each Coder deployment
4-
can have multiple templates for different workloads, such as ones for front-end
5-
development, Windows development, and so on.
3+
Templates are written in standard Terraform and describe the infrastructure for
4+
workspaces (e.g., aws_instance, kubernetes_pod, or both).
65

7-
Coder manages templates, including sharing them and rolling out updates
8-
to everybody. Users can also manually update their workspaces.
6+
In most cases, a small group of users (Coder admins) manage templates. Then,
7+
other users provision their development workspaces from templates.
98

10-
## Manage templates
9+
## Add a template
1110

12-
Coder provides production-ready [sample templates](https://github.com/coder/coder/tree/main/examples/templates),
13-
but you can modify the templates with Terraform.
11+
Before users can create workspaces, you'll need at least one template in Coder.
1412

1513
```sh
14+
# create a local directory to store templates
15+
mkdir -p $HOME/coder/templates
16+
cd $HOME/coder/templates
17+
1618
# start from an example
1719
coder templates init
1820

@@ -23,17 +25,188 @@ vim <template-name>/main.tf
2325
coder templates <create/update> <template-name>
2426
```
2527

26-
## Parameters
28+
> See the documentation and source code for each example in the
29+
> [examples/](https://github.com/coder/coder/tree/main/examples/templates)
30+
> directory in the repo.
31+
32+
## Customize templates
33+
34+
Example templates are not designed to support every use (e.g [examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) does
35+
not support custom VPCs). You can add these features by editing the Terraform
36+
code once you run `coder templates init` (new) or `coder templates pull`
37+
(existing).
38+
39+
- See [Creating and troubleshooting templates](#creating--troubleshooting-templates) for
40+
more info
41+
42+
## Concepts in templates
43+
44+
While templates are written with standard Terraform, the
45+
[Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) is
46+
used to define the workspace lifecycle and establish a connection from resources
47+
to Coder.
48+
49+
Below is an overview of some key concepts in templates (and workspaces). For all
50+
template options, reference [Coder Terraform provider docs](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs/resources/container).
51+
52+
### Resource
53+
54+
Resources in Coder are simply [Terraform resources](https://www.terraform.io/language/resources).
55+
If a Coder agent is attached to a resource, users can connect directly to the resource over
56+
SSH or web apps.
57+
58+
### Coder agent
59+
60+
Once a Coder workspace is created, the Coder agent establishes a connection
61+
between a resource (docker_container) and Coder, so that a user can connect to
62+
their workspace from the web UI or CLI. A template can have multiple agents to
63+
allow users to connect to multiple resources in their workspace.
64+
65+
> Resources must download and start the Coder agent binary to connect to Coder.
66+
> This means the resource must be able to reach your Coder URL.
67+
68+
Use the Coder agent's init script to
69+
70+
```hcl
71+
data "coder_workspace" "me" {
72+
}
73+
74+
resource "coder_agent" "pod1" {
75+
os = "linux"
76+
arch = "amd64"
77+
}
78+
79+
resource "kubernetes_pod" "pod1" {
80+
spec {
81+
...
82+
container {
83+
command = ["sh", "-c", coder_agent.pod1.init_script]
84+
env {
85+
name = "CODER_AGENT_TOKEN"
86+
value = coder_agent.dev.token
87+
}
88+
}
89+
}
90+
}
91+
```
92+
93+
### Parameters
2794

28-
Templates often contain _parameters_. In Coder, there are two types of parameters:
95+
Templates often contain _parameters_. These are defined by `variable` blocks in
96+
Terraform. There are two types of parameters:
2997

30-
- **Admin parameters** are set when a template is created/updated. These values
31-
are often cloud secrets, such as a `ServiceAccount` token, and are annotated
98+
- **Admin/template-wide parameters** are set when a template is created/updated. These values
99+
are often cloud configuration, such as a `VPC`, and are annotated
32100
with `sensitive = true` in the template code.
33-
- **User parameters** are set when a user creates a workspace. They are unique
34-
to each workspace, often personalization settings such as "preferred region"
101+
- **User/workspace parameters** are set when a user creates a workspace. These
102+
values are often personalization settings such as "preferred region"
35103
or "workspace image".
36104

105+
The template sample below uses *admin and user parameters* to allow developers to
106+
create workspaces from any image as long as it is in the proper registry:
107+
108+
```hcl
109+
variable "image_registry_url" {
110+
description = "The image registry developers can sele"
111+
default = "artifactory1.organization.com`
112+
sensitive = true # admin (template-wide) parameter
113+
}
114+
115+
variable "docker_image_name" {
116+
description = "The image your workspace will start from"
117+
default = "base_image"
118+
sensitive = false # user (workspace) parameter
119+
}
120+
121+
resource "docker_image" "workspace" {
122+
# ... other config
123+
name = "${var.image_registry_url}/${var.docker_image_name}"
124+
}
125+
```
126+
127+
### Persistent vs. ephemeral resources
128+
129+
You can use the workspace state to ensure some resources in Coder can are
130+
persistent, while others are ephemeral.
131+
132+
#### Start/stop
133+
134+
Coder workspaces can be started/stopped. This is often used to save on cloud costs or enforce
135+
ephemeral workflows. When a workspace is started or stopped, the Coder server
136+
runs an additional
137+
[terraform apply](https://www.terraform.io/cli/commands/apply), informing the
138+
Coder provider that the workspace has a new transition state.
139+
140+
This template sample has one persistent resource (docker image) and one ephemeral resource
141+
(docker volume).
142+
143+
```sh
144+
data "coder_workspace" "me" {
145+
}
146+
147+
resource "docker_volume" "home_volume" {
148+
# persistent resource (remains a workspace is stopped)
149+
count = 1
150+
name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-root"
151+
}
152+
153+
resource "docker_container" "workspace" {
154+
# ephemeral resource (deleted when workspace is stopped, created when started)
155+
count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started)
156+
volumes {
157+
container_path = "/home/coder/"
158+
volume_name = docker_volume.home_volume.name
159+
read_only = false
160+
}
161+
# ... other config
162+
}
163+
```
164+
165+
#### Delete workspaces
166+
167+
When a workspace is deleted, the Coder server essentially runs a
168+
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
169+
resources associated with the workspace.
170+
171+
> Terraform's
172+
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
173+
> and
174+
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
175+
> meta-arguments can be used to accidental data loss.
176+
177+
### Coder apps
178+
179+
By default, all templates allow developers to connect over SSH and a web
180+
terminal. See [Configuring Web IDEs](./ides/configuring-web-ides.md) to
181+
learn how to give users access to additional web applications.
182+
183+
## Creating & troubleshooting templates
184+
185+
You can use any Terraform resources or modules with Coder! When working on
186+
templates, we recommend you refer to the following resources:
187+
188+
- this document
189+
- [example templates](https://github.com/coder/coder/tree/main/examples/templates) code
190+
- [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs)
191+
documentation
192+
193+
Occasionally, you may run into scenarios where the agent is not able to connect.
194+
This means the start script has failed.
195+
196+
```sh
197+
$ coder ssh myworkspace
198+
Waiting for [agent] to connect...
199+
```
200+
201+
While troubleshooting steps vary by resource, here are some general best
202+
practices:
203+
204+
- Ensure the resource has `curl` installed
205+
- Ensure the resource can reach your Coder URL
206+
- Manually connect to the resource (e.g., `docker exec` or AWS console)
207+
- The Coder agent logs are typically stored in (`/var/log/coder-agent.log`)
208+
209+
37210
## Change Management
38211

39212
We recommend source controlling your templates as you would other code.

0 commit comments

Comments
 (0)