Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
typos
  • Loading branch information
mtojek committed May 23, 2024
commit f3016fbf99affd08d14f985aa6c59585f51bfa8d
70 changes: 35 additions & 35 deletions docs/templates/workspace-tags.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# Workspace Tags

Template admins can use static template tags to restrict workspace provisioning
to specific provisioner groups. This method has limited flexibility as it
prevents workspace users from creating workspaces on workspace nodes of their
choice.
Template administrators can use static template tags to restrict workspace
provisioning to specific provisioner groups. However, this method has limited
flexibility as it prevents workspace users from creating workspaces on nodes of
their choice.

Using `coder_workspace_tags` and `coder_parameter`s template admins can enable
dynamic tag selection, and mutate static template tags.
By using `coder_workspace_tags` and `coder_parameter`s, template administrators
can enable dynamic tag selection and modify static template tags.

## Dynamic tag selection

Here is a sample `coder_workspace_tags` data resource with a couple of workspace
tags specified:
Here is a sample `coder_workspace_tags` data resource with a few workspace tags
specified:

```hcl
data "coder_workspace_tags" "custom_workspace_tags" {
Expand All @@ -27,11 +27,11 @@ data "coder_workspace_tags" "custom_workspace_tags" {
**Legend**

- `zone` - static tag value set to `developers`
- `os` - supported by string `coder_parameter` to select OS
- `os` - supported by the string-type `coder_parameter` to select OS
runtime,`os_selector`
- `project_id` - a formatted string supported by string `coder_parameter`,
`project_name`
- `cache` - an HCL condition involving boolean `coder_parameter`,
- `project_id` - a formatted string supported by the string-type
`coder_parameter`, `project_name`
- `cache` - an HCL condition involving boolean-type `coder_parameter`,
`feature_cache_enabled`

Review the
Expand All @@ -42,44 +42,44 @@ using `coder_workspace_tags` and `coder_parameter`s.

### Tagged provisioners

With incorrectly selected workspace tags it is possible to pick a tag
configuration that is not observed by any provisioner, and make the provisioner
job stuck in the queue indefinitely.
With incorrectly selected workspace tags, it is possible to choose a tag
configuration that is not observed by any provisioner, causing the provisioner
job to get stuck in the queue indefinitely.

Before releasing the template version with configurable workspace tags, make
sure that every tag set is related with at least one healthy provisioner.
Before releasing the template version with configurable workspace tags, ensure
that every tag set is associated with at least one healthy provisioner.

### Parameters types

Provisioners require job tags to be defined in the plain string format. When a
Provisioners require job tags to be defined in plain string format. When a
workspace tag refers to a `coder_parameter` without involving the string
formatter, for example (`"os" = data.coder_parameter.os_selector.value`), Coder
provisioner server can transform to strings only following parameter types:
`string`, `number`, and `bool`.
formatter, for example, (`"os" = data.coder_parameter.os_selector.value`), the
Coder provisioner server can transform only the following parameter types to
strings: _string_, _number_, and _bool_.

### Mutability

A mutable `coder_parameter` might be dangerous for a workspace tag as it allows
A mutable `coder_parameter` can be dangerous for a workspace tag as it allows
the workspace owner to change a provisioner group (due to different tags). In
majority of use cases, `coder_parameter`s backing `coder_workspace_tags` should
be marked as _immutable_ and set only once, during the workspace creation.
most cases, `coder_parameter`s backing `coder_workspace_tags` should be marked
as immutable and set only once, during workspace creation.

### HCL syntax

While importing the template version with `coder_workspace_tags`, Coder
provisioner server extracts raw partial query for every workspace tag and stores
it in the database. During workspace build time, Coder server uses
[Hashicorp HCL library](github.com/hashicorp/hcl/v2) to evaluate these raw
queries _in-the-fly_ without processing the entire Terraform template. Such
evaluation is simpler, but also limited in terms of available functions,
When importing the template version with `coder_workspace_tags`, the Coder
provisioner server extracts raw partial queries for each workspace tag and
stores them in the database. During workspace build time, the Coder server uses
the [Hashicorp HCL library](github.com/hashicorp/hcl/v2) to evaluate these raw
queries on-the-fly without processing the entire Terraform template. This
evaluation is simpler but also limited in terms of available functions,
variables, and references to other resources.

**Supported syntax**

- static string: `foobar_tag = "foobaz"`
- formatted string: `foobar_tag = "foobaz ${data.coder_parameter.foobaz.value}"`
- reference to `coder_parameter`:
- Static string: `foobar_tag = "foobaz"`
- Formatted string: `foobar_tag = "foobaz ${data.coder_parameter.foobaz.value}"`
- Reference to `coder_parameter`:
`foobar_tag = data.coder_parameter.foobar.value`
- boolean logic: `production_tag = !data.coder_parameter.staging_env.value`
- condition:
- Boolean logic: `production_tag = !data.coder_parameter.staging_env.value`
- Condition:
`cache = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"`