From caa6ee799eadad1d5cc362c8e4ded91c2c337830 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 12:39:51 +0200
Subject: [PATCH 01/10] docs: describe workspace tags

---
 docs/manifest.json                |   5 ++
 docs/templates/workspace-tags.md  |  55 ++++++++++++++
 examples/workspace-tags/README.md |  21 ++++++
 examples/workspace-tags/main.tf   | 119 ++++++++++++++++++++++++++++++
 4 files changed, 200 insertions(+)
 create mode 100644 docs/templates/workspace-tags.md
 create mode 100644 examples/workspace-tags/README.md
 create mode 100644 examples/workspace-tags/main.tf

diff --git a/docs/manifest.json b/docs/manifest.json
index 13b1b72cceb0f..0509e0bd3a634 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -200,6 +200,11 @@
           "description": "Prompt the template administrator for additional information about a template",
           "path": "./templates/variables.md"
         },
+        {
+          "title": "Workspace Tags",
+          "description": "Select provisioners using Coder Parameters",
+          "path": "./templates/workspace-tags.md"
+        },
         {
           "title": "Administering templates",
           "description": "Configuration settings for template admins",
diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
new file mode 100644
index 0000000000000..1788401bfe84e
--- /dev/null
+++ b/docs/templates/workspace-tags.md
@@ -0,0 +1,55 @@
+# Workspace Tags
+
+Template admins can use static template tags to restrict workspace provisioning
+to specific provisioner groups. This method has limitated flexibility as it
+prevents workspace users from creating workspaces on workspace nodes of their
+choice. Using `coder_workspace_tags` and `coder_parameter`s template admins can
+enable dynamic tag selection.
+
+## Dynamic tag selection
+
+Here is a sample `coder_workspace_tags` data resource with a couple of workspace
+tags specified:
+
+```hcl
+data "coder_workspace_tags" "custom_workspace_tags" {
+  tags = {
+    "zone"        = "developers"
+    "os"          = data.coder_parameter.os_selector.value
+    "project_id"  = "PROJECT_${data.coder_parameter.project_name.value}"
+    "cache"       = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"
+  }
+}
+```
+
+**Legend**
+
+- `zone` - static tag value set to `developers`
+- `os` - supported by string `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`,
+  `feature_cache_enabled`
+
+Review the
+[full template example](https://github.com/coder/coder/tree/main/examples/workspace-tags)
+using `coder_workspace_tags` and `coder_parameter`s.
+
+## Limitations
+
+### Parameters types
+
+Provisioners require job tags to be defined in the 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`.
+
+#### Mutability
+
+TODO
+
+### HCL syntax
+
+TODO
diff --git a/examples/workspace-tags/README.md b/examples/workspace-tags/README.md
new file mode 100644
index 0000000000000..d424630a68fad
--- /dev/null
+++ b/examples/workspace-tags/README.md
@@ -0,0 +1,21 @@
+---
+name: Sample Template with Workspace Tags
+description: Review the sample template and introduce workspace tags to your template
+tags: [local, docker, workspace-tags]
+icon: /icon/docker.png
+---
+
+# Overview
+
+# Use case
+
+## Development
+
+Update the template and push it using the following command:
+
+```
+./scripts/coder-dev.sh templates push examples-workspace-tags \
+  -d examples/workspace-tags \
+  --create \
+  -y
+```
diff --git a/examples/workspace-tags/main.tf b/examples/workspace-tags/main.tf
new file mode 100644
index 0000000000000..b0f19763db383
--- /dev/null
+++ b/examples/workspace-tags/main.tf
@@ -0,0 +1,119 @@
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+    }
+    docker = {
+      source = "kreuzwerker/docker"
+    }
+  }
+}
+
+data "coder_provisioner" "me" {
+}
+
+data "coder_workspace" "me" {
+}
+
+resource "coder_agent" "main" {
+  arch           = data.coder_provisioner.me.arch
+  os             = "linux"
+  startup_script = <<EOF
+    #!/bin/sh
+    # install and start code-server
+    curl -fsSL https://code-server.dev/install.sh | sh -s -- --version 4.8.3
+    code-server --auth none --port 13337
+    EOF
+
+  env = {
+    GIT_AUTHOR_NAME     = "${data.coder_workspace.me.owner}"
+    GIT_COMMITTER_NAME  = "${data.coder_workspace.me.owner}"
+    GIT_AUTHOR_EMAIL    = "${data.coder_workspace.me.owner_email}"
+    GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}"
+  }
+}
+
+resource "coder_app" "code-server" {
+  agent_id     = coder_agent.main.id
+  slug         = "code-server"
+  display_name = "code-server"
+  url          = "http://localhost:13337/?folder=/home/${local.username}"
+  icon         = "/icon/code.svg"
+  subdomain    = false
+  share        = "owner"
+
+  healthcheck {
+    url       = "http://localhost:13337/healthz"
+    interval  = 5
+    threshold = 6
+  }
+}
+
+resource "docker_volume" "home_volume" {
+  name = "coder-${data.coder_workspace.me.id}-home"
+  lifecycle {
+    ignore_changes = all
+  }
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace.me.owner
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace.me.owner_id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name_at_creation"
+    value = data.coder_workspace.me.name
+  }
+}
+
+resource "coder_metadata" "home_info" {
+  resource_id = docker_volume.home_volume.id
+
+  item {
+    key   = "size"
+    value = "5 GiB"
+  }
+}
+
+resource "docker_container" "workspace" {
+  count      = data.coder_workspace.me.start_count
+  image      = "ubuntu:22.04"
+  name       = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
+  hostname   = data.coder_workspace.me.name
+  entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")]
+  env = [
+    "CODER_AGENT_TOKEN=${coder_agent.main.token}",
+  ]
+  host {
+    host = "host.docker.internal"
+    ip   = "host-gateway"
+  }
+  volumes {
+    container_path = "/home/${local.username}"
+    volume_name    = docker_volume.home_volume.name
+    read_only      = false
+  }
+
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace.me.owner
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace.me.owner_id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name"
+    value = data.coder_workspace.me.name
+  }
+}

From 1042d5bcd25251efcb3c01ecde6064f5d5c32a2e Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 13:49:16 +0200
Subject: [PATCH 02/10] WIP

---
 docs/templates/workspace-tags.md | 44 +++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index 1788401bfe84e..0ee88de606bae 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -1,10 +1,12 @@
 # Workspace Tags
 
 Template admins can use static template tags to restrict workspace provisioning
-to specific provisioner groups. This method has limitated flexibility as it
+to specific provisioner groups. This method has limited flexibility as it
 prevents workspace users from creating workspaces on workspace nodes of their
-choice. Using `coder_workspace_tags` and `coder_parameter`s template admins can
-enable dynamic tag selection.
+choice.
+
+Using `coder_workspace_tags` and `coder_parameter`s template admins can enable
+dynamic tag selection, and mutate static template tags.
 
 ## Dynamic tag selection
 
@@ -36,7 +38,16 @@ Review the
 [full template example](https://github.com/coder/coder/tree/main/examples/workspace-tags)
 using `coder_workspace_tags` and `coder_parameter`s.
 
-## Limitations
+## Contraints
+
+### 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.
+
+Before releasing the template version with configurable workspace tags, make
+sure that every tag set is related with at least one healthy provisioner.
 
 ### Parameters types
 
@@ -46,10 +57,29 @@ 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`.
 
-#### Mutability
+### Mutability
 
-TODO
+A mutable `coder_parameter` might 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.
 
 ### HCL syntax
 
-TODO
+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,
+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`:
+  `foobar_tag = data.coder_parameter.foobar.value`
+- boolean logic: `production_tag = !data.coder_parameter.staging_env.value`
+- condition:
+  `cache = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"`

From f3016fbf99affd08d14f985aa6c59585f51bfa8d Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 13:53:30 +0200
Subject: [PATCH 03/10] typos

---
 docs/templates/workspace-tags.md | 70 ++++++++++++++++----------------
 1 file changed, 35 insertions(+), 35 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index 0ee88de606bae..a7bfef58908f9 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -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" {
@@ -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
@@ -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"`

From 0c6c844174a54dd111f7c5ac6aa69223a76ad3c5 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 13:55:03 +0200
Subject: [PATCH 04/10] link

---
 docs/templates/workspace-tags.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index a7bfef58908f9..fdeb36e8f6208 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -69,8 +69,8 @@ as immutable and set only once, during workspace creation.
 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
+the [Hashicorp HCL library](https://github.com/hashicorp/hcl) 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.
 

From 7443d42e54338e3f95f6b68e6c10afc172dcbd97 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 14:02:00 +0200
Subject: [PATCH 05/10] typo

---
 docs/templates/workspace-tags.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index fdeb36e8f6208..fff9601ccb478 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -38,7 +38,7 @@ Review the
 [full template example](https://github.com/coder/coder/tree/main/examples/workspace-tags)
 using `coder_workspace_tags` and `coder_parameter`s.
 
-## Contraints
+## Constraints
 
 ### Tagged provisioners
 

From 716d01e5d43344c5745b748b5d832cf27f8d4c39 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 14:15:43 +0200
Subject: [PATCH 06/10] example

---
 examples/parameters-dynamic-options/README.md |  1 -
 examples/workspace-tags/README.md             |  9 +++-
 examples/workspace-tags/main.tf               | 51 +++++++++++++++++++
 3 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/examples/parameters-dynamic-options/README.md b/examples/parameters-dynamic-options/README.md
index 2c6c00d6acc83..b1c3f2dd3c5e0 100644
--- a/examples/parameters-dynamic-options/README.md
+++ b/examples/parameters-dynamic-options/README.md
@@ -35,6 +35,5 @@ Update the template and push it using the following command:
 ./scripts/coder-dev.sh templates push examples-parameters-dynamic-options \
   -d examples/parameters-dynamic-options \
   --variables-file examples/parameters-dynamic-options/variables.yml \
-  --create \
   -y
 ```
diff --git a/examples/workspace-tags/README.md b/examples/workspace-tags/README.md
index d424630a68fad..f3fbc86ae8fc1 100644
--- a/examples/workspace-tags/README.md
+++ b/examples/workspace-tags/README.md
@@ -1,14 +1,20 @@
 ---
 name: Sample Template with Workspace Tags
-description: Review the sample template and introduce workspace tags to your template
+description: Review the sample template and introduce dynamic workspace tags to your template
 tags: [local, docker, workspace-tags]
 icon: /icon/docker.png
 ---
 
 # Overview
 
+This Coder template presents use of [Workspace Tags](https://coder.com/docs/v2/latest/templates/workspace-tags) [Coder Parameters](https://coder.com/docs/v2/latest/templates/parameters).
+
 # Use case
 
+Template administrators can use static tags to control workspace provisioning, limiting it to specific provisioner groups. However, this restricts workspace users from choosing their preferred workspace nodes.
+
+By using `coder_workspace_tags` and `coder_parameter`s, template administrators can allow dynamic tag selection, avoiding the need to push the same template multiple times with different tags.
+
 ## Development
 
 Update the template and push it using the following command:
@@ -16,6 +22,5 @@ Update the template and push it using the following command:
 ```
 ./scripts/coder-dev.sh templates push examples-workspace-tags \
   -d examples/workspace-tags \
-  --create \
   -y
 ```
diff --git a/examples/workspace-tags/main.tf b/examples/workspace-tags/main.tf
index b0f19763db383..a1a06c695119b 100644
--- a/examples/workspace-tags/main.tf
+++ b/examples/workspace-tags/main.tf
@@ -9,12 +9,63 @@ terraform {
   }
 }
 
+locals {
+  username = data.coder_workspace.me.owner
+}
+
 data "coder_provisioner" "me" {
 }
 
 data "coder_workspace" "me" {
 }
 
+data "coder_workspace_tags" "custom_workspace_tags" {
+  tags = {
+    "zone"       = "developers"
+    "os"         = data.coder_parameter.os_selector.value
+    "project_id" = "PROJECT_${data.coder_parameter.project_name.value}"
+    "cache"      = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"
+  }
+}
+
+data "coder_parameter" "os_selector" {
+  name         = "os_selector"
+  display_name = "OS runtime"
+  default      = "linux"
+
+  option {
+    name  = "Linux"
+    value = "linux"
+  }
+  option {
+    name  = "OSX"
+    value = "osx"
+  }
+  option {
+    name  = "Windows"
+    value = "windows"
+  }
+
+  mutable = false
+}
+
+data "coder_parameter" "project_name" {
+  name         = "project_name"
+  display_name = "Project name"
+  description  = "Specify the project name."
+
+  mutable = false
+}
+
+data "coder_parameter" "feature_cache_enabled" {
+  name         = "feature_cache_enabled"
+  display_name = "Enable cache?"
+  type         = "bool"
+  default      = false
+
+  mutable = false
+}
+
 resource "coder_agent" "main" {
   arch           = data.coder_provisioner.me.arch
   os             = "linux"

From b43d8a1338c18780a5d4b94e35739da075d18355 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 14:46:00 +0200
Subject: [PATCH 07/10] lacks

---
 docs/templates/workspace-tags.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index fff9601ccb478..bb0625f23d898 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -2,8 +2,8 @@
 
 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.
+flexibility and lacks the capability to allow users to choose the nodes on which
+they create workspaces.
 
 By using `coder_workspace_tags` and `coder_parameter`s, template administrators
 can enable dynamic tag selection and modify static template tags.

From 883a17d6bd5ef7b9db3f1cd4f79ee3129b573434 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 14:55:28 +0200
Subject: [PATCH 08/10] rephrased

---
 docs/templates/workspace-tags.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index bb0625f23d898..55eeaf83589b3 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -1,9 +1,10 @@
 # Workspace Tags
 
-Template administrators can use static template tags to restrict workspace
-provisioning to specific provisioner groups. However, this method has limited
-flexibility and lacks the capability to allow users to choose the nodes on which
-they create workspaces.
+Template administrators can leverage static template tags to limit workspace
+provisioning to designated provisioner groups that have locally deployed
+credentials for creating workspace resources. While this method ensures
+controlled access, it offers limited flexibility and does not permit users to
+select the nodes for their workspace creation.
 
 By using `coder_workspace_tags` and `coder_parameter`s, template administrators
 can enable dynamic tag selection and modify static template tags.

From cfd0c2364da9dea471fdc0c6658ffdf68fb5f269 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 15:04:49 +0200
Subject: [PATCH 09/10] rename os to runtime

---
 docs/templates/workspace-tags.md | 13 +++++++------
 examples/workspace-tags/main.tf  | 22 +++++++++++-----------
 2 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index 55eeaf83589b3..72cc4e1309263 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -18,7 +18,7 @@ specified:
 data "coder_workspace_tags" "custom_workspace_tags" {
   tags = {
     "zone"        = "developers"
-    "os"          = data.coder_parameter.os_selector.value
+    "runtime"     = data.coder_parameter.runtime_selector.value
     "project_id"  = "PROJECT_${data.coder_parameter.project_name.value}"
     "cache"       = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"
   }
@@ -28,8 +28,8 @@ data "coder_workspace_tags" "custom_workspace_tags" {
 **Legend**
 
 - `zone` - static tag value set to `developers`
-- `os` - supported by the string-type `coder_parameter` to select OS
-  runtime,`os_selector`
+- `runtime` - supported by the string-type `coder_parameter` to select
+  provisioner runtime, `runtime_selector`
 - `project_id` - a formatted string supported by the string-type
   `coder_parameter`, `project_name`
 - `cache` - an HCL condition involving boolean-type `coder_parameter`,
@@ -54,9 +54,10 @@ that every tag set is associated with at least one healthy provisioner.
 
 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`), the
-Coder provisioner server can transform only the following parameter types to
-strings: _string_, _number_, and _bool_.
+formatter, for example,
+(`"runtime" = data.coder_parameter.runtime_selector.value`), the Coder
+provisioner server can transform only the following parameter types to strings:
+_string_, _number_, and _bool_.
 
 ### Mutability
 
diff --git a/examples/workspace-tags/main.tf b/examples/workspace-tags/main.tf
index a1a06c695119b..f74286741cbb0 100644
--- a/examples/workspace-tags/main.tf
+++ b/examples/workspace-tags/main.tf
@@ -22,28 +22,28 @@ data "coder_workspace" "me" {
 data "coder_workspace_tags" "custom_workspace_tags" {
   tags = {
     "zone"       = "developers"
-    "os"         = data.coder_parameter.os_selector.value
+    "runtime"    = data.coder_parameter.runtime_selector.value
     "project_id" = "PROJECT_${data.coder_parameter.project_name.value}"
     "cache"      = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"
   }
 }
 
-data "coder_parameter" "os_selector" {
-  name         = "os_selector"
-  display_name = "OS runtime"
-  default      = "linux"
+data "coder_parameter" "runtime_selector" {
+  name         = "runtime_selector"
+  display_name = "Provisioner Runtime"
+  default      = "development"
 
   option {
-    name  = "Linux"
-    value = "linux"
+    name  = "Development (free zone)"
+    value = "development"
   }
   option {
-    name  = "OSX"
-    value = "osx"
+    name  = "Staging (internal access)"
+    value = "staging"
   }
   option {
-    name  = "Windows"
-    value = "windows"
+    name  = "Production (air-gapped)"
+    value = "production"
   }
 
   mutable = false

From 12a292cace64eae25fef11643680c398329326e8 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 23 May 2024 15:12:06 +0200
Subject: [PATCH 10/10] Cian's review

---
 docs/manifest.json               | 2 +-
 docs/templates/workspace-tags.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/manifest.json b/docs/manifest.json
index 0509e0bd3a634..85f5c250066ff 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -202,7 +202,7 @@
         },
         {
           "title": "Workspace Tags",
-          "description": "Select provisioners using Coder Parameters",
+          "description": "Control provisioning using Workspace Tags and Parameters",
           "path": "./templates/workspace-tags.md"
         },
         {
diff --git a/docs/templates/workspace-tags.md b/docs/templates/workspace-tags.md
index 72cc4e1309263..ce886629abfe3 100644
--- a/docs/templates/workspace-tags.md
+++ b/docs/templates/workspace-tags.md
@@ -43,9 +43,9 @@ using `coder_workspace_tags` and `coder_parameter`s.
 
 ### Tagged provisioners
 
-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.
+It is possible to choose tag combinations that no provisioner can handle. This
+will cause the provisioner job to get stuck in the queue until a provisioner is
+added that can handle its combination of tags.
 
 Before releasing the template version with configurable workspace tags, ensure
 that every tag set is associated with at least one healthy provisioner.