A template can prompt the user for additional information when creatingworkspaces withparameters.

The user can set parameters in the dashboard UI and CLI.

You'll likely want to hardcode certain template properties for workspaces, suchas security group. But you can let developers specify other properties withparameters like instance size, geographical location, repository URL, etc.

This example lets a developer choose a Docker host for the workspace:

From there, a template can refer to a parameter's value:

Types

A Coder parameter can have one of these types:

• string
• bool
• number
• list(string)

To specify a default value for a parameter with thelist(string) type, use aJSON array and the Terraformjsonencodefunction. For example:

Options

Astring parameter can provide a set of options to limit the user's choices:

Incompatibility in Parameter Options for Workspace Builds

When creating Coder templates, authors have the flexibility to modify parameteroptions associated with rich parameters. Such modifications can involve adding,substituting, or removing a parameter option. It's important to note that makingthese changes can lead to discrepancies in parameter values utilized by ongoingworkspace builds.

Consequently, workspace users will be prompted to select the new value from apop-up window or by using the command-line interface. While this additionalinteractive step might seem like an interruption, it serves a crucial purpose.It prevents workspace users from becoming trapped with outdated templateversions, ensuring they can smoothly update their workspace without anyhindrances.

Example:

• Bob creates a workspace using thepython-dev template. This template has aparameterimage_tag, and Bob selects1.12.
• Later, the template author Alice is notified of a critical vulnerability in apackage installed in thepython-dev template, which affects the image tag1.12.
• Alice remediates this vulnerability, and pushes an updated template versionthat replaces option1.12 with1.13 for theimage_tag parameter. Shethen notifies all users of that template to update their workspaceimmediately.
• Bob saves their work, and selects theUpdate option in the UI. As theirworkspace uses the now-invalid option1.12, for theimage_tag parameter,they are prompted to select a new value forimage_tag.

Required and optional parameters

A parameter isrequired if it doesn't have thedefault property. The usermust provide a value to this parameter before creating a workspace:

If a parameter contains thedefault property, Coder will use this value if theuser does not specify any:

Admins can also set thedefault property to an empty value so that theparameter field can remain empty:

Mutability

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 workspaceresources like volumes, regions, and so on.

Example:

If a required parameter is empty or if the workspace creation page detects an incompatibility between selectedparameters, theCreate workspace button is disabled until the issues are resolved.

Ephemeral parameters

Ephemeral parameters are introduced to users in order to model specificbehaviors in a Coder workspace, such as reverting to a previous image, restoringfrom a volume snapshot, or building a project without using cache. Theseparameters are only settable when starting, updating, or restarting a workspaceand do not persist after the workspace is stopped.

Since these parameters are ephemeral in nature, subsequent builds proceed in thestandard manner:

Validating parameters

Coder supports parameters with multiple validation modes: min, max,monotonic numbers, and regular expressions.

Number

You can limit anumber parameter tomin andmax boundaries.

You can also specify its monotonicity asincreasing ordecreasing to verifythe current and new values. Use themonotonic attribute for resources thatcan't be shrunk or grown without implications, like disk volume size.

It is possible to override the defaulterror message for anumber parameter,along with its associatedmin and/ormax properties. The following messageplaceholders are available{min},{max}, and{value}.

String

You can validate astring parameter to match a regular expression. Theregexproperty requires a correspondingerror property.

Workspace presets

Workspace presets allow you to configure commonly used combinations of parametersinto a single option, which makes it easier for developers to pick one that fitstheir needs.

Use thecoder_workspace_presetdata source to define the preset parameters. After you save the template file,the presets will be available for all new workspace deployments.

Optional preset fields

In addition to the requiredname andparameters fields, you can enhance yourworkspace presets with optionaldescription andicon fields:

• description: A helpful text description that provides additional contextabout the preset. This helps users understand what the preset is for and whento use it.
• icon: A visual icon displayed alongside the preset name in the UI. Useemoji icons with the format/emojis/{code}.png (e.g.,/emojis/1f1fa-1f1f8.png for the US flag emoji 🇺🇸).

For a complete list of all available fields, see theTerraform provider documentation.

Create Autofill

When the template doesn't specify default values, Coder may still autofillparameters in one of two ways:

• Coder will look for URL query parameters with formparam.<name>=<value>.

  This feature enables platform teams to create pre-filled template creation links.

• Coder can populate recently used parameter key-value pairs for the user.This feature helps reduce repetition when filling common parameters such asdotfiles_url orregion.

  To enable this feature, you need to set theauto-fill-parameters experiment flag:

  coder server --experiments=auto-fill-parameters

  Or set theenvironment variable,CODER_EXPERIMENTS=auto-fill-parameters

Dynamic Parameters

Coder v2.24.0 introducesDynamic Parameters to extend the existing parameter system withconditional form controls, enriched input types, and user identity awareness.This feature allows template authors to create interactive workspace creation forms, meaning more environmentcustomization and fewer templates to maintain.

You can read more in theDynamic Parameters documentation and try it out in theParameters Playground.