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
1719coder templates init
1820
@@ -23,17 +25,188 @@ vim <template-name>/main.tf
2325coder 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 cloudsecrets , 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 cloudconfiguration , 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+ Waitingfor [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
39212We recommend source controlling your templates as you would other code.
