From 3bdd395faafcbe95caaa10d8e94c38b121c68f97 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 24 Aug 2026 07:55:23 -0500 Subject: [PATCH] docs(docs/admin/templates/extending-templates): clarify coder_env merge_strategy does not include host environment (#28466) `merge_strategy` on `coder_env` only combines values across `coder_env` resources targeting the same name. It does not know about the value already set by the workspace's image or host, such as the base `PATH`. A user hit this in #27501: appending to `PATH` with three `coder_env` resources replaced the host's `PATH` entirely, since none of them referenced the existing value. Clarify this in the docs, and update the `PATH` example to show referencing `$PATH` in one of the resources so the host's original value is kept. Refs #27501
Investigation notes - `coderd/provisionerdserver/provisionerdserver.go` builds the merged env starting from an empty map (`MergeExtraEnvs`), only combining `coder_env` resources with each other. - `agent/agent.go`'s `updateCommandEnv` applies the result with `os.ExpandEnv(v)`, which expands `$VARNAME` against the agent's real process environment. - Confirmed with a standalone repro that `value = "$PATH:/usr/local/cuda/bin"` preserves the host's real `PATH` and appends the extra directory, and that this composes correctly across multiple `coder_env` resources with `merge_strategy = "append"` as long as one of them references `$PATH`. - A companion PR updates the `terraform-provider-coder` schema description and example that feed the registry docs: https://github.com/coder/terraform-provider-coder (branch `bpmct/docs-env-merge-host`).
--- *Opened by Coder Agents on behalf of @bpmct.* --------- Co-authored-by: Nick Vigilante --- .../environment-variables.md | 39 ++++++++++++++----- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/admin/templates/extending-templates/environment-variables.md b/docs/admin/templates/extending-templates/environment-variables.md index 27082154f13..cbd2e2764d5 100644 --- a/docs/admin/templates/extending-templates/environment-variables.md +++ b/docs/admin/templates/extending-templates/environment-variables.md @@ -39,28 +39,50 @@ When multiple `coder_env` resources define the same variable name, use the The `append` and `prepend` strategies use `:` as a separator, which matches the convention for `PATH`-style variables on Unix systems. +### Merges and the host environment + +`merge_strategy` only combines values across `coder_env` resources in the same template. +It does not know about the value already set by the workspace's image or host, such as the base `PATH`. +An `append` or `prepend` builds its value from `coder_env` resources alone, and that value replaces whatever the host had set for that variable. + +To extend a variable that the host already sets, reference it directly in one of the values (for example, `$PATH`), so the agent expands it against the real environment at startup. +Only one resource in the chain needs the reference; the rest can use plain values. +The next example covers this. + ### Example: Appending to PATH -Multiple `coder_env` resources can each add directories to `PATH`: +Multiple `coder_env` resources can each add directories to `PATH`. +Reference `$PATH` in one of them to keep the host's original directories: ```tf -resource "coder_env" "path_tools" { +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" +} + +resource "coder_env" "path_cuda" { agent_id = coder_agent.dev.id name = "PATH" - value = "/home/coder/tools/bin" + value = "$PATH:/usr/local/cuda/bin" merge_strategy = "append" } resource "coder_env" "path_go" { agent_id = coder_agent.dev.id name = "PATH" - value = "/home/coder/go/bin" + value = "/usr/local/go/bin" + merge_strategy = "append" +} + +resource "coder_env" "path_rust_cargo" { + agent_id = coder_agent.dev.id + name = "PATH" + value = "/usr/local/cargo/bin" merge_strategy = "append" } ``` -This produces `PATH` with the value -`/home/coder/tools/bin:/home/coder/go/bin`. +This produces `PATH` with the host's original value, followed by `/usr/local/cuda/bin:/usr/local/go/bin:/usr/local/cargo/bin`. ### Example: Preventing duplicates @@ -83,9 +105,8 @@ a clear error message. When multiple `coder_env` resources append or prepend to the same variable, they are processed in alphabetical order by their [Terraform resource address](https://developer.hashicorp.com/terraform/cli/state/resource-addressing). -In the PATH example above, `coder_env.path_go` is processed before -`coder_env.path_tools` because `path_go` sorts before `path_tools` -alphabetically. +In the previous `PATH` example, `coder_env.path_cuda` is processed first, then `coder_env.path_go`, then `coder_env.path_rust_cargo`, because that is their alphabetical order. +This is why only one resource in the chain needs the `$PATH` reference: the merged value is built as one string before it's expanded, so the reference works no matter where in the chain it appears. ## Agent env override