[michvllni]

Problem

versions[*].directory is the only way to give a coderd_template version its contents, so the contents must exist as a directory on the filesystem of the machine running Terraform, at plan time. That rules out the cases described in #439:

• templates rendered per-deployment with templatefile() (the local_file + depends_on workaround relies on plan-time/apply-time ordering that isn't guaranteed),
• templates fetched from another repo, an artifact store, or http/vault, which arrive as strings or base64,
• remote runs on HCP Terraform / Terraform Enterprise, which only receive the uploaded configuration,
• contents that are already packaged as an archive, whether checked in, downloaded, or built by data "archive_file".

Fix

A version now takes its contents from exactly one of four attributes, enforced at validate time with stringvalidator.ExactlyOneOf:

• directory (unchanged) — a path to a directory on disk.

• files — map(string) of relative path to file content:

  files = {
    "main.tf"          = templatefile("${path.module}/tpl/main.tf.tftpl", { image = "ubuntu:24.04" })
    "build/Dockerfile" = file("${path.module}/tpl/build/Dockerfile")
  }

  The files are written out and then archived through provisionersdk.Tar like any other directory, so a version built from files behaves identically to the same contents on disk: hidden files are excluded, terraform.tfvars/*.auto.tfvars entries are read as variable values rather than uploaded, and the archive size limit applies. Paths must be relative and must not escape the root.

• archive_base64 — a base64-encoded archive, uploaded as-is, covering binary contents and prebuilt tarballs.

• archive_file — a path to an archive file, uploaded as-is, for an archive that already exists on disk and would otherwise have to be slurped into the configuration with filebase64():

  archive_file = data.archive_file.template.output_path

Both archive attributes accept an uncompressed tar, a gzipped tar, or a zip archive, detected from the contents rather than from a file extension. Tar and zip are uploaded as-is, since the Coder API accepts both and expands a zip server-side; a gzipped tar is decompressed first, buffering at most provisionersdk.TemplateArchiveLimit so a compression bomb can't be expanded into an unbounded amount of memory. Accepting more than uncompressed tar matters for archive_file in particular: data "archive_file" only produces zip and tar.gz, so tar-only support would have left the most common producer unusable.

Variable values can't be discovered from an archive without extracting it, so tf_vars is the only way to set them for the two archive sources.

directory_hash — the value that decides whether a new template version is created — is now computed from whichever source is set (files hashes sorted path + content, so a rename is a change; the archive sources hash the normalized archive bytes, so re-gzipping identical contents is not a change). When the configured source isn't known yet, the hash plans as unknown instead of erroring, so contents produced by another resource plan as a new version and are resolved during apply.

Following "fail at plan time, not apply time": invalid base64, a missing or unreadable archive_file, an archive that is none of the three formats, an oversized archive, more than one source set (which ExactlyOneOf defers on when one of the four is unknown), and a files map with no root .tf/.tf.json file all fail the plan.

Notes

• directory becomes Optional instead of Required; existing configurations are unaffected.
• directory_hash keeps its name (it's in state for every existing template) but now documents itself as the hash of the version contents.
• Switching an existing version from directory to the equivalent files or archive creates one new template version, since the hashes are computed differently per source.
• archive_file is read while planning, like directory is, so the archive has to exist at plan time — a data source fits it, a resource that writes the file during apply does not.
• No new module dependencies: go.mod/go.sum are unchanged, and archive/zip/compress/gzip are standard library packages already linked into the binary transitively.

Closes #439