fixup! chore(docs): add notes regarding provisioner tags and untagged jobs

johnstcn · johnstcn · commit 481104e48e2a · 2024-10-15T14:26:59.000+01:00
diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md
@@ -154,7 +154,9 @@ This can also be done in the UI when building a template:
 
 Alternatively, a template can target a provisioner via
 [workspace tags](https://github.com/coder/coder/tree/main/examples/workspace-tags)
-inside the Terraform.
+inside the Terraform. See the
+[workspace tags documentation](../admin/templates/extending-templates/workspace-tags.md)
+for more information.
 
 > [!NOTE] Workspace tags defined with the `coder_workspace_tags` data source
 > template **do not** automatically apply to the template import job! You may
diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md
@@ -17,6 +17,7 @@ specified:
 ```tf
 data "coder_workspace_tags" "custom_workspace_tags" {
   tags = {
+    "az"          = var.az
     "zone"        = "developers"
     "runtime"     = data.coder_parameter.runtime_selector.value
     "project_id"  = "PROJECT_${data.coder_parameter.project_name.value}"
@@ -50,6 +51,9 @@ 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.
 
+> [!NOTE] It may be useful to run at least one provisioner with no additional
+> tag restrictions that is able to take on any job.
+
 ### Parameters types
 
 Provisioners require job tags to be defined in plain string format. When a
@@ -66,6 +70,14 @@ 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 only using the following as inputs for `coder_workspace_tags`:**
+
+- Static values (e.g. `"developers"`),
+- Template variables (e.g. `var.az`),
+- Coder parameters (e.g. `data.coder_parameter.runtime_selector.value`).
+
+Passing template tags in from other data sources may have undesired effects!
+
 ### HCL syntax
 
 When importing the template version with `coder_workspace_tags`, the Coder
