mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: reorganize template docs (#10297)
* docs: rework our "templates" section * wikistuff * fix formatting * add diagram * reorganize some things * docs: improve workspaces and templates doc (#9139) * Reorg, updated/new screenshots, consistent terminology * First pass * Another pass * Added integration section * New outline for template pages, small updates * Revised outline for templates, added tutorial * First pass at tutorial * Some feedback from Ben. * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Fixed typos * Expanded tutorial I have read the CLA Document and I hereby sign the CLA * New screenshots, improved tutorial, revised anatomy * Improved tutorial. Anatomy is now a guided tour. * First pass at guided tour * Updated authentication info * Reorganized the guided tour * Edited more template pages * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tutorial.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Revised devcontainers and docker-in-workspaces * Edited and added screenshots * Prepared first draft, except docs/templates/open-in-coder.md * Fix typo * remove legacy parameters and migration guide * Use coder templates create * Added screenshot for workspace template variables * Made it prettier * Fixed minor typos and markdown problems * edits to repairing workspaces * fix broken links in product * Added troubleshooting, minor corrections. * fix terminal links * fmt --------- Co-authored-by: Muhammad Atif Ali <matifali@live.com> Co-authored-by: Ben Potter <me@bpmct.net> Co-authored-by: Atif Ali <atif@coder.com> * make fmt * fix merge conflict * make fmt * make gen * update * lint * Discard changes to coderd/database/queries.sql.go * Discard changes to cli/templates.go * Discard changes to cli/templateversionarchive.go * Discard changes to cli/templateversions.go * Update docker-in-workspaces.md * replace ```sh with ```shell * open-in-coder * fmt * mention coder_metadata in icons.md * resource_metadata * use shell * modules.md * mention coder registry module * workspace.md * resource_metadata * remove duplication * address comments * cleanup * fmt * fix broken links * fix numbering * mention module registry * add example * demote heading * remove top level entry from manifest * fmt --------- Co-authored-by: Ben <me@bpmct.net> Co-authored-by: Marc Paquette <22124737+marcpaq@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
co-authored by
Muhammad Atif Ali
Ben Potter
Marc Paquette
Muhammad Atif Ali
Ben Potter
Marc Paquette
parent
b5e5b39de2
commit
a49e6b88f9
Vendored
+61
-149
@@ -1,10 +1,19 @@
|
||||
# Parameters
|
||||
|
||||
Templates can contain _parameters_, which allow prompting the user for
|
||||
additional information when creating workspaces in both the UI and CLI.
|
||||
A template can prompt the user for additional information when creating
|
||||
workspaces with
|
||||
[_parameters_](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter).
|
||||
|
||||
|
||||
|
||||
The user can set parameters in the dashboard UI and CLI.
|
||||
|
||||
You'll likely want to hardcode certain template properties for workspaces, such
|
||||
as security group. But you can let developers specify other properties with
|
||||
parameters like instance size, geographical location, repository URL, etc.
|
||||
|
||||
This example lets a developer choose a Docker host for the workspace:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "docker_host" {
|
||||
name = "Region"
|
||||
@@ -33,7 +42,7 @@ data "coder_parameter" "docker_host" {
|
||||
}
|
||||
```
|
||||
|
||||
From there, parameters can be referenced during build-time:
|
||||
From there, a template can refer to a parameter's value:
|
||||
|
||||
```hcl
|
||||
provider "docker" {
|
||||
@@ -41,21 +50,19 @@ provider "docker" {
|
||||
}
|
||||
```
|
||||
|
||||
> For a complete list of supported parameter properties, see the
|
||||
> [coder_parameter Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter)
|
||||
|
||||
## Types
|
||||
|
||||
The following parameter types are supported: `string`, `list(string)`, `bool`,
|
||||
and `number`.
|
||||
A Coder parameter can have one of these types:
|
||||
|
||||
### List of strings
|
||||
- `string`
|
||||
- `bool`
|
||||
- `number`.
|
||||
- `list(string)`
|
||||
|
||||
List of strings is a specific parameter type, that can't be easily mapped to the
|
||||
default value, which is string type. Parameters with the `list(string)` type
|
||||
must be converted to JSON arrays using
|
||||
To specify a default value for a parameter with the `list(string)` type, use a
|
||||
JSON array and the Terraform
|
||||
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
|
||||
function.
|
||||
function. For example:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "security_groups" {
|
||||
@@ -74,7 +81,7 @@ data "coder_parameter" "security_groups" {
|
||||
|
||||
## Options
|
||||
|
||||
A _string_ parameter can provide a set of options to limit the choice:
|
||||
A `string` parameter can provide a set of options to limit the user's choices:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "docker_host" {
|
||||
@@ -135,9 +142,8 @@ Example:
|
||||
|
||||
## Required and optional parameters
|
||||
|
||||
A parameter is considered to be _required_ if it doesn't have the `default`
|
||||
property. The user **must** provide a value to this parameter before creating a
|
||||
workspace.
|
||||
A parameter is _required_ if it doesn't have the `default` property. The user
|
||||
**must** provide a value to this parameter before creating a workspace:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "account_name" {
|
||||
@@ -170,30 +176,18 @@ data "coder_parameter" "dotfiles_url" {
|
||||
}
|
||||
```
|
||||
|
||||
Terraform
|
||||
[conditional expressions](https://developer.hashicorp.com/terraform/language/expressions/conditionals)
|
||||
can be used to determine whether the user specified a value for an optional
|
||||
parameter:
|
||||
|
||||
```hcl
|
||||
resource "coder_agent" "main" {
|
||||
# ...
|
||||
startup_script_timeout = 180
|
||||
startup_script = <<-EOT
|
||||
set -e
|
||||
|
||||
echo "The optional parameter value is: ${data.coder_parameter.optional.value == "" ? "[empty]" : data.coder_parameter.optional.value}"
|
||||
|
||||
EOT
|
||||
}
|
||||
```
|
||||
|
||||
## Mutability
|
||||
|
||||
Immutable parameters can be only set before workspace creation, or during update
|
||||
on the first usage to set the initial value for required parameters. The idea is
|
||||
to prevent users from modifying fragile or persistent workspace resources like
|
||||
volumes, regions, etc.:
|
||||
Immutable parameters can only be set in these situations:
|
||||
|
||||
- Creating a workspace for the first time.
|
||||
- Updating a workspace to a new template version. This sets the initial value
|
||||
for required parameters.
|
||||
|
||||
The idea is to prevent users from modifying fragile or persistent workspace
|
||||
resources like volumes, regions, and so on.
|
||||
|
||||
Example:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "region" {
|
||||
@@ -204,19 +198,19 @@ data "coder_parameter" "region" {
|
||||
}
|
||||
```
|
||||
|
||||
It is allowed to modify the mutability state anytime. In case of emergency,
|
||||
template authors can temporarily allow for changing immutable parameters to fix
|
||||
an operational issue, but it is not advised to overuse this opportunity.
|
||||
You can modify a parameter's `mutable` attribute state anytime. In case of
|
||||
emergency, you can temporarily allow for changing immutable parameters to fix an
|
||||
operational issue, but it is not advised to overuse this opportunity.
|
||||
|
||||
## Ephemeral parameters
|
||||
|
||||
Ephemeral parameters are introduced to users in the form of "build options."
|
||||
This functionality can be used to model specific behaviors within a Coder
|
||||
workspace, such as reverting to a previous image, restoring from a volume
|
||||
snapshot, or building a project without utilizing cache.
|
||||
Ephemeral parameters are introduced to users in the form of "build options." Use
|
||||
ephemeral parameters to model specific behaviors in a Coder workspace, such as
|
||||
reverting to a previous image, restoring from a volume snapshot, or building a
|
||||
project without using cache.
|
||||
|
||||
As these parameters are ephemeral in nature, subsequent builds will proceed in
|
||||
the standard manner.
|
||||
Since these parameters are ephemeral in nature, subsequent builds proceed in the
|
||||
standard manner:
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "force_rebuild" {
|
||||
@@ -229,17 +223,18 @@ data "coder_parameter" "force_rebuild" {
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
## Validating parameters
|
||||
|
||||
Rich parameters support multiple validation modes - min, max, monotonic numbers,
|
||||
and regular expressions.
|
||||
Coder supports rich parameters with multiple validation modes: min, max,
|
||||
monotonic numbers, and regular expressions.
|
||||
|
||||
### Number
|
||||
|
||||
A _number_ parameter can be limited to boundaries - min, max. Additionally, the
|
||||
monotonicity (`increasing` or `decreasing`) between the current parameter value
|
||||
and the new one can be verified too. Monotonicity can be enabled for resources
|
||||
that can't be shrunk without implications, for instance - disk volume size.
|
||||
You can limit a `number` parameter to `min` and `max` boundaries.
|
||||
|
||||
You can also specify its monotonicity as `increasing` or `decreasing` to verify
|
||||
the current and new values. Use the `monotonic` aatribute for resources that
|
||||
can't be shrunk or grown without implications, like disk volume size.
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "instances" {
|
||||
@@ -256,9 +251,8 @@ data "coder_parameter" "instances" {
|
||||
|
||||
### String
|
||||
|
||||
A _string_ parameter can have a regular expression defined to make sure that the
|
||||
parameter value matches the pattern. The `regex` property requires a
|
||||
corresponding `error` property.
|
||||
You can validate a `string` parameter to match a regular expression. The `regex`
|
||||
property requires a corresponding `error` property.
|
||||
|
||||
```hcl
|
||||
data "coder_parameter" "project_id" {
|
||||
@@ -266,106 +260,24 @@ data "coder_parameter" "project_id" {
|
||||
description = "Alpha-numeric project ID"
|
||||
validation {
|
||||
regex = "^[a-z0-9]+$"
|
||||
error = "Unfortunately, it isn't a valid project ID"
|
||||
error = "Unfortunately, this isn't a valid project ID"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Legacy
|
||||
|
||||
### Legacy parameters are unsupported now
|
||||
|
||||
In Coder, workspaces using legacy parameters can't be deployed anymore. To
|
||||
address this, it is necessary to either remove or adjust incompatible templates.
|
||||
In some cases, deleting a workspace with a hard dependency on a legacy parameter
|
||||
may be challenging. To cleanup unsupported workspaces, administrators are
|
||||
advised to take the following actions for affected templates:
|
||||
|
||||
1. Enable the `feature_use_managed_variables` provider flag.
|
||||
2. Ensure that every legacy variable block has defined missing default values,
|
||||
or convert it to `coder_parameter`.
|
||||
3. Push the new template version using UI or CLI.
|
||||
4. Update unsupported workspaces to the newest template version.
|
||||
5. Delete the affected workspaces that have been updated to the newest template
|
||||
version.
|
||||
|
||||
### Migration
|
||||
|
||||
> ⚠️ Migration is available until v0.24.0 (Jun 2023) release.
|
||||
|
||||
Terraform `variable` shouldn't be used for workspace scoped parameters anymore,
|
||||
and it's required to convert `variable` to `coder_parameter` resources. To make
|
||||
the migration smoother, there is a special property introduced -
|
||||
`legacy_variable` and `legacy_variable_name` , which can link `coder_parameter`
|
||||
with a legacy variable.
|
||||
|
||||
```hcl
|
||||
variable "legacy_cpu" {
|
||||
sensitive = false
|
||||
description = "CPU cores"
|
||||
default = 2
|
||||
}
|
||||
|
||||
data "coder_parameter" "cpu" {
|
||||
name = "CPU cores"
|
||||
type = "number"
|
||||
description = "Number of CPU cores"
|
||||
mutable = true
|
||||
|
||||
legacy_variable_name = "legacy_cpu"
|
||||
legacy_variable = var.legacy_cpu
|
||||
}
|
||||
```
|
||||
|
||||
#### Steps
|
||||
|
||||
1. Prepare and update a new template version:
|
||||
|
||||
- Add `coder_parameter` resource matching the legacy variable to migrate.
|
||||
- Use `legacy_variable_name` and `legacy_variable` to link the
|
||||
`coder_parameter` to the legacy variable.
|
||||
- Mark the new parameter as `mutable`, so that Coder will not block updating
|
||||
existing workspaces.
|
||||
|
||||
2. Update all workspaces to the updated template version. Coder will populate
|
||||
the added `coder_parameter`s with values from legacy variables.
|
||||
3. Prepare another template version:
|
||||
|
||||
- Remove the migrated variables.
|
||||
- Remove properties `legacy_variable` and `legacy_variable_name` from
|
||||
`coder_parameter`s.
|
||||
|
||||
4. Update all workspaces to the updated template version (2nd).
|
||||
5. Prepare a third template version:
|
||||
|
||||
- Enable the `feature_use_managed_variables` provider flag to use managed
|
||||
Terraform variables for template customization. Once the flag is enabled,
|
||||
legacy variables won't be used.
|
||||
|
||||
6. Update all workspaces to the updated template version (3rd).
|
||||
7. Delete legacy parameters.
|
||||
|
||||
As a template improvement, the template author can consider making some of the
|
||||
new `coder_parameter` resources `mutable`.
|
||||
|
||||
## Terraform template-wide variables
|
||||
|
||||
> ⚠️ Flag `feature_use_managed_variables` is available until v0.25.0 (Jul 2023)
|
||||
> release. After this release, template-wide Terraform variables will be enabled
|
||||
> by default.
|
||||
|
||||
As parameters are intended to be used only for workspace customization purposes,
|
||||
Terraform variables can be freely managed by the template author to build
|
||||
templates. Workspace users are not able to modify template variables.
|
||||
|
||||
The template author can enable Terraform template-wide variables mode by
|
||||
specifying the following flag:
|
||||
|
||||
```hcl
|
||||
provider "coder" {
|
||||
feature_use_managed_variables = "true"
|
||||
}
|
||||
```
|
||||
|
||||
Once it's defined, coder will allow for modifying variables by using CLI and UI
|
||||
forms, but it will not be possible to use legacy parameters.
|
||||
variable "CLOUD_API_KEY" {
|
||||
type = string
|
||||
description = "API key for the service"
|
||||
default = "1234567890"
|
||||
sensitive = true
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user