Skip to content

Commit e20aa4b

Browse files
mtojekmtojek
committed
WIP
1 parent 1cc10f2 commit e20aa4b

File tree

3 files changed

+126
-79
lines changed

3 files changed

+126
-79
lines changed

‎docs/manifest.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,12 @@
135135
"description": "Use docker inside containerized templates",
136136
"path": "./templates/docker-in-docker.md",
137137
"icon_path": "./images/icons/docker.svg"
138+
},
139+
{
140+
"title": "Parameters",
141+
"description": "Use parameters to customize templates",
142+
"path": "./templates/parameters.md",
143+
"icon_path": "./images/icons/code.svg"
138144
}
139145
]
140146
},

‎docs/templates.md

Lines changed: 0 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -185,85 +185,6 @@ coder dotfiles -y ${var.dotfiles_uri}
185185
}
186186
```
187187

188-
### Parameters (alpha)
189-
190-
> Parameters are an [alpha feature](./contributing/feature-stages.md#alpha-features). See the [Rich Parameters Milestone](https://github.com/coder/coder/milestone/11) for more details.
191-
192-
Templates can contain _parameters_, which prompt the user for additional information
193-
in the "create workspace" screen.
194-
195-
![Parameters in Create Workspace screen](./images/parameters.png)
196-
197-
```hcl
198-
data "coder_parameter" "docker_host" {
199-
name = "Region"
200-
description = "Which region would you like to deploy to?"
201-
icon = "/emojis/1f30f.png"
202-
type = "string"
203-
default = "tcp://100.94.74.63:2375"
204-
205-
option {
206-
name = "Pittsburgh, USA"
207-
value = "tcp://100.94.74.63:2375"
208-
icon = "/emojis/1f1fa-1f1f8.png"
209-
}
210-
211-
option {
212-
name = "Helsinki, Finland"
213-
value = "tcp://100.117.102.81:2375"
214-
icon = "/emojis/1f1eb-1f1ee.png"
215-
}
216-
217-
option {
218-
name = "Sydney, Australia"
219-
value = "tcp://100.127.2.1:2375"
220-
icon = "/emojis/1f1e6-1f1f9.png"
221-
}
222-
}
223-
```
224-
225-
From there, parameters can be referenced during build-time:
226-
227-
```hcl
228-
provider "docker" {
229-
host = data.coder_parameter.docker_host.value
230-
}
231-
```
232-
233-
> For a complete list of supported parameter types, see the
234-
> [coder_parameter Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter)
235-
236-
#### Legacy parameters
237-
238-
Prior to Coder v0.16.0 (Jan 2023), parameters were defined via Terraform `variable` blocks. These "legacy parameters" can still be used in templates, but will be removed in April 2023.
239-
240-
```hcl
241-
variable "use_kubeconfig" {
242-
sensitive = true # Admin (template-level) parameter
243-
type = bool
244-
description = <<-EOF
245-
Use host kubeconfig? (true/false)
246-
EOF
247-
}
248-
249-
variable "cpu" {
250-
sensitive = false # User (workspace-level) parameter
251-
description = "CPU (__ cores)"
252-
default = 2
253-
validation {
254-
condition = contains([
255-
"2",
256-
"4",
257-
"6",
258-
"8"
259-
], var.cpu)
260-
error_message = "Invalid cpu!"
261-
}
262-
}
263-
```
264-
265-
> ⚠️ Legacy (`variable`) parameters and rich parameters cannot be used in the same template.
266-
267188
### Start/stop
268189

269190
[Learn about resource persistence in Coder](./templates/resource-persistence.md)

‎docs/templates/parameters.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Parameters (alpha)
2+
3+
> Parameters are an [alpha feature](../contributing/feature-stages.md#alpha-features). See the [Rich Parameters Milestone](https://github.com/coder/coder/milestone/11) for more details.
4+
5+
Templates can contain _parameters_, which prompt the user for additional information
6+
in the "create workspace" screen.
7+
8+
![Parameters in Create Workspace screen](../images/parameters.png)
9+
10+
```hcl
11+
data "coder_parameter" "docker_host" {
12+
name = "Region"
13+
description = "Which region would you like to deploy to?"
14+
icon = "/emojis/1f30f.png"
15+
type = "string"
16+
default = "tcp://100.94.74.63:2375"
17+
18+
option {
19+
name = "Pittsburgh, USA"
20+
value = "tcp://100.94.74.63:2375"
21+
icon = "/emojis/1f1fa-1f1f8.png"
22+
}
23+
24+
option {
25+
name = "Helsinki, Finland"
26+
value = "tcp://100.117.102.81:2375"
27+
icon = "/emojis/1f1eb-1f1ee.png"
28+
}
29+
30+
option {
31+
name = "Sydney, Australia"
32+
value = "tcp://100.127.2.1:2375"
33+
icon = "/emojis/1f1e6-1f1f9.png"
34+
}
35+
}
36+
```
37+
38+
From there, parameters can be referenced during build-time:
39+
40+
```hcl
41+
provider "docker" {
42+
host = data.coder_parameter.docker_host.value
43+
}
44+
```
45+
46+
> For a complete list of supported parameter types, see the
47+
> [coder_parameter Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter)
48+
49+
## Optional
50+
51+
A parameter is consider to be _required_ if it doesn't have the `default` property. It means that the workspace user needs to provide the parameter value before creating a workspace.
52+
53+
```hcl
54+
data "coder_parameter" "account_name" {
55+
name = "Account name"
56+
description = "Cloud account name"
57+
mutable = true
58+
}
59+
```
60+
61+
If a parameter contains the `default` property, coder will use it when the workspace user doesn't specify the custom value. This way admins can set the `default` property to an empty value,
62+
so that the parameter field can remain empty.
63+
64+
```hcl
65+
data "coder_parameter" "dotfiles_url" {
66+
name = "dotfiles URL"
67+
description = "Git repository with dotfiles"
68+
mutable = true
69+
default = ""
70+
}
71+
```
72+
73+
## Mutable
74+
75+
TODO
76+
77+
## Validation
78+
79+
TODO
80+
81+
## Migration
82+
83+
TODO
84+
85+
### Terraform variables
86+
87+
TODO
88+
89+
TODO sensitive
90+
91+
## Legacy
92+
93+
Prior to Coder v0.16.0 (Jan 2023), parameters were defined via Terraform `variable` blocks. These "legacy parameters" can still be used in templates, but will be removed in April 2023.
94+
95+
```hcl
96+
variable "use_kubeconfig" {
97+
sensitive = true # Admin (template-level) parameter
98+
type = bool
99+
description = <<-EOF
100+
Use host kubeconfig? (true/false)
101+
EOF
102+
}
103+
104+
variable "cpu" {
105+
sensitive = false # User (workspace-level) parameter
106+
description = "CPU (__ cores)"
107+
default = 2
108+
validation {
109+
condition = contains([
110+
"2",
111+
"4",
112+
"6",
113+
"8"
114+
], var.cpu)
115+
error_message = "Invalid cpu!"
116+
}
117+
}
118+
```
119+
120+
> ⚠️ Legacy (`variable`) parameters and rich parameters cannot be used in the same template.

0 commit comments

Comments
 (0)