chore(docs): update documentation for coder_workspace_tags

coder · johnstcn · Nov 25, 2024 · Nov 21, 2024 · Nov 21, 2024 · Nov 21, 2024
commit 2ad6f66ff802ed7665d0234205859ea333d57589
diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md
@@ -40,8 +40,33 @@ Review the
 [full template example](https://github.com/coder/coder/tree/main/examples/workspace-tags)
 using `coder_workspace_tags` and `coder_parameter`s.
 
+## How it Works
+
+In order to correctly import a template that defines tags in
+`coder_workspace_tags`, Coder needs to know the tags to assign the template
+import job ahead of time. To work around this chicken-and-egg problem, Coder
+performs static analysis of the Terraform to determine a reasonable set of tags
+to assign to the template import job. This happens _before_ the job is started.
+
+When the template is imported, Coder will then store the _raw_ Terraform
+expressions for the values of the workspace tags for that template version. The
+next time a workspace is created from that template, Coder retrieves the stored
+raw values from the database and evaluates them using provided template
+variables and parameters. This is illustrated in the table below:
+
+| Value Type | Template Import                                    | Workspace Creation      |
+| ---------- | -------------------------------------------------- | ----------------------- |
+| Static     | `{"region": "us"}`                                 | `{"region": "us"}`      |
+| Variable   | `{"az": var.az}`                                   | `{"region": "us-east"}` |
+| Parameter  | `{"cluster": data.coder_parameter.cluster.value }` | `{"cluster": "dev"}`    |
+
 ## Constraints
 
+### Default Values
+
+All template variables and `coder_parameter` data sources **must** provide a
+default value. Failure to do so will result in an error.
+
 ### Tagged provisioners
 
 It is possible to choose tag combinations that no provisioner can handle. This
@@ -70,15 +95,15 @@ the workspace owner to change a provisioner group (due to different tags). In
 most cases, `coder_parameter`s backing `coder_workspace_tags` should be marked
 as immutable and set only once, during workspace creation.
 
-We recommend using only the following as inputs for `coder_workspace_tags`:
+You may only specify the following as inputs for `coder_workspace_tags`:
 
 |                    | Example                                       |
 | :----------------- | :-------------------------------------------- |
 | Static values      | `"developers"`                                |
 | Template variables | `var.az`                                      |
 | Coder parameters   | `data.coder_parameter.runtime_selector.value` |
 
-Passing template tags in from other data sources may have undesired effects.
+Passing template tags in from other data sources or resources is not permitted.
 
 ### HCL syntax
 
@@ -99,3 +124,9 @@ variables, and references to other resources.
 - Boolean logic: `production_tag = !data.coder_parameter.staging_env.value`
 - Condition:
   `cache = data.coder_parameter.feature_cache_enabled.value == "true" ? "with-cache" : "no-cache"`
+
+**Not supported**
+
+- Function calls: `try(var.foo, "default")`
+- Resources: `compute_instance.dev.name`
+- Data sources other than `coder_parameter`: `data.local_file.hostname.content`
diff --git a/examples/workspace-tags/README.md b/examples/workspace-tags/README.md
@@ -15,6 +15,14 @@ Template administrators can use static tags to control workspace provisioning, l
 
 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.
 
+# Notes
+
+* You will need to have an [external provisioner](https://coder.com/docs/admin/provisioners#external-provisioners) with the correct tagset running in order to import this template.
+* When specifying values for the `coder_workspace_tags` data source, you are restricted to using a subset of Terraform's capabilities.
+* You must specify default values for all data sources and variables referenced by the `coder_workspace_tags` data source.
+
+See [Workspace Tags](https://coder.com/docs/templates/workspace-tags) for more information.
+
 ## Development
 
 Update the template and push it using the following command:

diff --git a/examples/workspace-tags/main.tf b/examples/workspace-tags/main.tf
@@ -54,7 +54,7 @@ data "coder_parameter" "project_name" {
   name         = "project_name"
   display_name = "Project name"
   description  = "Specify the project name."
-
+  default = "SUPERSECRET"
   mutable = false
 }