Skip to content

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 25, 2024
Merged

chore(docs): update documentation for coder_workspace_tags #15620

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ad6f66
chore(docs): update documentation for `coder_workspace_tags`
johnstcn Nov 21, 2024
9f3812f
make fmt
johnstcn Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions docs/admin/templates/extending-templates/workspace-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +67 to +68
Copy link
Member

Choose a reason for hiding this comment

The 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?

Copy link
Member Author

Choose a reason for hiding this comment

The 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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not needed in docs but with UI enhancements but if we can parse them and show to the user that would do the work.
cc: @chrifro consider this in context of #15447.

Copy link
Member Author

Choose a reason for hiding this comment

The 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 👍

Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Member Author

Choose a reason for hiding this comment

The 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!

Copy link
Member

Choose a reason for hiding this comment

The 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
Expand Down Expand Up @@ -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` |
Comment on lines +98 to 104
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But the value of the coder_parameter can itself come from any other local, resource, or data. Right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the default must be specified in the coder_parameter data source. I'll make this more explicit.


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

Expand All @@ -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`
8 changes: 8 additions & 0 deletions examples/workspace-tags/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The 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 .

Copy link
Member Author

Choose a reason for hiding this comment

The 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:
Expand Down
4 changes: 2 additions & 2 deletions examples/workspace-tags/main.tf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ data "coder_parameter" "project_name" {
name = "project_name"
display_name = "Project name"
description = "Specify the project name."

mutable = false
default = "SUPERSECRET"
mutable = false
}

data "coder_parameter" "feature_cache_enabled" {
Expand Down
Loading