From 2ad6f66ff802ed7665d0234205859ea333d57589 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Thu, 21 Nov 2024 18:08:29 +0000 Subject: [PATCH 1/2] chore(docs): update documentation for `coder_workspace_tags` --- .../extending-templates/workspace-tags.md | 35 +++++++++++++++++-- examples/workspace-tags/README.md | 8 +++++ examples/workspace-tags/main.tf | 2 +- 3 files changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md index 2f7df96cba681..83ea983ce72ba 100644 --- 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,7 +95,7 @@ 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 | | :----------------- | :-------------------------------------------- | @@ -78,7 +103,7 @@ We recommend using only the following as inputs for `coder_workspace_tags`: | 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 index 6d7dca733fe8d..154a94f94e5fb 100644 --- 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 index b7f0874a661d1..6b70f82a6e8f8 100644 --- 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 } From 9f3812f99a02c079f67e9ddbbe0e830c9d1e5561 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Thu, 21 Nov 2024 18:10:04 +0000 Subject: [PATCH 2/2] make fmt --- examples/workspace-tags/README.md | 6 +++--- examples/workspace-tags/main.tf | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/workspace-tags/README.md b/examples/workspace-tags/README.md index 154a94f94e5fb..7a42bc05d1825 100644 --- a/examples/workspace-tags/README.md +++ b/examples/workspace-tags/README.md @@ -17,9 +17,9 @@ By using `coder_workspace_tags` and `coder_parameter`s, template administrators # 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. +- 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. diff --git a/examples/workspace-tags/main.tf b/examples/workspace-tags/main.tf index 6b70f82a6e8f8..9b8dd64ff4e80 100644 --- a/examples/workspace-tags/main.tf +++ b/examples/workspace-tags/main.tf @@ -54,8 +54,8 @@ data "coder_parameter" "project_name" { name = "project_name" display_name = "Project name" description = "Specify the project name." - default = "SUPERSECRET" - mutable = false + default = "SUPERSECRET" + mutable = false } data "coder_parameter" "feature_cache_enabled" { pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy