- Notifications
You must be signed in to change notification settings - Fork1k
chore(docs): update documentation for coder_workspace_tags#15620
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Changes fromall commits
File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
matifali marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| 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. | ||
Comment on lines +67 to +68 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Can we be sure that the error is explicit and inform the user on how to fix it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. There are some UI improvements to be made, but here are the main messages:
I'd rather not over-index on documenting package-level errors in documentation, but I can document these if you think it's necessary? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. It should end up in the API response returned by the backend, so all the FE needs to do is display it to the user 👍 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I think we should create an issue in coder/internal to track adding terraform errors to API response. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I agree, but this might already be in the scope of#15447 Your call though! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Yes ✅ | ||
| ### 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. | ||
| You mayonly 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` | | ||
Comment on lines +98 to 104 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. But the value of the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. No, the default must be specified in the | ||
| Passing template tags in from other data sourcesor 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` | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Are we exposing an explicit error if this is not the case to inform the user on what they can do to fix it. Think about it in context of#15447 . There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. See below comment, but TL;DR yes. | ||
| See [Workspace Tags](https://coder.com/docs/templates/workspace-tags) for more information. | ||
| ## Development | ||
| Update the template and push it using the following command: | ||
Uh oh!
There was an error while loading.Please reload this page.