From 27cf00cb83115261182f744572114491bce3a556 Mon Sep 17 00:00:00 2001 From: michaelvillani Date: Thu, 17 Sep 2026 06:09:01 +0000 Subject: [PATCH 1/5] feat(coderd_template): accept version contents as files or an archive `versions[*].directory` was the only way to give a template version its contents, which meant the contents had to exist on the filesystem of the machine running Terraform. Templates rendered with `templatefile()`, fetched from another repo or an artifact store, or applied from HCP Terraform can't be expressed that way, and the `local_file` workaround depends on plan-time/apply-time ordering that isn't guaranteed. A version can now take its contents from one of three mutually exclusive attributes, enforced with `stringvalidator.ExactlyOneOf`: - `directory`, unchanged. - `files`, a map of relative path to file content. The files are written out and archived exactly like a directory, so hidden files are excluded and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values. - `archive_base64`, a base64-encoded tar archive, uploaded as-is. Variable values aren't discovered from it, so `tf_vars` is the only way to set them. `directory_hash` is now computed from whichever source is set, and is unknown (rather than an error) while the source is unknown, so contents produced by another resource plan as a new version. Bad base64, a non-tar archive, an oversized archive, and a `files` map without a root `.tf` file all fail during the plan instead of the apply. Closes #439 --- docs/resources/template.md | 40 +- .../resources/coderd_template/resource.tf | 29 + internal/provider/template_resource.go | 344 ++++++++++- internal/provider/template_resource_test.go | 575 +++++++++++++++++- internal/provider/util.go | 29 + 5 files changed, 980 insertions(+), 37 deletions(-) diff --git a/docs/resources/template.md b/docs/resources/template.md index f34c6fa9..9c2198aa 100644 --- a/docs/resources/template.md +++ b/docs/resources/template.md @@ -53,6 +53,35 @@ resource "coderd_template" "ubuntu-main" { groups = [] } } + +// Template contents don't have to live in a directory on disk: a version can be +// built from rendered file contents, or from a prebuilt archive. Exactly one of +// `directory`, `files`, and `archive_base64` may be set on a version. +resource "coderd_template" "ubuntu-rendered" { + name = "ubuntu-rendered" + description = "The main template, rendered for this deployment." + versions = [ + { + name = "rendered-${var.COMMIT_SHA}" + active = true + files = { + "main.tf" = templatefile("${path.module}/tpl/main.tf.tftpl", { image = "ubuntu:24.04" }) + "build/Dockerfile" = file("${path.module}/tpl/build/Dockerfile") + } + }, + { + name = "prebuilt-${var.COMMIT_SHA}" + // A base64-encoded, uncompressed tar archive, such as one fetched from an + // artifact store. Variable values aren't discovered from an archive, so + // they're set with `tf_vars`. + archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") + tf_vars = [{ + name = "image" + value = "ubuntu:24.04" + }] + } + ] +} ``` @@ -130,21 +159,20 @@ Optional: ### Nested Schema for `versions` -Required: - -- `directory` (String) A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. - Optional: - `active` (Boolean) Whether this version is the active version of the template. Only one version can be active at a time. +- `archive_base64` (String) A base64-encoded, uncompressed tar archive of the template version contents, uploaded as-is. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, or `archive_base64` must be set. +- `directory` (String) A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, or `archive_base64` must be set. +- `files` (Map of String) The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, or `archive_base64` must be set. - `message` (String) A message describing the changes in this version of the template. Messages longer than 72 characters will be truncated. -- `name` (String) The name of the template version. Automatically generated if not provided. If provided, the name *must* change each time the directory contents, or the `tf_vars` attribute are updated. +- `name` (String) The name of the template version. Automatically generated if not provided. If provided, the name *must* change each time the version contents, or the `tf_vars` attribute are updated. - `provisioner_tags` (Attributes Set) Provisioner tags for the template version. (see [below for nested schema](#nestedatt--versions--provisioner_tags)) - `tf_vars` (Attributes Set) Terraform variables for the template version. (see [below for nested schema](#nestedatt--versions--tf_vars)) Read-Only: -- `directory_hash` (String) +- `directory_hash` (String) A hash of the template version contents, used to detect when a new version needs to be created. - `id` (String) diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf index e644d6e7..345c92a6 100644 --- a/examples/resources/coderd_template/resource.tf +++ b/examples/resources/coderd_template/resource.tf @@ -35,3 +35,32 @@ resource "coderd_template" "ubuntu-main" { groups = [] } } + +// Template contents don't have to live in a directory on disk: a version can be +// built from rendered file contents, or from a prebuilt archive. Exactly one of +// `directory`, `files`, and `archive_base64` may be set on a version. +resource "coderd_template" "ubuntu-rendered" { + name = "ubuntu-rendered" + description = "The main template, rendered for this deployment." + versions = [ + { + name = "rendered-${var.COMMIT_SHA}" + active = true + files = { + "main.tf" = templatefile("${path.module}/tpl/main.tf.tftpl", { image = "ubuntu:24.04" }) + "build/Dockerfile" = file("${path.module}/tpl/build/Dockerfile") + } + }, + { + name = "prebuilt-${var.COMMIT_SHA}" + // A base64-encoded, uncompressed tar archive, such as one fetched from an + // artifact store. Variable values aren't discovered from an archive, so + // they're set with `tf_vars`. + archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") + tf_vars = [{ + name = "image" + value = "ubuntu:24.04" + }] + } + ] +} diff --git a/internal/provider/template_resource.go b/internal/provider/template_resource.go index 2b6bb405..01724956 100644 --- a/internal/provider/template_resource.go +++ b/internal/provider/template_resource.go @@ -1,11 +1,17 @@ package provider import ( + "archive/tar" "bufio" + "bytes" "context" + "encoding/base64" "encoding/json" + "errors" "fmt" "io" + "os" + "path/filepath" "slices" "strings" "time" @@ -166,6 +172,8 @@ type TemplateVersion struct { Name types.String `tfsdk:"name"` Message types.String `tfsdk:"message"` Directory types.String `tfsdk:"directory"` + Files types.Map `tfsdk:"files"` + ArchiveBase64 types.String `tfsdk:"archive_base64"` DirectoryHash types.String `tfsdk:"directory_hash"` Active types.Bool `tfsdk:"active"` TerraformVariables types.Set `tfsdk:"tf_vars"` @@ -500,7 +508,7 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques Computed: true, }, "name": schema.StringAttribute{ - MarkdownDescription: "The name of the template version. Automatically generated if not provided. If provided, the name *must* change each time the directory contents, or the `tf_vars` attribute are updated.", + MarkdownDescription: "The name of the template version. Automatically generated if not provided. If provided, the name *must* change each time the version contents, or the `tf_vars` attribute are updated.", Optional: true, Computed: true, Validators: []validator.String{ @@ -514,11 +522,28 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques Default: stringdefault.StaticString(""), }, "directory": schema.StringAttribute{ - MarkdownDescription: "A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version.", - Required: true, + MarkdownDescription: "A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + Optional: true, + Validators: []validator.String{ + stringvalidator.ExactlyOneOf( + path.MatchRelative().AtParent().AtName("directory"), + path.MatchRelative().AtParent().AtName("files"), + path.MatchRelative().AtParent().AtName("archive_base64"), + ), + }, + }, + "files": schema.MapAttribute{ + MarkdownDescription: "The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + Optional: true, + ElementType: types.StringType, + }, + "archive_base64": schema.StringAttribute{ + MarkdownDescription: "A base64-encoded, uncompressed tar archive of the template version contents, uploaded as-is. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + Optional: true, }, "directory_hash": schema.StringAttribute{ - Computed: true, + MarkdownDescription: "A hash of the template version contents, used to detect when a new version needs to be created.", + Computed: true, }, "active": schema.BoolAttribute{ MarkdownDescription: "Whether this version is the active version of the template. Only one version can be active at a time.", @@ -679,6 +704,13 @@ func (r *TemplateResource) Create(ctx context.Context, req resource.CreateReques data.UseClassicParameterFlow = types.BoolValue(ucpfResp.UseClassicParameterFlow) } + // Any hash left unknown at plan time (because its contents weren't known + // yet) has to be resolved before it's written to state. + resp.Diagnostics.Append(data.Versions.resolveContentHashes(ctx)...) + if resp.Diagnostics.HasError() { + return + } + resp.Diagnostics.Append(data.Versions.setPrivateState(ctx, resp.Private)...) if resp.Diagnostics.HasError() { return @@ -885,6 +917,11 @@ func (r *TemplateResource) Update(ctx context.Context, req resource.UpdateReques } } } + resp.Diagnostics.Append(newState.Versions.resolveContentHashes(ctx)...) + if resp.Diagnostics.HasError() { + return + } + resp.Diagnostics.Append(newState.Versions.setPrivateState(ctx, resp.Private)...) if resp.Diagnostics.HasError() { return @@ -1016,7 +1053,7 @@ func (d *versionsPlanModifier) Description(ctx context.Context) string { // MarkdownDescription implements planmodifier.Object. func (d *versionsPlanModifier) MarkdownDescription(context.Context) string { - return "Compute the hash of a directory." + return "Compute the hash of a template version's contents." } // PlanModifyObject implements planmodifier.List. @@ -1064,12 +1101,12 @@ func (d *versionsPlanModifier) PlanModifyList(ctx context.Context, req planmodif } for i := range planVersions { - hash, err := computeDirectoryHash(planVersions[i].Directory.ValueString()) - if err != nil { - resp.Diagnostics.AddError("Client Error", fmt.Sprintf("Failed to compute directory hash: %s", err)) + hash, hashDiags := versionContentHash(ctx, &planVersions[i]) + resp.Diagnostics.Append(hashDiags...) + if resp.Diagnostics.HasError() { return } - planVersions[i].DirectoryHash = types.StringValue(hash) + planVersions[i].DirectoryHash = hash } var lv LastVersionsByHash @@ -1170,6 +1207,192 @@ var templateACLRoleValidator = stringvalidator.OneOf( string(codersdk.TemplateRoleUse), ) +// versionSourceKind identifies which of the mutually exclusive attributes a +// template version takes its contents from. +type versionSourceKind int + +const ( + versionSourceNone versionSourceKind = iota + versionSourceDirectory + versionSourceFiles + versionSourceArchive +) + +// versionSource reports which content attribute is set on a version. +// `stringvalidator.ExactlyOneOf` enforces the same rule at validate time, but +// it defers whenever one of the three is unknown, so the invariant is checked +// here too rather than silently picking one of the configured sources. +func versionSource(version *TemplateVersion) (versionSourceKind, diag.Diagnostics) { + var diags diag.Diagnostics + kind := versionSourceNone + count := 0 + if !version.Directory.IsNull() { + kind, count = versionSourceDirectory, count+1 + } + if !version.Files.IsNull() { + kind, count = versionSourceFiles, count+1 + } + if !version.ArchiveBase64.IsNull() { + kind, count = versionSourceArchive, count+1 + } + switch { + case count == 0: + diags.AddError("Client Error", "A template version must set exactly one of `directory`, `files`, or `archive_base64`.") + case count > 1: + diags.AddError("Client Error", "A template version can only set one of `directory`, `files`, or `archive_base64`.") + } + return kind, diags +} + +// filesFromMap converts a version's `files` attribute into a map of relative +// path to content. It returns a nil map, without diagnostics, when the map or +// any of its elements is still unknown: the contents can neither be hashed nor +// uploaded yet, and callers treat that as "not known". +func filesFromMap(ctx context.Context, files types.Map) (map[string]string, diag.Diagnostics) { + var diags diag.Diagnostics + if files.IsNull() || files.IsUnknown() { + return nil, diags + } + elements := files.Elements() + for name, content := range elements { + if content.IsUnknown() { + return nil, diags + } + if content.IsNull() { + diags.AddError("Client Error", fmt.Sprintf("The contents of file %q are null. Every entry in `files` must be a string.", name)) + return nil, diags + } + } + out := make(map[string]string, len(elements)) + diags.Append(files.ElementsAs(ctx, &out, false)...) + if diags.HasError() { + return nil, diags + } + return out, diags +} + +// filesHaveTerraform reports whether a `files` map contains a Terraform file at +// the root of the template. The files are archived through +// `provisionersdk.Tar`, which rejects a directory without one, but its error +// refers to the temporary directory they're written to, so this is checked up +// front instead. +func filesHaveTerraform(files map[string]string) bool { + for name := range files { + rel := filepath.Clean(filepath.FromSlash(name)) + if filepath.Dir(rel) != "." { + continue + } + if strings.HasSuffix(rel, ".tf") || strings.HasSuffix(rel, ".tf.json") { + return true + } + } + return false +} + +// writeFiles materializes a `files` map into dir so that it can be archived and +// have its variable files discovered exactly like a configured `directory`. +func writeFiles(dir string, files map[string]string) error { + for name, content := range files { + rel := filepath.Clean(filepath.FromSlash(name)) + if filepath.IsAbs(rel) || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) { + return fmt.Errorf("invalid file path %q: paths must be relative to the root of the template, and must not escape it", name) + } + target := filepath.Join(dir, rel) + if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil { + return fmt.Errorf("failed to create directory for %q: %w", name, err) + } + if err := os.WriteFile(target, []byte(content), 0o644); err != nil { + return fmt.Errorf("failed to write %q: %w", name, err) + } + } + return nil +} + +// decodeArchive decodes and sanity-checks a version's `archive_base64` +// attribute. It's called from the plan modifier as well as at apply time, so a +// malformed archive fails the plan instead of a partially applied change. +func decodeArchive(archiveBase64 string) ([]byte, error) { + archive, err := base64.StdEncoding.DecodeString(archiveBase64) + if err != nil { + return nil, fmt.Errorf("`archive_base64` is not valid base64: %w", err) + } + if int64(len(archive)) >= provisionersdk.TemplateArchiveLimit { + return nil, fmt.Errorf("archive too big. Must be < %d bytes", provisionersdk.TemplateArchiveLimit) + } + if _, err := tar.NewReader(bytes.NewReader(archive)).Next(); err != nil { + return nil, fmt.Errorf("`archive_base64` must contain an uncompressed tar archive: %w", err) + } + return archive, nil +} + +// versionContentHash hashes a version's contents, from whichever of +// `directory`, `files`, or `archive_base64` is set. The hash is what decides +// whether a new template version needs to be created, so it returns an unknown +// string when the configured source isn't known yet, which plans the version as +// new. +func versionContentHash(ctx context.Context, version *TemplateVersion) (types.String, diag.Diagnostics) { + source, diags := versionSource(version) + if diags.HasError() { + return types.StringNull(), diags + } + switch source { + case versionSourceDirectory: + if version.Directory.IsUnknown() { + return types.StringUnknown(), diags + } + hash, err := computeDirectoryHash(version.Directory.ValueString()) + if err != nil { + diags.AddError("Client Error", fmt.Sprintf("Failed to compute directory hash: %s", err)) + return types.StringNull(), diags + } + return types.StringValue(hash), diags + case versionSourceFiles: + files, fileDiags := filesFromMap(ctx, version.Files) + diags.Append(fileDiags...) + if diags.HasError() { + return types.StringNull(), diags + } + if files == nil { + return types.StringUnknown(), diags + } + if !filesHaveTerraform(files) { + diags.AddError("Client Error", "`files` must contain at least one `.tf` or `.tf.json` file at the root of the template.") + return types.StringNull(), diags + } + return types.StringValue(computeFilesHash(files)), diags + case versionSourceArchive: + if version.ArchiveBase64.IsUnknown() { + return types.StringUnknown(), diags + } + archive, err := decodeArchive(version.ArchiveBase64.ValueString()) + if err != nil { + diags.AddError("Client Error", fmt.Sprintf("Failed to read template version archive: %s", err)) + return types.StringNull(), diags + } + return types.StringValue(computeBytesHash(archive)), diags + default: + return types.StringUnknown(), diags + } +} + +// resolveContentHashes fills in any version hash that was left unknown at plan +// time, so that the hashes written to state (and to the private state that +// matches versions across plans) are always known. +func (v Versions) resolveContentHashes(ctx context.Context) (diags diag.Diagnostics) { + for i := range v { + if !v[i].DirectoryHash.IsUnknown() { + continue + } + hash, hashDiags := versionContentHash(ctx, &v[i]) + diags.Append(hashDiags...) + if diags.HasError() { + return diags + } + v[i].DirectoryHash = hash + } + return diags +} + func uploadDirectory(ctx context.Context, client *codersdk.Client, logger slog.Logger, directory string) (*codersdk.UploadResponse, error) { pipeReader, pipeWriter := io.Pipe() go func() { @@ -1191,6 +1414,88 @@ func uploadDirectory(ctx context.Context, client *codersdk.Client, logger slog.L return &resp, nil } +// uploadVersionContents uploads the contents of a template version from +// whichever of `directory`, `files`, or `archive_base64` is set, and returns +// the ID of the uploaded file along with any variable values discovered +// alongside the contents. +func uploadVersionContents(ctx context.Context, client *codersdk.Client, version *TemplateVersion) (uuid.UUID, []codersdk.VariableValue, error) { + source, diags := versionSource(version) + if diags.HasError() { + return uuid.Nil, nil, errors.New(diags.Errors()[0].Detail()) + } + switch source { + case versionSourceDirectory: + return uploadTemplateDirectory(ctx, client, version.Directory.ValueString()) + case versionSourceFiles: + files, fileDiags := filesFromMap(ctx, version.Files) + if fileDiags.HasError() { + return uuid.Nil, nil, errors.New(fileDiags.Errors()[0].Detail()) + } + if files == nil { + return uuid.Nil, nil, errors.New("the contents of `files` are not known") + } + // The files are written out and then archived like any other directory, + // so that a version built from `files` behaves identically to the same + // contents on disk (hidden file handling, variable file discovery, and + // the archive size limit all included). + dir, err := os.MkdirTemp("", "coderd-template-version-") + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to create temporary directory for `files`: %s", err) + } + defer func() { + if err := os.RemoveAll(dir); err != nil { + tflog.Warn(ctx, "error removing temporary template directory", map[string]any{ + "error": err, + }) + } + }() + if err := writeFiles(dir, files); err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to write `files`: %s", err) + } + return uploadTemplateDirectory(ctx, client, dir) + case versionSourceArchive: + archive, err := decodeArchive(version.ArchiveBase64.ValueString()) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to read template version archive: %s", err) + } + tflog.Info(ctx, "uploading archive") + uploadResp, err := client.Upload(ctx, codersdk.ContentTypeTar, bytes.NewReader(archive)) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to upload archive: %s", err) + } + tflog.Info(ctx, "successfully uploaded archive") + // Variable values can't be discovered without extracting the archive, + // so `tf_vars` is the only way to set them for this source. + return uploadResp.ID, nil, nil + default: + return uuid.Nil, nil, errors.New("a template version must set exactly one of `directory`, `files`, or `archive_base64`") + } +} + +// uploadTemplateDirectory archives and uploads a directory, and parses the +// variable values from any vars files it contains. +func uploadTemplateDirectory(ctx context.Context, client *codersdk.Client, directory string) (uuid.UUID, []codersdk.VariableValue, error) { + tflog.Info(ctx, "uploading directory") + uploadResp, err := uploadDirectory(ctx, client, slog.Make(newTFLogSink(ctx)), directory) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to upload directory: %s", err) + } + tflog.Info(ctx, "successfully uploaded directory") + tflog.Info(ctx, "discovering and parsing vars files") + varFiles, err := codersdk.DiscoverVarsFiles(directory) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to discover vars files: %s", err) + } + vars, err := codersdk.ParseUserVariableValues(varFiles, "", []string{}) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to parse user variable values: %s", err) + } + tflog.Info(ctx, "discovered and parsed vars files", map[string]any{ + "vars": vars, + }) + return uploadResp.ID, vars, nil +} + func waitForJob(ctx context.Context, client *codersdk.Client, version *codersdk.TemplateVersion) ([]codersdk.ProvisionerJobLog, error) { const maxRetries = 3 var allLogs []codersdk.ProvisionerJobLog @@ -1267,25 +1572,10 @@ type newVersionRequest struct { func newVersion(ctx context.Context, client *codersdk.Client, req newVersionRequest) (*codersdk.TemplateVersion, []codersdk.ProvisionerJobLog, error) { var logs []codersdk.ProvisionerJobLog - directory := req.Version.Directory.ValueString() - tflog.Info(ctx, "uploading directory") - uploadResp, err := uploadDirectory(ctx, client, slog.Make(newTFLogSink(ctx)), directory) - if err != nil { - return nil, logs, fmt.Errorf("failed to upload directory: %s", err) - } - tflog.Info(ctx, "successfully uploaded directory") - tflog.Info(ctx, "discovering and parsing vars files") - varFiles, err := codersdk.DiscoverVarsFiles(directory) - if err != nil { - return nil, logs, fmt.Errorf("failed to discover vars files: %s", err) - } - vars, err := codersdk.ParseUserVariableValues(varFiles, "", []string{}) + fileID, vars, err := uploadVersionContents(ctx, client, req.Version) if err != nil { - return nil, logs, fmt.Errorf("failed to parse user variable values: %s", err) + return nil, logs, err } - tflog.Info(ctx, "discovered and parsed vars files", map[string]any{ - "vars": vars, - }) tfVars, diags := variablesFromSet(ctx, req.Version.TerraformVariables) if diags.HasError() { return nil, logs, fmt.Errorf("failed to extract terraform variables: %s", diags.Errors()[0].Detail()) @@ -1309,7 +1599,7 @@ func newVersion(ctx context.Context, client *codersdk.Client, req newVersionRequ Message: req.Version.Message.ValueString(), StorageMethod: codersdk.ProvisionerStorageMethodFile, Provisioner: codersdk.ProvisionerTypeTerraform, - FileID: uploadResp.ID, + FileID: fileID, UserVariableValues: vars, ProvisionerTags: provTags, } diff --git a/internal/provider/template_resource_test.go b/internal/provider/template_resource_test.go index d5b08f9d..8c6f3d9e 100644 --- a/internal/provider/template_resource_test.go +++ b/internal/provider/template_resource_test.go @@ -1,21 +1,28 @@ package provider import ( + "archive/tar" + "bytes" "context" + "encoding/base64" "fmt" "os" + "path/filepath" "regexp" "slices" + "sort" "strings" "testing" "text/template" "github.com/coder/coder/v2/codersdk" + "github.com/coder/coder/v2/provisionersdk" "github.com/coder/terraform-provider-coderd/integration" "github.com/google/uuid" "github.com/hashicorp/terraform-plugin-framework/attr" "github.com/hashicorp/terraform-plugin-framework/diag" frameworkresource "github.com/hashicorp/terraform-plugin-framework/resource" + "github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier" "github.com/hashicorp/terraform-plugin-framework/schema/validator" "github.com/hashicorp/terraform-plugin-framework/types" "github.com/hashicorp/terraform-plugin-testing/config" @@ -2503,10 +2510,14 @@ func TestReconcileVersionIDs(t *testing.T) { func versionObjectType() types.ObjectType { return types.ObjectType{ AttrTypes: map[string]attr.Type{ - "id": UUIDType, - "name": types.StringType, - "message": types.StringType, - "directory": types.StringType, + "id": UUIDType, + "name": types.StringType, + "message": types.StringType, + "directory": types.StringType, + "files": types.MapType{ + ElemType: types.StringType, + }, + "archive_base64": types.StringType, "directory_hash": types.StringType, "active": types.BoolType, "tf_vars": types.SetType{ @@ -2535,6 +2546,8 @@ func TestValidateListUnknownTFVars(t *testing.T) { "name": types.StringValue("main"), "message": types.StringValue(""), "directory": types.StringValue("./template"), + "files": types.MapNull(types.StringType), + "archive_base64": types.StringNull(), "directory_hash": types.StringUnknown(), "active": types.BoolValue(true), "tf_vars": types.SetUnknown(variableSetElemType), @@ -2573,6 +2586,8 @@ func TestUnknownTFVarsDeserialization(t *testing.T) { "name": types.StringValue("stable-1"), "message": types.StringValue(""), "directory": types.StringValue("/tmp/test"), + "files": types.MapNull(types.StringType), + "archive_base64": types.StringNull(), "directory_hash": types.StringUnknown(), "active": types.BoolValue(true), "tf_vars": tfVars, @@ -2650,3 +2665,555 @@ func TestUnknownTFVarsDeserialization(t *testing.T) { require.Empty(t, vars) }) } + +// mustTarBase64 builds a base64-encoded tar archive from a map of file path to +// content, for use as a version's `archive_base64`. +func mustTarBase64(t *testing.T, files map[string]string) string { + t.Helper() + var buf bytes.Buffer + tw := tar.NewWriter(&buf) + paths := make([]string, 0, len(files)) + for path := range files { + paths = append(paths, path) + } + sort.Strings(paths) + for _, path := range paths { + require.NoError(t, tw.WriteHeader(&tar.Header{ + Name: path, + Typeflag: tar.TypeReg, + Mode: 0o644, + Size: int64(len(files[path])), + })) + _, err := tw.Write([]byte(files[path])) + require.NoError(t, err) + } + require.NoError(t, tw.Close()) + return base64.StdEncoding.EncodeToString(buf.Bytes()) +} + +// mustFilesMap converts a map of file path to content into the types.Map used +// by a version's `files` attribute. +func mustFilesMap(t *testing.T, files map[string]string) types.Map { + t.Helper() + m, diags := types.MapValueFrom(context.Background(), types.StringType, files) + require.False(t, diags.HasError(), "building files map: %v", diags.Errors()) + return m +} + +func TestComputeFilesHash(t *testing.T) { + t.Parallel() + + base := computeFilesHash(map[string]string{ + "main.tf": "resource \"null_resource\" \"a\" {}", + "build/Dockerfile": "FROM ubuntu", + }) + + t.Run("StableAcrossMaps", func(t *testing.T) { + t.Parallel() + // A different map with the same entries must hash identically, + // otherwise map iteration order would create a new version on + // every plan. + other := computeFilesHash(map[string]string{ + "build/Dockerfile": "FROM ubuntu", + "main.tf": "resource \"null_resource\" \"a\" {}", + }) + require.Equal(t, base, other) + }) + + t.Run("ContentChanges", func(t *testing.T) { + t.Parallel() + require.NotEqual(t, base, computeFilesHash(map[string]string{ + "main.tf": "resource \"null_resource\" \"a\" {}", + "build/Dockerfile": "FROM debian", + })) + }) + + t.Run("RenameChanges", func(t *testing.T) { + t.Parallel() + // Paths are hashed alongside contents, so moving a file is a change + // even though the bytes are identical. + require.NotEqual(t, base, computeFilesHash(map[string]string{ + "main.tf": "resource \"null_resource\" \"a\" {}", + "build/Containerfile": "FROM ubuntu", + })) + }) + + t.Run("ConcatenationIsUnambiguous", func(t *testing.T) { + t.Parallel() + require.NotEqual(t, + computeFilesHash(map[string]string{"a": "bc"}), + computeFilesHash(map[string]string{"ab": "c"}), + ) + }) +} + +func TestVersionContentHash(t *testing.T) { + t.Parallel() + ctx := t.Context() + + dir := t.TempDir() + require.NoError(t, os.WriteFile(filepath.Join(dir, "main.tf"), []byte("resource \"null_resource\" \"a\" {}"), 0o644)) + + t.Run("Directory", func(t *testing.T) { + t.Parallel() + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringValue(dir), + Files: types.MapNull(types.StringType), + ArchiveBase64: types.StringNull(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + expected, err := computeDirectoryHash(dir) + require.NoError(t, err) + require.Equal(t, expected, hash.ValueString()) + }) + + t.Run("Files", func(t *testing.T) { + t.Parallel() + files := map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"} + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: mustFilesMap(t, files), + ArchiveBase64: types.StringNull(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.Equal(t, computeFilesHash(files), hash.ValueString()) + }) + + t.Run("Archive", func(t *testing.T) { + t.Parallel() + archive := mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"}) + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: types.MapNull(types.StringType), + ArchiveBase64: types.StringValue(archive), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + decoded, err := base64.StdEncoding.DecodeString(archive) + require.NoError(t, err) + require.Equal(t, computeBytesHash(decoded), hash.ValueString()) + }) + + // A source that isn't known yet must plan as a new version rather than + // failing, since the contents can come from another resource. + t.Run("UnknownFiles", func(t *testing.T) { + t.Parallel() + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: types.MapUnknown(types.StringType), + ArchiveBase64: types.StringNull(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.True(t, hash.IsUnknown()) + }) + + t.Run("UnknownFileContent", func(t *testing.T) { + t.Parallel() + files, diags := types.MapValue(types.StringType, map[string]attr.Value{ + "main.tf": types.StringUnknown(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: files, + ArchiveBase64: types.StringNull(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.True(t, hash.IsUnknown()) + }) + + t.Run("UnknownDirectory", func(t *testing.T) { + t.Parallel() + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringUnknown(), + Files: types.MapNull(types.StringType), + ArchiveBase64: types.StringNull(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.True(t, hash.IsUnknown()) + }) + + t.Run("NoSource", func(t *testing.T) { + t.Parallel() + _, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: types.MapNull(types.StringType), + ArchiveBase64: types.StringNull(), + }) + require.True(t, diags.HasError()) + }) + + // `stringvalidator.ExactlyOneOf` defers whenever one of the three is + // unknown, so this has to be caught here as well. + t.Run("MultipleSources", func(t *testing.T) { + t.Parallel() + _, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringValue(dir), + Files: mustFilesMap(t, map[string]string{"main.tf": ""}), + ArchiveBase64: types.StringNull(), + }) + require.True(t, diags.HasError()) + }) + + t.Run("NoTerraformFiles", func(t *testing.T) { + t.Parallel() + _, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: mustFilesMap(t, map[string]string{"nested/main.tf": ""}), + ArchiveBase64: types.StringNull(), + }) + require.True(t, diags.HasError()) + }) + + t.Run("InvalidArchive", func(t *testing.T) { + t.Parallel() + _, diags := versionContentHash(ctx, &TemplateVersion{ + Directory: types.StringNull(), + Files: types.MapNull(types.StringType), + ArchiveBase64: types.StringValue("not base64!"), + }) + require.True(t, diags.HasError()) + }) +} + +func TestDecodeArchive(t *testing.T) { + t.Parallel() + + t.Run("Tar", func(t *testing.T) { + t.Parallel() + archive, err := decodeArchive(mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"})) + require.NoError(t, err) + require.NotEmpty(t, archive) + }) + + t.Run("NotBase64", func(t *testing.T) { + t.Parallel() + _, err := decodeArchive("not base64!") + require.ErrorContains(t, err, "not valid base64") + }) + + t.Run("NotATar", func(t *testing.T) { + t.Parallel() + _, err := decodeArchive(base64.StdEncoding.EncodeToString([]byte("resource \"null_resource\" \"a\" {}"))) + require.ErrorContains(t, err, "uncompressed tar archive") + }) + + t.Run("TooBig", func(t *testing.T) { + t.Parallel() + _, err := decodeArchive(mustTarBase64(t, map[string]string{ + "main.tf": strings.Repeat("a", provisionersdk.TemplateArchiveLimit), + })) + require.ErrorContains(t, err, "too big") + }) +} + +func TestWriteFiles(t *testing.T) { + t.Parallel() + + t.Run("NestedPaths", func(t *testing.T) { + t.Parallel() + dir := t.TempDir() + require.NoError(t, writeFiles(dir, map[string]string{ + "main.tf": "resource \"null_resource\" \"a\" {}", + "build/Dockerfile": "FROM ubuntu", + })) + content, err := os.ReadFile(filepath.Join(dir, "build", "Dockerfile")) + require.NoError(t, err) + require.Equal(t, "FROM ubuntu", string(content)) + }) + + t.Run("RejectsEscapingPaths", func(t *testing.T) { + t.Parallel() + for _, path := range []string{"../escape.tf", "/etc/passwd", "nested/../../escape.tf", ".."} { + require.ErrorContains(t, writeFiles(t.TempDir(), map[string]string{path: ""}), "must not escape") + } + }) +} + +func TestAccTemplateResourceVersionSourceValidation(t *testing.T) { + t.Parallel() + if os.Getenv("TF_ACC") == "" { + t.Skip("Acceptance tests are disabled.") + } + + cfg := ` +provider coderd { + url = "https://example.com" + token = "abcd" +} + +resource "coderd_template" "test" { + name = "example-template" + versions = [ + { + active = true + %s + } + ] +}` + + // These all fail during validation, before the provider is configured, so + // no Coder deployment is needed. + for name, source := range map[string]string{ + "NoSource": ``, + "DirectoryAndFiles": "directory = \"./example-template\"\n\t\t\tfiles = { \"main.tf\" = \"\" }", + "DirectoryAndArchive": "directory = \"./example-template\"\n\t\t\tarchive_base64 = \"\"", + "FilesAndArchive": "files = { \"main.tf\" = \"\" }\n\t\t\tarchive_base64 = \"\"", + "AllThree": "directory = \"./example-template\"\n\t\t\tfiles = { \"main.tf\" = \"\" }\n\t\t\tarchive_base64 = \"\"", + } { + t.Run(name, func(t *testing.T) { + resource.Test(t, resource.TestCase{ + PreCheck: func() { testAccPreCheck(t) }, + IsUnitTest: true, + ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, + Steps: []resource.TestStep{ + { + Config: fmt.Sprintf(cfg, source), + ExpectError: regexp.MustCompile("Invalid Attribute Combination"), + }, + }, + }) + }) + } +} + +func TestAccTemplateResourceFiles(t *testing.T) { + t.Parallel() + if os.Getenv("TF_ACC") == "" { + t.Skip("Acceptance tests are disabled.") + } + + cfg := ` +provider coderd { + url = %q + token = %q +} + +resource "coderd_template" "test" { + name = "files-template" + versions = [ + { + name = %q + active = true + files = { + "main.tf" = %q + "terraform.tfvars" = "name = \"world\"" + } + } + ] +}` + + ctx := t.Context() + client := integration.StartCoder(ctx, t, "template_resource_files_acc") + + mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") + require.NoError(t, err) + + resource.Test(t, resource.TestCase{ + PreCheck: func() { testAccPreCheck(t) }, + IsUnitTest: true, + ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, + Steps: []resource.TestStep{ + // The contents are provided inline, and `terraform.tfvars` is read + // as a variable value just like it is for a `directory`. + { + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "one", string(mainTF)), + Check: resource.ComposeTestCheckFunc( + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.id"), + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.directory_hash"), + resource.TestCheckResourceAttr("coderd_template.test", "versions.0.name", "one"), + ), + }, + // Changing the contents creates a new version. + { + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "two", string(mainTF)+"\n# a change\n"), + Check: resource.ComposeTestCheckFunc( + resource.TestCheckResourceAttr("coderd_template.test", "versions.0.name", "two"), + ), + }, + }, + }) +} + +func TestAccTemplateResourceArchive(t *testing.T) { + t.Parallel() + if os.Getenv("TF_ACC") == "" { + t.Skip("Acceptance tests are disabled.") + } + + cfg := ` +provider coderd { + url = %q + token = %q +} + +resource "coderd_template" "test" { + name = "archive-template" + versions = [ + { + active = true + archive_base64 = %q + tf_vars = [ + { + name = "name" + value = "world" + } + ] + } + ] +}` + + ctx := t.Context() + client := integration.StartCoder(ctx, t, "template_resource_archive_acc") + + mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") + require.NoError(t, err) + archive := mustTarBase64(t, map[string]string{"main.tf": string(mainTF)}) + + resource.Test(t, resource.TestCase{ + PreCheck: func() { testAccPreCheck(t) }, + IsUnitTest: true, + ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, + Steps: []resource.TestStep{ + { + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), archive), + Check: resource.ComposeTestCheckFunc( + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.id"), + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.directory_hash"), + ), + }, + }, + }) +} + +// TestAccTemplateResourceVersionSourcePlan checks that a version whose contents +// come from `files` or `archive_base64` plans without error, end to end. It +// only plans, so a mock server is enough. The hash the plan modifier produces +// is asserted in TestVersionsPlanModifierContentHash. +func TestAccTemplateResourceVersionSourcePlan(t *testing.T) { + t.Parallel() + if os.Getenv("TF_ACC") == "" { + t.Skip("Acceptance tests are disabled.") + } + + srv := newMockServer(nil) + defer srv.Close() + + cfg := ` +provider coderd { + url = %q + token = "abcd" +} + +resource "coderd_template" "test" { + name = "example-template" + versions = [ + { + active = true + %s + } + ] +}` + + for name, source := range map[string]string{ + "Files": "files = { \"main.tf\" = \"resource \\\"null_resource\\\" \\\"a\\\" {}\" }", + "Archive": fmt.Sprintf("archive_base64 = %q", mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"})), + } { + t.Run(name, func(t *testing.T) { + resource.Test(t, resource.TestCase{ + PreCheck: func() { testAccPreCheck(t) }, + IsUnitTest: true, + ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, + Steps: []resource.TestStep{ + { + Config: fmt.Sprintf(cfg, srv.URL, source), + PlanOnly: true, + // The resource doesn't exist yet, so the plan to + // create it is non-empty by definition. + ExpectNonEmptyPlan: true, + }, + }, + }) + }) + } +} + +// TestVersionsPlanModifierContentHash checks that the plan modifier hashes a +// version's contents regardless of which source attribute they come from, +// since an unknown or incorrect hash would create a new template version on +// every plan. +func TestVersionsPlanModifierContentHash(t *testing.T) { + t.Parallel() + ctx := t.Context() + objType := versionObjectType() + + dir := t.TempDir() + require.NoError(t, os.WriteFile(filepath.Join(dir, "main.tf"), []byte("resource \"null_resource\" \"a\" {}"), 0o644)) + dirHash, err := computeDirectoryHash(dir) + require.NoError(t, err) + + files := map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"} + archive := mustTarBase64(t, files) + decodedArchive, err := base64.StdEncoding.DecodeString(archive) + require.NoError(t, err) + + for name, tc := range map[string]struct { + directory attr.Value + files attr.Value + archiveBase64 attr.Value + expected string + }{ + "Directory": { + directory: types.StringValue(dir), + files: types.MapNull(types.StringType), + archiveBase64: types.StringNull(), + expected: dirHash, + }, + "Files": { + directory: types.StringNull(), + files: mustFilesMap(t, files), + archiveBase64: types.StringNull(), + expected: computeFilesHash(files), + }, + "Archive": { + directory: types.StringNull(), + files: types.MapNull(types.StringType), + archiveBase64: types.StringValue(archive), + expected: computeBytesHash(decodedArchive), + }, + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + versionVal, diags := types.ObjectValue(objType.AttrTypes, map[string]attr.Value{ + "id": NewUUIDUnknown(), + "name": types.StringValue("main"), + "message": types.StringValue(""), + "directory": tc.directory, + "files": tc.files, + "archive_base64": tc.archiveBase64, + "directory_hash": types.StringUnknown(), + "active": types.BoolValue(true), + "tf_vars": types.SetNull(variableSetElemType), + "provisioner_tags": types.SetNull(variableSetElemType), + }) + require.False(t, diags.HasError(), "building version object: %v", diags.Errors()) + + listVal, diags := types.ListValue(objType, []attr.Value{versionVal}) + require.False(t, diags.HasError(), "building list: %v", diags.Errors()) + + resp := &planmodifier.ListResponse{PlanValue: listVal} + NewVersionsPlanModifier().PlanModifyList(ctx, planmodifier.ListRequest{ + ConfigValue: listVal, + PlanValue: listVal, + }, resp) + require.False(t, resp.Diagnostics.HasError(), "PlanModifyList: %v", resp.Diagnostics.Errors()) + + var planned []TemplateVersion + diags = resp.PlanValue.ElementsAs(ctx, &planned, false) + require.False(t, diags.HasError(), "decoding planned versions: %v", diags.Errors()) + require.Len(t, planned, 1) + require.Equal(t, tc.expected, planned[0].DirectoryHash.ValueString()) + // There's no prior version with this hash, so a new one is created. + require.True(t, planned[0].ID.IsUnknown()) + }) + } +} diff --git a/internal/provider/util.go b/internal/provider/util.go index 0d0748a2..71d9e01a 100644 --- a/internal/provider/util.go +++ b/internal/provider/util.go @@ -8,6 +8,7 @@ import ( "net/http" "os" "path/filepath" + "sort" "strings" "github.com/coder/coder/v2/codersdk" @@ -86,6 +87,34 @@ func computeDirectoryHash(directory string) (string, error) { return hex.EncodeToString(hash.Sum(nil)), nil } +// computeFilesHash hashes a map of relative path to file content, as provided +// by a template version's `files` attribute. Paths are sorted so the hash +// doesn't depend on map iteration order, and each path is hashed alongside its +// contents so that renaming a file produces a new hash. +func computeFilesHash(files map[string]string) string { + paths := make([]string, 0, len(files)) + for path := range files { + paths = append(paths, path) + } + sort.Strings(paths) + + hash := sha256.New() + for _, path := range paths { + hash.Write([]byte(path)) + hash.Write([]byte{0}) + hash.Write([]byte(files[path])) + hash.Write([]byte{0}) + } + return hex.EncodeToString(hash.Sum(nil)) +} + +// computeBytesHash hashes raw contents, as provided by a template version's +// `archive_base64` attribute. +func computeBytesHash(contents []byte) string { + sum := sha256.Sum256(contents) + return hex.EncodeToString(sum[:]) +} + // memberDiff returns the members to add and remove from the group, given the // current members and the planned members. plannedMembers is deliberately our // custom type, as Terraform cannot automatically produce `[]uuid.UUID` from a From c8a129ab50477baa143dbf26687763787402156d Mon Sep 17 00:00:00 2001 From: michaelvillani Date: Thu, 17 Sep 2026 06:18:07 +0000 Subject: [PATCH 2/5] test(coderd_template): escape interpolation in inline version contents The example template's `${var.name}` was interpolated by the test's own configuration instead of reaching the provider, so the `files` acceptance test failed to plan with "Reference to undeclared input variable". The plan-only test now uses the same contents, so the mock-server test catches this without a Coder deployment. --- internal/provider/template_resource_test.go | 26 +++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/internal/provider/template_resource_test.go b/internal/provider/template_resource_test.go index 8c6f3d9e..b76a6008 100644 --- a/internal/provider/template_resource_test.go +++ b/internal/provider/template_resource_test.go @@ -2691,6 +2691,14 @@ func mustTarBase64(t *testing.T, files map[string]string) string { return base64.StdEncoding.EncodeToString(buf.Bytes()) } +// escapeTFInterpolation escapes Terraform's interpolation and directive +// markers, so that file contents embedded in a test configuration reach the +// provider verbatim instead of being evaluated by Terraform. +func escapeTFInterpolation(contents string) string { + contents = strings.ReplaceAll(contents, "${", "$${") + return strings.ReplaceAll(contents, "%{", "%%{") +} + // mustFilesMap converts a map of file path to content into the types.Map used // by a version's `files` attribute. func mustFilesMap(t *testing.T, files map[string]string) types.Map { @@ -3008,6 +3016,10 @@ resource "coderd_template" "test" { mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") require.NoError(t, err) + // The contents are interpolated into the test configuration as a string, so + // the template's own interpolations have to be escaped to survive it. + escapedMainTF := escapeTFInterpolation(string(mainTF)) + resource.Test(t, resource.TestCase{ PreCheck: func() { testAccPreCheck(t) }, IsUnitTest: true, @@ -3016,7 +3028,7 @@ resource "coderd_template" "test" { // The contents are provided inline, and `terraform.tfvars` is read // as a variable value just like it is for a `directory`. { - Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "one", string(mainTF)), + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "one", escapedMainTF), Check: resource.ComposeTestCheckFunc( resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.id"), resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.directory_hash"), @@ -3025,7 +3037,7 @@ resource "coderd_template" "test" { }, // Changing the contents creates a new version. { - Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "two", string(mainTF)+"\n# a change\n"), + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "two", escapedMainTF+"\n# a change\n"), Check: resource.ComposeTestCheckFunc( resource.TestCheckResourceAttr("coderd_template.test", "versions.0.name", "two"), ), @@ -3114,9 +3126,15 @@ resource "coderd_template" "test" { ] }` + // The example template is used verbatim, since its interpolations are + // exactly what a `files` entry has to carry through to the provider + // untouched. + mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") + require.NoError(t, err) + for name, source := range map[string]string{ - "Files": "files = { \"main.tf\" = \"resource \\\"null_resource\\\" \\\"a\\\" {}\" }", - "Archive": fmt.Sprintf("archive_base64 = %q", mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"})), + "Files": fmt.Sprintf("files = { \"main.tf\" = %q }", escapeTFInterpolation(string(mainTF))), + "Archive": fmt.Sprintf("archive_base64 = %q", mustTarBase64(t, map[string]string{"main.tf": string(mainTF)})), } { t.Run(name, func(t *testing.T) { resource.Test(t, resource.TestCase{ From 9e1bb9fd5c562ed944bba601fec541be181e9ab3 Mon Sep 17 00:00:00 2001 From: michaelvillani Date: Thu, 17 Sep 2026 08:11:24 +0000 Subject: [PATCH 3/5] feat(coderd_template): accept version contents as an archive file path `archive_base64` closed the gap for contents that live in the configuration, but an archive that already exists as a file still had to be read into the configuration with `filebase64()`, which is wasteful for anything of size and awkward when the archive is produced by a data source such as `archive_file`. A version can now point `archive_file` at an archive on disk instead. It is the fourth mutually exclusive content attribute, hashed while planning like `directory` is, so the archive has to exist at plan time. Both archive attributes now accept an uncompressed tar, a gzipped tar, or a zip archive, detected from the contents rather than a file extension: `archive_file` is otherwise unusable with the `archive_file` data source, which produces zip or tar.gz only. Tar and zip are uploaded as-is since the API takes both, gzip is decompressed first, and decompression is bounded by the archive size limit so a compression bomb can't be expanded into an unbounded amount of memory. Refs #439 --- docs/resources/template.md | 31 +- .../resources/coderd_template/resource.tf | 24 +- internal/provider/template_resource.go | 184 +++++++-- internal/provider/template_resource_test.go | 372 ++++++++++++++++-- internal/provider/util.go | 2 +- 5 files changed, 539 insertions(+), 74 deletions(-) diff --git a/docs/resources/template.md b/docs/resources/template.md index 9c2198aa..63b58c3b 100644 --- a/docs/resources/template.md +++ b/docs/resources/template.md @@ -56,7 +56,8 @@ resource "coderd_template" "ubuntu-main" { // Template contents don't have to live in a directory on disk: a version can be // built from rendered file contents, or from a prebuilt archive. Exactly one of -// `directory`, `files`, and `archive_base64` may be set on a version. +// `directory`, `files`, `archive_base64`, and `archive_file` may be set on a +// version. resource "coderd_template" "ubuntu-rendered" { name = "ubuntu-rendered" description = "The main template, rendered for this deployment." @@ -71,17 +72,34 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "prebuilt-${var.COMMIT_SHA}" - // A base64-encoded, uncompressed tar archive, such as one fetched from an - // artifact store. Variable values aren't discovered from an archive, so + // A base64-encoded tar, tar.gz, or zip archive, such as one fetched from + // an artifact store. Variable values aren't discovered from an archive, so // they're set with `tf_vars`. archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") tf_vars = [{ name = "image" value = "ubuntu:24.04" }] + }, + { + name = "packaged-${var.COMMIT_SHA}" + // The same archive, referenced by path instead of being read into the + // configuration. The file has to exist at plan time, so a data source is + // a better fit than a resource that writes it during apply. + archive_file = data.archive_file.template.output_path + tf_vars = [{ + name = "image" + value = "ubuntu:24.04" + }] } ] } + +data "archive_file" "template" { + type = "zip" + source_dir = "${path.module}/stable-template" + output_path = "${path.module}/build/template.zip" +} ``` @@ -162,9 +180,10 @@ Optional: Optional: - `active` (Boolean) Whether this version is the active version of the template. Only one version can be active at a time. -- `archive_base64` (String) A base64-encoded, uncompressed tar archive of the template version contents, uploaded as-is. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, or `archive_base64` must be set. -- `directory` (String) A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, or `archive_base64` must be set. -- `files` (Map of String) The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, or `archive_base64` must be set. +- `archive_base64` (String) A base64-encoded archive of the template version contents, uploaded as-is. The archive must be an uncompressed tar, a gzipped tar, or a zip archive. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set. +- `archive_file` (String) A path to an archive file containing the template version contents, uploaded as-is. The archive must be an uncompressed tar, a gzipped tar, or a zip archive, such as the one produced by the `archive_file` data source. The file is read while planning, so it must already exist at plan time, and changes to its contents will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set. +- `directory` (String) A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set. +- `files` (Map of String) The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set. - `message` (String) A message describing the changes in this version of the template. Messages longer than 72 characters will be truncated. - `name` (String) The name of the template version. Automatically generated if not provided. If provided, the name *must* change each time the version contents, or the `tf_vars` attribute are updated. - `provisioner_tags` (Attributes Set) Provisioner tags for the template version. (see [below for nested schema](#nestedatt--versions--provisioner_tags)) diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf index 345c92a6..53f21c85 100644 --- a/examples/resources/coderd_template/resource.tf +++ b/examples/resources/coderd_template/resource.tf @@ -38,7 +38,8 @@ resource "coderd_template" "ubuntu-main" { // Template contents don't have to live in a directory on disk: a version can be // built from rendered file contents, or from a prebuilt archive. Exactly one of -// `directory`, `files`, and `archive_base64` may be set on a version. +// `directory`, `files`, `archive_base64`, and `archive_file` may be set on a +// version. resource "coderd_template" "ubuntu-rendered" { name = "ubuntu-rendered" description = "The main template, rendered for this deployment." @@ -53,14 +54,31 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "prebuilt-${var.COMMIT_SHA}" - // A base64-encoded, uncompressed tar archive, such as one fetched from an - // artifact store. Variable values aren't discovered from an archive, so + // A base64-encoded tar, tar.gz, or zip archive, such as one fetched from + // an artifact store. Variable values aren't discovered from an archive, so // they're set with `tf_vars`. archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") tf_vars = [{ name = "image" value = "ubuntu:24.04" }] + }, + { + name = "packaged-${var.COMMIT_SHA}" + // The same archive, referenced by path instead of being read into the + // configuration. The file has to exist at plan time, so a data source is + // a better fit than a resource that writes it during apply. + archive_file = data.archive_file.template.output_path + tf_vars = [{ + name = "image" + value = "ubuntu:24.04" + }] } ] } + +data "archive_file" "template" { + type = "zip" + source_dir = "${path.module}/stable-template" + output_path = "${path.module}/build/template.zip" +} diff --git a/internal/provider/template_resource.go b/internal/provider/template_resource.go index 01724956..8bcffd46 100644 --- a/internal/provider/template_resource.go +++ b/internal/provider/template_resource.go @@ -2,8 +2,10 @@ package provider import ( "archive/tar" + "archive/zip" "bufio" "bytes" + "compress/gzip" "context" "encoding/base64" "encoding/json" @@ -174,6 +176,7 @@ type TemplateVersion struct { Directory types.String `tfsdk:"directory"` Files types.Map `tfsdk:"files"` ArchiveBase64 types.String `tfsdk:"archive_base64"` + ArchiveFile types.String `tfsdk:"archive_file"` DirectoryHash types.String `tfsdk:"directory_hash"` Active types.Bool `tfsdk:"active"` TerraformVariables types.Set `tfsdk:"tf_vars"` @@ -522,23 +525,28 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques Default: stringdefault.StaticString(""), }, "directory": schema.StringAttribute{ - MarkdownDescription: "A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + MarkdownDescription: "A path to the directory to create the template version from. Changes in the directory contents will trigger the creation of a new template version. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set.", Optional: true, Validators: []validator.String{ stringvalidator.ExactlyOneOf( path.MatchRelative().AtParent().AtName("directory"), path.MatchRelative().AtParent().AtName("files"), path.MatchRelative().AtParent().AtName("archive_base64"), + path.MatchRelative().AtParent().AtName("archive_file"), ), }, }, "files": schema.MapAttribute{ - MarkdownDescription: "The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + MarkdownDescription: "The contents of the template version, as a map of file path (relative to the root of the template) to file content. Paths must be relative and must not escape the root of the template, and at least one `.tf` or `.tf.json` file must be present at the root. Changes in the contents will trigger the creation of a new template version. The files are archived exactly as if they were read from a `directory`, meaning hidden files are excluded, and `terraform.tfvars`/`*.auto.tfvars` entries are read as variable values instead of being uploaded. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set.", Optional: true, ElementType: types.StringType, }, "archive_base64": schema.StringAttribute{ - MarkdownDescription: "A base64-encoded, uncompressed tar archive of the template version contents, uploaded as-is. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, or `archive_base64` must be set.", + MarkdownDescription: "A base64-encoded archive of the template version contents, uploaded as-is. The archive must be an uncompressed tar, a gzipped tar, or a zip archive. Changes in the archive will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set.", + Optional: true, + }, + "archive_file": schema.StringAttribute{ + MarkdownDescription: "A path to an archive file containing the template version contents, uploaded as-is. The archive must be an uncompressed tar, a gzipped tar, or a zip archive, such as the one produced by the `archive_file` data source. The file is read while planning, so it must already exist at plan time, and changes to its contents will trigger the creation of a new template version. Unlike `directory` and `files`, variable values are not discovered from the archive, so any `*.tfvars` files it contains are ignored - use `tf_vars` instead. Exactly one of `directory`, `files`, `archive_base64`, or `archive_file` must be set.", Optional: true, }, "directory_hash": schema.StringAttribute{ @@ -1216,12 +1224,17 @@ const ( versionSourceDirectory versionSourceFiles versionSourceArchive + versionSourceArchiveFile ) +// versionSourceAttrs lists the mutually exclusive content attributes, for use +// in diagnostics. +const versionSourceAttrs = "`directory`, `files`, `archive_base64`, or `archive_file`" + // versionSource reports which content attribute is set on a version. // `stringvalidator.ExactlyOneOf` enforces the same rule at validate time, but -// it defers whenever one of the three is unknown, so the invariant is checked -// here too rather than silently picking one of the configured sources. +// it defers whenever one of them is unknown, so the invariant is checked here +// too rather than silently picking one of the configured sources. func versionSource(version *TemplateVersion) (versionSourceKind, diag.Diagnostics) { var diags diag.Diagnostics kind := versionSourceNone @@ -1235,11 +1248,14 @@ func versionSource(version *TemplateVersion) (versionSourceKind, diag.Diagnostic if !version.ArchiveBase64.IsNull() { kind, count = versionSourceArchive, count+1 } + if !version.ArchiveFile.IsNull() { + kind, count = versionSourceArchiveFile, count+1 + } switch { case count == 0: - diags.AddError("Client Error", "A template version must set exactly one of `directory`, `files`, or `archive_base64`.") + diags.AddError("Client Error", "A template version must set exactly one of "+versionSourceAttrs+".") case count > 1: - diags.AddError("Client Error", "A template version can only set one of `directory`, `files`, or `archive_base64`.") + diags.AddError("Client Error", "A template version can only set one of "+versionSourceAttrs+".") } return kind, diags } @@ -1308,28 +1324,108 @@ func writeFiles(dir string, files map[string]string) error { return nil } +// Magic bytes identifying the archive formats accepted by `archive_base64` and +// `archive_file`. +var ( + gzipMagic = []byte{0x1f, 0x8b} + zipMagic = []byte("PK\x03\x04") +) + +// normalizeArchive sanity-checks raw archive contents and returns the bytes to +// upload along with the content type to upload them as. An uncompressed tar, a +// gzipped tar, or a zip archive is accepted: the Coder API takes tar and zip +// directly, and gzip is decompressed here so that archives produced by e.g. the +// `archive_file` data source can be used without a conversion step. +func normalizeArchive(raw []byte) (string, []byte, error) { + switch { + case bytes.HasPrefix(raw, gzipMagic): + payload, err := gunzipArchive(raw) + if err != nil { + return "", nil, err + } + if err := validateTarArchive(payload); err != nil { + return "", nil, fmt.Errorf("the gzipped archive does not contain a tar archive: %w", err) + } + return codersdk.ContentTypeTar, payload, nil + case bytes.HasPrefix(raw, zipMagic): + if err := checkArchiveSize(len(raw)); err != nil { + return "", nil, err + } + if _, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw))); err != nil { + return "", nil, fmt.Errorf("the archive is not a readable zip archive: %w", err) + } + return codersdk.ContentTypeZip, raw, nil + default: + if err := checkArchiveSize(len(raw)); err != nil { + return "", nil, err + } + if err := validateTarArchive(raw); err != nil { + return "", nil, fmt.Errorf("the archive must be an uncompressed tar, a gzipped tar, or a zip archive: %w", err) + } + return codersdk.ContentTypeTar, raw, nil + } +} + +func checkArchiveSize(size int) error { + if int64(size) >= provisionersdk.TemplateArchiveLimit { + return fmt.Errorf("archive too big. Must be < %d bytes", provisionersdk.TemplateArchiveLimit) + } + return nil +} + +func validateTarArchive(payload []byte) error { + _, err := tar.NewReader(bytes.NewReader(payload)).Next() + return err +} + +// gunzipArchive decompresses a gzipped archive, refusing to buffer more than +// the archive size limit so that a small, highly compressed archive can't be +// expanded into an unbounded amount of memory. +func gunzipArchive(raw []byte) ([]byte, error) { + reader, err := gzip.NewReader(bytes.NewReader(raw)) + if err != nil { + return nil, fmt.Errorf("the archive is not a readable gzip archive: %w", err) + } + defer func() { + _ = reader.Close() + }() + var buf bytes.Buffer + if _, err := io.CopyN(&buf, reader, provisionersdk.TemplateArchiveLimit); err != nil && !errors.Is(err, io.EOF) { + return nil, fmt.Errorf("failed to decompress the archive: %w", err) + } + if err := checkArchiveSize(buf.Len()); err != nil { + return nil, err + } + return buf.Bytes(), nil +} + // decodeArchive decodes and sanity-checks a version's `archive_base64` // attribute. It's called from the plan modifier as well as at apply time, so a // malformed archive fails the plan instead of a partially applied change. -func decodeArchive(archiveBase64 string) ([]byte, error) { - archive, err := base64.StdEncoding.DecodeString(archiveBase64) +func decodeArchive(archiveBase64 string) (string, []byte, error) { + raw, err := base64.StdEncoding.DecodeString(archiveBase64) if err != nil { - return nil, fmt.Errorf("`archive_base64` is not valid base64: %w", err) - } - if int64(len(archive)) >= provisionersdk.TemplateArchiveLimit { - return nil, fmt.Errorf("archive too big. Must be < %d bytes", provisionersdk.TemplateArchiveLimit) + return "", nil, fmt.Errorf("`archive_base64` is not valid base64: %w", err) } - if _, err := tar.NewReader(bytes.NewReader(archive)).Next(); err != nil { - return nil, fmt.Errorf("`archive_base64` must contain an uncompressed tar archive: %w", err) + return normalizeArchive(raw) +} + +// readArchiveFile reads and sanity-checks the archive a version's +// `archive_file` attribute points at. Like `computeDirectoryHash`, it reads +// from disk while planning, so the archive has to exist by then, and a missing +// or malformed one fails the plan instead of a partially applied change. +func readArchiveFile(filename string) (string, []byte, error) { + raw, err := os.ReadFile(filename) + if err != nil { + return "", nil, fmt.Errorf("failed to read `archive_file`: %w", err) } - return archive, nil + return normalizeArchive(raw) } -// versionContentHash hashes a version's contents, from whichever of -// `directory`, `files`, or `archive_base64` is set. The hash is what decides -// whether a new template version needs to be created, so it returns an unknown -// string when the configured source isn't known yet, which plans the version as -// new. +// versionContentHash hashes a version's contents, from whichever content +// attribute is set. The hash is what decides whether a new template version +// needs to be created, so it returns an unknown string when the configured +// source isn't known yet, which plans the version as new. func versionContentHash(ctx context.Context, version *TemplateVersion) (types.String, diag.Diagnostics) { source, diags := versionSource(version) if diags.HasError() { @@ -1364,7 +1460,17 @@ func versionContentHash(ctx context.Context, version *TemplateVersion) (types.St if version.ArchiveBase64.IsUnknown() { return types.StringUnknown(), diags } - archive, err := decodeArchive(version.ArchiveBase64.ValueString()) + _, archive, err := decodeArchive(version.ArchiveBase64.ValueString()) + if err != nil { + diags.AddError("Client Error", fmt.Sprintf("Failed to read template version archive: %s", err)) + return types.StringNull(), diags + } + return types.StringValue(computeBytesHash(archive)), diags + case versionSourceArchiveFile: + if version.ArchiveFile.IsUnknown() { + return types.StringUnknown(), diags + } + _, archive, err := readArchiveFile(version.ArchiveFile.ValueString()) if err != nil { diags.AddError("Client Error", fmt.Sprintf("Failed to read template version archive: %s", err)) return types.StringNull(), diags @@ -1415,9 +1521,8 @@ func uploadDirectory(ctx context.Context, client *codersdk.Client, logger slog.L } // uploadVersionContents uploads the contents of a template version from -// whichever of `directory`, `files`, or `archive_base64` is set, and returns -// the ID of the uploaded file along with any variable values discovered -// alongside the contents. +// whichever content attribute is set, and returns the ID of the uploaded file +// along with any variable values discovered alongside the contents. func uploadVersionContents(ctx context.Context, client *codersdk.Client, version *TemplateVersion) (uuid.UUID, []codersdk.VariableValue, error) { source, diags := versionSource(version) if diags.HasError() { @@ -1454,22 +1559,33 @@ func uploadVersionContents(ctx context.Context, client *codersdk.Client, version } return uploadTemplateDirectory(ctx, client, dir) case versionSourceArchive: - archive, err := decodeArchive(version.ArchiveBase64.ValueString()) + contentType, archive, err := decodeArchive(version.ArchiveBase64.ValueString()) if err != nil { return uuid.Nil, nil, fmt.Errorf("failed to read template version archive: %s", err) } - tflog.Info(ctx, "uploading archive") - uploadResp, err := client.Upload(ctx, codersdk.ContentTypeTar, bytes.NewReader(archive)) + return uploadTemplateArchive(ctx, client, contentType, archive) + case versionSourceArchiveFile: + contentType, archive, err := readArchiveFile(version.ArchiveFile.ValueString()) if err != nil { - return uuid.Nil, nil, fmt.Errorf("failed to upload archive: %s", err) + return uuid.Nil, nil, fmt.Errorf("failed to read template version archive: %s", err) } - tflog.Info(ctx, "successfully uploaded archive") - // Variable values can't be discovered without extracting the archive, - // so `tf_vars` is the only way to set them for this source. - return uploadResp.ID, nil, nil + return uploadTemplateArchive(ctx, client, contentType, archive) default: - return uuid.Nil, nil, errors.New("a template version must set exactly one of `directory`, `files`, or `archive_base64`") + return uuid.Nil, nil, errors.New("a template version must set exactly one of " + versionSourceAttrs) + } +} + +// uploadTemplateArchive uploads an already-built archive as-is. Variable values +// can't be discovered without extracting it, so `tf_vars` is the only way to +// set them for the archive sources. +func uploadTemplateArchive(ctx context.Context, client *codersdk.Client, contentType string, archive []byte) (uuid.UUID, []codersdk.VariableValue, error) { + tflog.Info(ctx, "uploading archive") + uploadResp, err := client.Upload(ctx, contentType, bytes.NewReader(archive)) + if err != nil { + return uuid.Nil, nil, fmt.Errorf("failed to upload archive: %s", err) } + tflog.Info(ctx, "successfully uploaded archive") + return uploadResp.ID, nil, nil } // uploadTemplateDirectory archives and uploads a directory, and parses the diff --git a/internal/provider/template_resource_test.go b/internal/provider/template_resource_test.go index b76a6008..e8e98d66 100644 --- a/internal/provider/template_resource_test.go +++ b/internal/provider/template_resource_test.go @@ -2,7 +2,9 @@ package provider import ( "archive/tar" + "archive/zip" "bytes" + "compress/gzip" "context" "encoding/base64" "fmt" @@ -2518,6 +2520,7 @@ func versionObjectType() types.ObjectType { ElemType: types.StringType, }, "archive_base64": types.StringType, + "archive_file": types.StringType, "directory_hash": types.StringType, "active": types.BoolType, "tf_vars": types.SetType{ @@ -2548,6 +2551,7 @@ func TestValidateListUnknownTFVars(t *testing.T) { "directory": types.StringValue("./template"), "files": types.MapNull(types.StringType), "archive_base64": types.StringNull(), + "archive_file": types.StringNull(), "directory_hash": types.StringUnknown(), "active": types.BoolValue(true), "tf_vars": types.SetUnknown(variableSetElemType), @@ -2588,6 +2592,7 @@ func TestUnknownTFVarsDeserialization(t *testing.T) { "directory": types.StringValue("/tmp/test"), "files": types.MapNull(types.StringType), "archive_base64": types.StringNull(), + "archive_file": types.StringNull(), "directory_hash": types.StringUnknown(), "active": types.BoolValue(true), "tf_vars": tfVars, @@ -2666,18 +2671,24 @@ func TestUnknownTFVarsDeserialization(t *testing.T) { }) } -// mustTarBase64 builds a base64-encoded tar archive from a map of file path to -// content, for use as a version's `archive_base64`. -func mustTarBase64(t *testing.T, files map[string]string) string { - t.Helper() - var buf bytes.Buffer - tw := tar.NewWriter(&buf) +// sortedPaths returns the paths of a file map in a deterministic order, so that +// the archives the helpers below build are reproducible. +func sortedPaths(files map[string]string) []string { paths := make([]string, 0, len(files)) for path := range files { paths = append(paths, path) } sort.Strings(paths) - for _, path := range paths { + return paths +} + +// mustTar builds an uncompressed tar archive from a map of file path to +// content. +func mustTar(t *testing.T, files map[string]string) []byte { + t.Helper() + var buf bytes.Buffer + tw := tar.NewWriter(&buf) + for _, path := range sortedPaths(files) { require.NoError(t, tw.WriteHeader(&tar.Header{ Name: path, Typeflag: tar.TypeReg, @@ -2688,7 +2699,51 @@ func mustTarBase64(t *testing.T, files map[string]string) string { require.NoError(t, err) } require.NoError(t, tw.Close()) - return base64.StdEncoding.EncodeToString(buf.Bytes()) + return buf.Bytes() +} + +// mustTarBase64 builds a base64-encoded tar archive from a map of file path to +// content, for use as a version's `archive_base64`. +func mustTarBase64(t *testing.T, files map[string]string) string { + t.Helper() + return base64.StdEncoding.EncodeToString(mustTar(t, files)) +} + +// mustGzip compresses an archive, as `tar -czf` or the `archive_file` data +// source's `tar.gz` type would. +func mustGzip(t *testing.T, contents []byte) []byte { + t.Helper() + var buf bytes.Buffer + gw := gzip.NewWriter(&buf) + _, err := gw.Write(contents) + require.NoError(t, err) + require.NoError(t, gw.Close()) + return buf.Bytes() +} + +// mustZip builds a zip archive from a map of file path to content, as the +// `archive_file` data source's default type would. +func mustZip(t *testing.T, files map[string]string) []byte { + t.Helper() + var buf bytes.Buffer + zw := zip.NewWriter(&buf) + for _, path := range sortedPaths(files) { + w, err := zw.Create(path) + require.NoError(t, err) + _, err = w.Write([]byte(files[path])) + require.NoError(t, err) + } + require.NoError(t, zw.Close()) + return buf.Bytes() +} + +// mustArchiveFile writes an archive to a temporary file and returns its path, +// for use as a version's `archive_file`. +func mustArchiveFile(t *testing.T, name string, contents []byte) string { + t.Helper() + path := filepath.Join(t.TempDir(), name) + require.NoError(t, os.WriteFile(path, contents, 0o644)) + return path } // escapeTFInterpolation escapes Terraform's interpolation and directive @@ -2801,6 +2856,51 @@ func TestVersionContentHash(t *testing.T) { require.Equal(t, computeBytesHash(decoded), hash.ValueString()) }) + t.Run("ArchiveFile", func(t *testing.T) { + t.Parallel() + contents := mustTar(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"}) + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Files: types.MapNull(types.StringType), + ArchiveFile: types.StringValue(mustArchiveFile(t, "template.tar", contents)), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.Equal(t, computeBytesHash(contents), hash.ValueString()) + }) + + // A gzipped archive hashes as the tar it decompresses to, so recompressing + // identical contents doesn't create a new version. + t.Run("GzippedArchiveFile", func(t *testing.T) { + t.Parallel() + contents := mustTar(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"}) + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Files: types.MapNull(types.StringType), + ArchiveFile: types.StringValue(mustArchiveFile(t, "template.tar.gz", mustGzip(t, contents))), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.Equal(t, computeBytesHash(contents), hash.ValueString()) + }) + + t.Run("UnknownArchiveFile", func(t *testing.T) { + t.Parallel() + hash, diags := versionContentHash(ctx, &TemplateVersion{ + Files: types.MapNull(types.StringType), + ArchiveFile: types.StringUnknown(), + }) + require.False(t, diags.HasError(), "%v", diags.Errors()) + require.True(t, hash.IsUnknown()) + }) + + // Unlike an unknown path, a known path that isn't there is a mistake worth + // failing the plan over, exactly like a missing `directory`. + t.Run("MissingArchiveFile", func(t *testing.T) { + t.Parallel() + _, diags := versionContentHash(ctx, &TemplateVersion{ + Files: types.MapNull(types.StringType), + ArchiveFile: types.StringValue(filepath.Join(t.TempDir(), "absent.tar")), + }) + require.True(t, diags.HasError()) + }) + // A source that isn't known yet must plan as a new version rather than // failing, since the contents can come from another resource. t.Run("UnknownFiles", func(t *testing.T) { @@ -2850,8 +2950,8 @@ func TestVersionContentHash(t *testing.T) { require.True(t, diags.HasError()) }) - // `stringvalidator.ExactlyOneOf` defers whenever one of the three is - // unknown, so this has to be caught here as well. + // `stringvalidator.ExactlyOneOf` defers whenever one of them is unknown, + // so this has to be caught here as well. t.Run("MultipleSources", func(t *testing.T) { t.Parallel() _, diags := versionContentHash(ctx, &TemplateVersion{ @@ -2888,32 +2988,155 @@ func TestDecodeArchive(t *testing.T) { t.Run("Tar", func(t *testing.T) { t.Parallel() - archive, err := decodeArchive(mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"})) + contentType, archive, err := decodeArchive(mustTarBase64(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"})) require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeTar, contentType) require.NotEmpty(t, archive) }) t.Run("NotBase64", func(t *testing.T) { t.Parallel() - _, err := decodeArchive("not base64!") + _, _, err := decodeArchive("not base64!") require.ErrorContains(t, err, "not valid base64") }) - t.Run("NotATar", func(t *testing.T) { + t.Run("NotAnArchive", func(t *testing.T) { t.Parallel() - _, err := decodeArchive(base64.StdEncoding.EncodeToString([]byte("resource \"null_resource\" \"a\" {}"))) - require.ErrorContains(t, err, "uncompressed tar archive") + _, _, err := decodeArchive(base64.StdEncoding.EncodeToString([]byte("resource \"null_resource\" \"a\" {}"))) + require.ErrorContains(t, err, "uncompressed tar, a gzipped tar, or a zip archive") }) t.Run("TooBig", func(t *testing.T) { t.Parallel() - _, err := decodeArchive(mustTarBase64(t, map[string]string{ + _, _, err := decodeArchive(mustTarBase64(t, map[string]string{ + "main.tf": strings.Repeat("a", provisionersdk.TemplateArchiveLimit), + })) + require.ErrorContains(t, err, "too big") + }) +} + +func TestNormalizeArchive(t *testing.T) { + t.Parallel() + + files := map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"} + + t.Run("Tar", func(t *testing.T) { + t.Parallel() + tarred := mustTar(t, files) + contentType, payload, err := normalizeArchive(tarred) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeTar, contentType) + require.Equal(t, tarred, payload) + }) + + // A gzipped tar is decompressed here, since the API only accepts tar and + // zip. + t.Run("GzippedTar", func(t *testing.T) { + t.Parallel() + tarred := mustTar(t, files) + contentType, payload, err := normalizeArchive(mustGzip(t, tarred)) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeTar, contentType) + require.Equal(t, tarred, payload) + }) + + // A zip is uploaded as-is: the API expands it server-side. + t.Run("Zip", func(t *testing.T) { + t.Parallel() + zipped := mustZip(t, files) + contentType, payload, err := normalizeArchive(zipped) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeZip, contentType) + require.Equal(t, zipped, payload) + }) + + t.Run("GzippedNonTar", func(t *testing.T) { + t.Parallel() + _, _, err := normalizeArchive(mustGzip(t, []byte("not a tar archive"))) + require.ErrorContains(t, err, "does not contain a tar archive") + }) + + t.Run("TruncatedZip", func(t *testing.T) { + t.Parallel() + zipped := mustZip(t, files) + _, _, err := normalizeArchive(zipped[:len(zipped)/2]) + require.ErrorContains(t, err, "readable zip archive") + }) + + // A small archive must not be allowed to expand into an unbounded amount + // of memory. + t.Run("GzipBomb", func(t *testing.T) { + t.Parallel() + bomb := mustGzip(t, mustTar(t, map[string]string{ "main.tf": strings.Repeat("a", provisionersdk.TemplateArchiveLimit), })) + require.Less(t, len(bomb), provisionersdk.TemplateArchiveLimit) + _, _, err := normalizeArchive(bomb) + require.ErrorContains(t, err, "too big") + }) + + t.Run("ZipTooBig", func(t *testing.T) { + t.Parallel() + // Pseudo-random, and so incompressible, contents: the zip itself has + // to exceed the limit for the size check to be the one that fails. + big := make([]byte, provisionersdk.TemplateArchiveLimit) + x := uint64(88172645463325252) + for i := range big { + x ^= x << 13 + x ^= x >> 7 + x ^= x << 17 + big[i] = byte(x) + } + _, _, err := normalizeArchive(mustZip(t, map[string]string{"main.tf": string(big)})) require.ErrorContains(t, err, "too big") }) } +func TestReadArchiveFile(t *testing.T) { + t.Parallel() + + files := map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"} + + t.Run("Tar", func(t *testing.T) { + t.Parallel() + tarred := mustTar(t, files) + contentType, payload, err := readArchiveFile(mustArchiveFile(t, "template.tar", tarred)) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeTar, contentType) + require.Equal(t, tarred, payload) + }) + + t.Run("Zip", func(t *testing.T) { + t.Parallel() + zipped := mustZip(t, files) + contentType, payload, err := readArchiveFile(mustArchiveFile(t, "template.zip", zipped)) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeZip, contentType) + require.Equal(t, zipped, payload) + }) + + // The extension is irrelevant: the format is detected from the contents, + // so a mislabelled archive still works. + t.Run("MislabelledExtension", func(t *testing.T) { + t.Parallel() + contentType, _, err := readArchiveFile(mustArchiveFile(t, "template.tar", mustZip(t, files))) + require.NoError(t, err) + require.Equal(t, codersdk.ContentTypeZip, contentType) + }) + + t.Run("Missing", func(t *testing.T) { + t.Parallel() + _, _, err := readArchiveFile(filepath.Join(t.TempDir(), "absent.tar")) + require.ErrorContains(t, err, "failed to read `archive_file`") + }) + + t.Run("NotAnArchive", func(t *testing.T) { + t.Parallel() + _, _, err := readArchiveFile(mustArchiveFile(t, "template.tar", []byte("resource \"null_resource\" \"a\" {}"))) + require.ErrorContains(t, err, "uncompressed tar, a gzipped tar, or a zip archive") + }) +} + func TestWriteFiles(t *testing.T) { t.Parallel() @@ -2961,12 +3184,23 @@ resource "coderd_template" "test" { // These all fail during validation, before the provider is configured, so // no Coder deployment is needed. + const ( + directory = "directory = \"./example-template\"" + files = "files = { \"main.tf\" = \"\" }" + archiveBase64 = "archive_base64 = \"\"" + archiveFile = "archive_file = \"./example-template.tar\"" + sep = "\n\t\t\t" + ) + for name, source := range map[string]string{ - "NoSource": ``, - "DirectoryAndFiles": "directory = \"./example-template\"\n\t\t\tfiles = { \"main.tf\" = \"\" }", - "DirectoryAndArchive": "directory = \"./example-template\"\n\t\t\tarchive_base64 = \"\"", - "FilesAndArchive": "files = { \"main.tf\" = \"\" }\n\t\t\tarchive_base64 = \"\"", - "AllThree": "directory = \"./example-template\"\n\t\t\tfiles = { \"main.tf\" = \"\" }\n\t\t\tarchive_base64 = \"\"", + "NoSource": ``, + "DirectoryAndFiles": directory + sep + files, + "DirectoryAndArchive": directory + sep + archiveBase64, + "DirectoryAndArchiveFile": directory + sep + archiveFile, + "FilesAndArchive": files + sep + archiveBase64, + "FilesAndArchiveFile": files + sep + archiveFile, + "BothArchives": archiveBase64 + sep + archiveFile, + "AllFour": directory + sep + files + sep + archiveBase64 + sep + archiveFile, } { t.Run(name, func(t *testing.T) { resource.Test(t, resource.TestCase{ @@ -3097,10 +3331,64 @@ resource "coderd_template" "test" { }) } +func TestAccTemplateResourceArchiveFile(t *testing.T) { + t.Parallel() + if os.Getenv("TF_ACC") == "" { + t.Skip("Acceptance tests are disabled.") + } + + cfg := ` +provider coderd { + url = %q + token = %q +} + +resource "coderd_template" "test" { + name = "archive-file-template" + versions = [ + { + active = true + archive_file = %q + tf_vars = [ + { + name = "name" + value = "world" + } + ] + } + ] +}` + + ctx := t.Context() + client := integration.StartCoder(ctx, t, "template_resource_archive_file_acc") + + mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") + require.NoError(t, err) + files := map[string]string{"main.tf": string(mainTF)} + // A zip, since that's what the `archive_file` data source produces by + // default, and it exercises the server-side expansion. + archive := mustArchiveFile(t, "template.zip", mustZip(t, files)) + + resource.Test(t, resource.TestCase{ + PreCheck: func() { testAccPreCheck(t) }, + IsUnitTest: true, + ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, + Steps: []resource.TestStep{ + { + Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), archive), + Check: resource.ComposeTestCheckFunc( + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.id"), + resource.TestCheckResourceAttrSet("coderd_template.test", "versions.0.directory_hash"), + ), + }, + }, + }) +} + // TestAccTemplateResourceVersionSourcePlan checks that a version whose contents -// come from `files` or `archive_base64` plans without error, end to end. It -// only plans, so a mock server is enough. The hash the plan modifier produces -// is asserted in TestVersionsPlanModifierContentHash. +// come from `files`, `archive_base64`, or `archive_file` plans without error, +// end to end. It only plans, so a mock server is enough. The hash the plan +// modifier produces is asserted in TestVersionsPlanModifierContentHash. func TestAccTemplateResourceVersionSourcePlan(t *testing.T) { t.Parallel() if os.Getenv("TF_ACC") == "" { @@ -3132,9 +3420,14 @@ resource "coderd_template" "test" { mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") require.NoError(t, err) + tarred := mustTar(t, map[string]string{"main.tf": string(mainTF)}) + for name, source := range map[string]string{ - "Files": fmt.Sprintf("files = { \"main.tf\" = %q }", escapeTFInterpolation(string(mainTF))), - "Archive": fmt.Sprintf("archive_base64 = %q", mustTarBase64(t, map[string]string{"main.tf": string(mainTF)})), + "Files": fmt.Sprintf("files = { \"main.tf\" = %q }", escapeTFInterpolation(string(mainTF))), + "Archive": fmt.Sprintf("archive_base64 = %q", base64.StdEncoding.EncodeToString(tarred)), + "ArchiveFile": fmt.Sprintf("archive_file = %q", mustArchiveFile(t, "template.tar", tarred)), + "ZippedArchiveFile": fmt.Sprintf("archive_file = %q", + mustArchiveFile(t, "template.zip", mustZip(t, map[string]string{"main.tf": string(mainTF)}))), } { t.Run(name, func(t *testing.T) { resource.Test(t, resource.TestCase{ @@ -3170,33 +3463,51 @@ func TestVersionsPlanModifierContentHash(t *testing.T) { require.NoError(t, err) files := map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"} - archive := mustTarBase64(t, files) - decodedArchive, err := base64.StdEncoding.DecodeString(archive) - require.NoError(t, err) + tarred := mustTar(t, files) + archive := base64.StdEncoding.EncodeToString(tarred) + zipped := mustZip(t, files) for name, tc := range map[string]struct { directory attr.Value files attr.Value archiveBase64 attr.Value + archiveFile attr.Value expected string }{ "Directory": { directory: types.StringValue(dir), files: types.MapNull(types.StringType), archiveBase64: types.StringNull(), + archiveFile: types.StringNull(), expected: dirHash, }, "Files": { directory: types.StringNull(), files: mustFilesMap(t, files), archiveBase64: types.StringNull(), + archiveFile: types.StringNull(), expected: computeFilesHash(files), }, "Archive": { directory: types.StringNull(), files: types.MapNull(types.StringType), archiveBase64: types.StringValue(archive), - expected: computeBytesHash(decodedArchive), + archiveFile: types.StringNull(), + expected: computeBytesHash(tarred), + }, + "ArchiveFile": { + directory: types.StringNull(), + files: types.MapNull(types.StringType), + archiveBase64: types.StringNull(), + archiveFile: types.StringValue(mustArchiveFile(t, "template.tar", tarred)), + expected: computeBytesHash(tarred), + }, + "ZippedArchiveFile": { + directory: types.StringNull(), + files: types.MapNull(types.StringType), + archiveBase64: types.StringNull(), + archiveFile: types.StringValue(mustArchiveFile(t, "template.zip", zipped)), + expected: computeBytesHash(zipped), }, } { t.Run(name, func(t *testing.T) { @@ -3208,6 +3519,7 @@ func TestVersionsPlanModifierContentHash(t *testing.T) { "directory": tc.directory, "files": tc.files, "archive_base64": tc.archiveBase64, + "archive_file": tc.archiveFile, "directory_hash": types.StringUnknown(), "active": types.BoolValue(true), "tf_vars": types.SetNull(variableSetElemType), diff --git a/internal/provider/util.go b/internal/provider/util.go index 71d9e01a..bb318469 100644 --- a/internal/provider/util.go +++ b/internal/provider/util.go @@ -109,7 +109,7 @@ func computeFilesHash(files map[string]string) string { } // computeBytesHash hashes raw contents, as provided by a template version's -// `archive_base64` attribute. +// `archive_base64` or `archive_file` attribute. func computeBytesHash(contents []byte) string { sum := sha256.Sum256(contents) return hex.EncodeToString(sum[:]) From 1101ff9df2bece37a4b836bf91504d105d906f51 Mon Sep 17 00:00:00 2001 From: michaelvillani Date: Thu, 17 Sep 2026 09:56:59 +0000 Subject: [PATCH 4/5] chore(coderd_template): return only the file ID from the archive upload helper `uploadTemplateArchive` returned a `[]codersdk.VariableValue` that was always nil, to match the shape of `uploadVersionContents`. `unparam` rejects that, failing the build job's linters, so the helper now returns just the file ID and its callers supply the nil themselves. --- internal/provider/template_resource.go | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/internal/provider/template_resource.go b/internal/provider/template_resource.go index 8bcffd46..1e7724e0 100644 --- a/internal/provider/template_resource.go +++ b/internal/provider/template_resource.go @@ -1563,29 +1563,32 @@ func uploadVersionContents(ctx context.Context, client *codersdk.Client, version if err != nil { return uuid.Nil, nil, fmt.Errorf("failed to read template version archive: %s", err) } - return uploadTemplateArchive(ctx, client, contentType, archive) + fileID, err := uploadTemplateArchive(ctx, client, contentType, archive) + return fileID, nil, err case versionSourceArchiveFile: contentType, archive, err := readArchiveFile(version.ArchiveFile.ValueString()) if err != nil { return uuid.Nil, nil, fmt.Errorf("failed to read template version archive: %s", err) } - return uploadTemplateArchive(ctx, client, contentType, archive) + fileID, err := uploadTemplateArchive(ctx, client, contentType, archive) + return fileID, nil, err default: return uuid.Nil, nil, errors.New("a template version must set exactly one of " + versionSourceAttrs) } } -// uploadTemplateArchive uploads an already-built archive as-is. Variable values -// can't be discovered without extracting it, so `tf_vars` is the only way to +// uploadTemplateArchive uploads an already-built archive as-is, and returns the +// ID of the uploaded file. It reports no variable values: they can't be +// discovered without extracting the archive, so `tf_vars` is the only way to // set them for the archive sources. -func uploadTemplateArchive(ctx context.Context, client *codersdk.Client, contentType string, archive []byte) (uuid.UUID, []codersdk.VariableValue, error) { +func uploadTemplateArchive(ctx context.Context, client *codersdk.Client, contentType string, archive []byte) (uuid.UUID, error) { tflog.Info(ctx, "uploading archive") uploadResp, err := client.Upload(ctx, contentType, bytes.NewReader(archive)) if err != nil { - return uuid.Nil, nil, fmt.Errorf("failed to upload archive: %s", err) + return uuid.Nil, fmt.Errorf("failed to upload archive: %s", err) } tflog.Info(ctx, "successfully uploaded archive") - return uploadResp.ID, nil, nil + return uploadResp.ID, nil } // uploadTemplateDirectory archives and uploads a directory, and parses the From 1136c486f24f657f875b811e3ab5b3cf9a4f9ef4 Mon Sep 17 00:00:00 2001 From: michaelvillani Date: Thu, 17 Sep 2026 11:54:32 +0000 Subject: [PATCH 5/5] chore(coderd_template): trim the version contents comments to the repo's style The comments added for `files`, `archive_base64`, and `archive_file` explained why the code is the way it is. The rest of the package states what a function does and leaves the reasoning to the pull request, so these now do the same. --- docs/resources/template.md | 15 ++-- .../resources/coderd_template/resource.tf | 15 ++-- internal/provider/template_resource.go | 50 ++++--------- internal/provider/template_resource_test.go | 70 ++++++------------- internal/provider/util.go | 4 +- 5 files changed, 47 insertions(+), 107 deletions(-) diff --git a/docs/resources/template.md b/docs/resources/template.md index 63b58c3b..aa20a730 100644 --- a/docs/resources/template.md +++ b/docs/resources/template.md @@ -54,10 +54,8 @@ resource "coderd_template" "ubuntu-main" { } } -// Template contents don't have to live in a directory on disk: a version can be -// built from rendered file contents, or from a prebuilt archive. Exactly one of -// `directory`, `files`, `archive_base64`, and `archive_file` may be set on a -// version. +// Exactly one of `directory`, `files`, `archive_base64`, and `archive_file` may +// be set on a version. resource "coderd_template" "ubuntu-rendered" { name = "ubuntu-rendered" description = "The main template, rendered for this deployment." @@ -72,9 +70,8 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "prebuilt-${var.COMMIT_SHA}" - // A base64-encoded tar, tar.gz, or zip archive, such as one fetched from - // an artifact store. Variable values aren't discovered from an archive, so - // they're set with `tf_vars`. + // A base64-encoded tar, tar.gz, or zip archive. Variable values aren't + // discovered from an archive, so they're set with `tf_vars`. archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") tf_vars = [{ name = "image" @@ -83,9 +80,7 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "packaged-${var.COMMIT_SHA}" - // The same archive, referenced by path instead of being read into the - // configuration. The file has to exist at plan time, so a data source is - // a better fit than a resource that writes it during apply. + // The same archive, referenced by path. It has to exist at plan time. archive_file = data.archive_file.template.output_path tf_vars = [{ name = "image" diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf index 53f21c85..fe123fba 100644 --- a/examples/resources/coderd_template/resource.tf +++ b/examples/resources/coderd_template/resource.tf @@ -36,10 +36,8 @@ resource "coderd_template" "ubuntu-main" { } } -// Template contents don't have to live in a directory on disk: a version can be -// built from rendered file contents, or from a prebuilt archive. Exactly one of -// `directory`, `files`, `archive_base64`, and `archive_file` may be set on a -// version. +// Exactly one of `directory`, `files`, `archive_base64`, and `archive_file` may +// be set on a version. resource "coderd_template" "ubuntu-rendered" { name = "ubuntu-rendered" description = "The main template, rendered for this deployment." @@ -54,9 +52,8 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "prebuilt-${var.COMMIT_SHA}" - // A base64-encoded tar, tar.gz, or zip archive, such as one fetched from - // an artifact store. Variable values aren't discovered from an archive, so - // they're set with `tf_vars`. + // A base64-encoded tar, tar.gz, or zip archive. Variable values aren't + // discovered from an archive, so they're set with `tf_vars`. archive_base64 = filebase64("${path.module}/tpl/prebuilt.tar") tf_vars = [{ name = "image" @@ -65,9 +62,7 @@ resource "coderd_template" "ubuntu-rendered" { }, { name = "packaged-${var.COMMIT_SHA}" - // The same archive, referenced by path instead of being read into the - // configuration. The file has to exist at plan time, so a data source is - // a better fit than a resource that writes it during apply. + // The same archive, referenced by path. It has to exist at plan time. archive_file = data.archive_file.template.output_path tf_vars = [{ name = "image" diff --git a/internal/provider/template_resource.go b/internal/provider/template_resource.go index 1e7724e0..edb7c864 100644 --- a/internal/provider/template_resource.go +++ b/internal/provider/template_resource.go @@ -712,8 +712,6 @@ func (r *TemplateResource) Create(ctx context.Context, req resource.CreateReques data.UseClassicParameterFlow = types.BoolValue(ucpfResp.UseClassicParameterFlow) } - // Any hash left unknown at plan time (because its contents weren't known - // yet) has to be resolved before it's written to state. resp.Diagnostics.Append(data.Versions.resolveContentHashes(ctx)...) if resp.Diagnostics.HasError() { return @@ -1232,9 +1230,6 @@ const ( const versionSourceAttrs = "`directory`, `files`, `archive_base64`, or `archive_file`" // versionSource reports which content attribute is set on a version. -// `stringvalidator.ExactlyOneOf` enforces the same rule at validate time, but -// it defers whenever one of them is unknown, so the invariant is checked here -// too rather than silently picking one of the configured sources. func versionSource(version *TemplateVersion) (versionSourceKind, diag.Diagnostics) { var diags diag.Diagnostics kind := versionSourceNone @@ -1262,8 +1257,7 @@ func versionSource(version *TemplateVersion) (versionSourceKind, diag.Diagnostic // filesFromMap converts a version's `files` attribute into a map of relative // path to content. It returns a nil map, without diagnostics, when the map or -// any of its elements is still unknown: the contents can neither be hashed nor -// uploaded yet, and callers treat that as "not known". +// any of its elements is still unknown. func filesFromMap(ctx context.Context, files types.Map) (map[string]string, diag.Diagnostics) { var diags diag.Diagnostics if files.IsNull() || files.IsUnknown() { @@ -1288,10 +1282,7 @@ func filesFromMap(ctx context.Context, files types.Map) (map[string]string, diag } // filesHaveTerraform reports whether a `files` map contains a Terraform file at -// the root of the template. The files are archived through -// `provisionersdk.Tar`, which rejects a directory without one, but its error -// refers to the temporary directory they're written to, so this is checked up -// front instead. +// the root of the template. func filesHaveTerraform(files map[string]string) bool { for name := range files { rel := filepath.Clean(filepath.FromSlash(name)) @@ -1305,8 +1296,7 @@ func filesHaveTerraform(files map[string]string) bool { return false } -// writeFiles materializes a `files` map into dir so that it can be archived and -// have its variable files discovered exactly like a configured `directory`. +// writeFiles materializes a `files` map into dir. func writeFiles(dir string, files map[string]string) error { for name, content := range files { rel := filepath.Clean(filepath.FromSlash(name)) @@ -1333,9 +1323,7 @@ var ( // normalizeArchive sanity-checks raw archive contents and returns the bytes to // upload along with the content type to upload them as. An uncompressed tar, a -// gzipped tar, or a zip archive is accepted: the Coder API takes tar and zip -// directly, and gzip is decompressed here so that archives produced by e.g. the -// `archive_file` data source can be used without a conversion step. +// gzipped tar, or a zip archive is accepted; a gzipped tar is decompressed. func normalizeArchive(raw []byte) (string, []byte, error) { switch { case bytes.HasPrefix(raw, gzipMagic): @@ -1378,9 +1366,8 @@ func validateTarArchive(payload []byte) error { return err } -// gunzipArchive decompresses a gzipped archive, refusing to buffer more than -// the archive size limit so that a small, highly compressed archive can't be -// expanded into an unbounded amount of memory. +// gunzipArchive decompresses a gzipped archive, buffering at most the archive +// size limit. func gunzipArchive(raw []byte) ([]byte, error) { reader, err := gzip.NewReader(bytes.NewReader(raw)) if err != nil { @@ -1400,8 +1387,7 @@ func gunzipArchive(raw []byte) ([]byte, error) { } // decodeArchive decodes and sanity-checks a version's `archive_base64` -// attribute. It's called from the plan modifier as well as at apply time, so a -// malformed archive fails the plan instead of a partially applied change. +// attribute. func decodeArchive(archiveBase64 string) (string, []byte, error) { raw, err := base64.StdEncoding.DecodeString(archiveBase64) if err != nil { @@ -1411,9 +1397,7 @@ func decodeArchive(archiveBase64 string) (string, []byte, error) { } // readArchiveFile reads and sanity-checks the archive a version's -// `archive_file` attribute points at. Like `computeDirectoryHash`, it reads -// from disk while planning, so the archive has to exist by then, and a missing -// or malformed one fails the plan instead of a partially applied change. +// `archive_file` attribute points at. func readArchiveFile(filename string) (string, []byte, error) { raw, err := os.ReadFile(filename) if err != nil { @@ -1423,9 +1407,8 @@ func readArchiveFile(filename string) (string, []byte, error) { } // versionContentHash hashes a version's contents, from whichever content -// attribute is set. The hash is what decides whether a new template version -// needs to be created, so it returns an unknown string when the configured -// source isn't known yet, which plans the version as new. +// attribute is set. It returns an unknown string when the configured source +// isn't known yet. func versionContentHash(ctx context.Context, version *TemplateVersion) (types.String, diag.Diagnostics) { source, diags := versionSource(version) if diags.HasError() { @@ -1482,8 +1465,7 @@ func versionContentHash(ctx context.Context, version *TemplateVersion) (types.St } // resolveContentHashes fills in any version hash that was left unknown at plan -// time, so that the hashes written to state (and to the private state that -// matches versions across plans) are always known. +// time. func (v Versions) resolveContentHashes(ctx context.Context) (diags diag.Diagnostics) { for i := range v { if !v[i].DirectoryHash.IsUnknown() { @@ -1539,10 +1521,6 @@ func uploadVersionContents(ctx context.Context, client *codersdk.Client, version if files == nil { return uuid.Nil, nil, errors.New("the contents of `files` are not known") } - // The files are written out and then archived like any other directory, - // so that a version built from `files` behaves identically to the same - // contents on disk (hidden file handling, variable file discovery, and - // the archive size limit all included). dir, err := os.MkdirTemp("", "coderd-template-version-") if err != nil { return uuid.Nil, nil, fmt.Errorf("failed to create temporary directory for `files`: %s", err) @@ -1577,10 +1555,8 @@ func uploadVersionContents(ctx context.Context, client *codersdk.Client, version } } -// uploadTemplateArchive uploads an already-built archive as-is, and returns the -// ID of the uploaded file. It reports no variable values: they can't be -// discovered without extracting the archive, so `tf_vars` is the only way to -// set them for the archive sources. +// uploadTemplateArchive uploads an already-built archive and returns the ID of +// the uploaded file. func uploadTemplateArchive(ctx context.Context, client *codersdk.Client, contentType string, archive []byte) (uuid.UUID, error) { tflog.Info(ctx, "uploading archive") uploadResp, err := client.Upload(ctx, contentType, bytes.NewReader(archive)) diff --git a/internal/provider/template_resource_test.go b/internal/provider/template_resource_test.go index e8e98d66..7d2ea9ca 100644 --- a/internal/provider/template_resource_test.go +++ b/internal/provider/template_resource_test.go @@ -2671,8 +2671,7 @@ func TestUnknownTFVarsDeserialization(t *testing.T) { }) } -// sortedPaths returns the paths of a file map in a deterministic order, so that -// the archives the helpers below build are reproducible. +// sortedPaths returns the paths of a file map in sorted order. func sortedPaths(files map[string]string) []string { paths := make([]string, 0, len(files)) for path := range files { @@ -2709,8 +2708,7 @@ func mustTarBase64(t *testing.T, files map[string]string) string { return base64.StdEncoding.EncodeToString(mustTar(t, files)) } -// mustGzip compresses an archive, as `tar -czf` or the `archive_file` data -// source's `tar.gz` type would. +// mustGzip compresses an archive with gzip. func mustGzip(t *testing.T, contents []byte) []byte { t.Helper() var buf bytes.Buffer @@ -2721,8 +2719,7 @@ func mustGzip(t *testing.T, contents []byte) []byte { return buf.Bytes() } -// mustZip builds a zip archive from a map of file path to content, as the -// `archive_file` data source's default type would. +// mustZip builds a zip archive from a map of file path to content. func mustZip(t *testing.T, files map[string]string) []byte { t.Helper() var buf bytes.Buffer @@ -2747,8 +2744,7 @@ func mustArchiveFile(t *testing.T, name string, contents []byte) string { } // escapeTFInterpolation escapes Terraform's interpolation and directive -// markers, so that file contents embedded in a test configuration reach the -// provider verbatim instead of being evaluated by Terraform. +// markers in file contents embedded in a test configuration. func escapeTFInterpolation(contents string) string { contents = strings.ReplaceAll(contents, "${", "$${") return strings.ReplaceAll(contents, "%{", "%%{") @@ -2773,9 +2769,7 @@ func TestComputeFilesHash(t *testing.T) { t.Run("StableAcrossMaps", func(t *testing.T) { t.Parallel() - // A different map with the same entries must hash identically, - // otherwise map iteration order would create a new version on - // every plan. + // A different map with the same entries must hash identically. other := computeFilesHash(map[string]string{ "build/Dockerfile": "FROM ubuntu", "main.tf": "resource \"null_resource\" \"a\" {}", @@ -2793,8 +2787,7 @@ func TestComputeFilesHash(t *testing.T) { t.Run("RenameChanges", func(t *testing.T) { t.Parallel() - // Paths are hashed alongside contents, so moving a file is a change - // even though the bytes are identical. + // Moving a file is a change even though the bytes are identical. require.NotEqual(t, base, computeFilesHash(map[string]string{ "main.tf": "resource \"null_resource\" \"a\" {}", "build/Containerfile": "FROM ubuntu", @@ -2867,8 +2860,7 @@ func TestVersionContentHash(t *testing.T) { require.Equal(t, computeBytesHash(contents), hash.ValueString()) }) - // A gzipped archive hashes as the tar it decompresses to, so recompressing - // identical contents doesn't create a new version. + // A gzipped archive hashes as the tar it decompresses to. t.Run("GzippedArchiveFile", func(t *testing.T) { t.Parallel() contents := mustTar(t, map[string]string{"main.tf": "resource \"null_resource\" \"a\" {}"}) @@ -2890,8 +2882,7 @@ func TestVersionContentHash(t *testing.T) { require.True(t, hash.IsUnknown()) }) - // Unlike an unknown path, a known path that isn't there is a mistake worth - // failing the plan over, exactly like a missing `directory`. + // A known path that isn't there fails, like a missing `directory`. t.Run("MissingArchiveFile", func(t *testing.T) { t.Parallel() _, diags := versionContentHash(ctx, &TemplateVersion{ @@ -2901,8 +2892,7 @@ func TestVersionContentHash(t *testing.T) { require.True(t, diags.HasError()) }) - // A source that isn't known yet must plan as a new version rather than - // failing, since the contents can come from another resource. + // A source that isn't known yet plans as a new version rather than failing. t.Run("UnknownFiles", func(t *testing.T) { t.Parallel() hash, diags := versionContentHash(ctx, &TemplateVersion{ @@ -2950,8 +2940,6 @@ func TestVersionContentHash(t *testing.T) { require.True(t, diags.HasError()) }) - // `stringvalidator.ExactlyOneOf` defers whenever one of them is unknown, - // so this has to be caught here as well. t.Run("MultipleSources", func(t *testing.T) { t.Parallel() _, diags := versionContentHash(ctx, &TemplateVersion{ @@ -3029,8 +3017,6 @@ func TestNormalizeArchive(t *testing.T) { require.Equal(t, tarred, payload) }) - // A gzipped tar is decompressed here, since the API only accepts tar and - // zip. t.Run("GzippedTar", func(t *testing.T) { t.Parallel() tarred := mustTar(t, files) @@ -3040,7 +3026,6 @@ func TestNormalizeArchive(t *testing.T) { require.Equal(t, tarred, payload) }) - // A zip is uploaded as-is: the API expands it server-side. t.Run("Zip", func(t *testing.T) { t.Parallel() zipped := mustZip(t, files) @@ -3063,8 +3048,6 @@ func TestNormalizeArchive(t *testing.T) { require.ErrorContains(t, err, "readable zip archive") }) - // A small archive must not be allowed to expand into an unbounded amount - // of memory. t.Run("GzipBomb", func(t *testing.T) { t.Parallel() bomb := mustGzip(t, mustTar(t, map[string]string{ @@ -3077,8 +3060,7 @@ func TestNormalizeArchive(t *testing.T) { t.Run("ZipTooBig", func(t *testing.T) { t.Parallel() - // Pseudo-random, and so incompressible, contents: the zip itself has - // to exceed the limit for the size check to be the one that fails. + // Incompressible contents, so the zip itself exceeds the limit. big := make([]byte, provisionersdk.TemplateArchiveLimit) x := uint64(88172645463325252) for i := range big { @@ -3115,8 +3097,7 @@ func TestReadArchiveFile(t *testing.T) { require.Equal(t, zipped, payload) }) - // The extension is irrelevant: the format is detected from the contents, - // so a mislabelled archive still works. + // The format is detected from the contents, not the extension. t.Run("MislabelledExtension", func(t *testing.T) { t.Parallel() contentType, _, err := readArchiveFile(mustArchiveFile(t, "template.tar", mustZip(t, files))) @@ -3250,8 +3231,8 @@ resource "coderd_template" "test" { mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") require.NoError(t, err) - // The contents are interpolated into the test configuration as a string, so - // the template's own interpolations have to be escaped to survive it. + // The contents are interpolated into the test configuration, so the + // template's own interpolations have to be escaped. escapedMainTF := escapeTFInterpolation(string(mainTF)) resource.Test(t, resource.TestCase{ @@ -3259,8 +3240,8 @@ resource "coderd_template" "test" { IsUnitTest: true, ProtoV6ProviderFactories: testAccProtoV6ProviderFactories, Steps: []resource.TestStep{ - // The contents are provided inline, and `terraform.tfvars` is read - // as a variable value just like it is for a `directory`. + // Init. `terraform.tfvars` is read as a variable value, + // like it is for a `directory`. { Config: fmt.Sprintf(cfg, client.URL.String(), client.SessionToken(), "one", escapedMainTF), Check: resource.ComposeTestCheckFunc( @@ -3365,8 +3346,8 @@ resource "coderd_template" "test" { mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") require.NoError(t, err) files := map[string]string{"main.tf": string(mainTF)} - // A zip, since that's what the `archive_file` data source produces by - // default, and it exercises the server-side expansion. + // A zip, as produced by the `archive_file` data source, is expanded + // server-side. archive := mustArchiveFile(t, "template.zip", mustZip(t, files)) resource.Test(t, resource.TestCase{ @@ -3386,9 +3367,8 @@ resource "coderd_template" "test" { } // TestAccTemplateResourceVersionSourcePlan checks that a version whose contents -// come from `files`, `archive_base64`, or `archive_file` plans without error, -// end to end. It only plans, so a mock server is enough. The hash the plan -// modifier produces is asserted in TestVersionsPlanModifierContentHash. +// come from `files`, `archive_base64`, or `archive_file` plans without error. +// It only plans, so a mock server is enough. func TestAccTemplateResourceVersionSourcePlan(t *testing.T) { t.Parallel() if os.Getenv("TF_ACC") == "" { @@ -3414,9 +3394,7 @@ resource "coderd_template" "test" { ] }` - // The example template is used verbatim, since its interpolations are - // exactly what a `files` entry has to carry through to the provider - // untouched. + // The example template is used verbatim, interpolations included. mainTF, err := os.ReadFile("../../integration/template-test/example-template/main.tf") require.NoError(t, err) @@ -3438,8 +3416,8 @@ resource "coderd_template" "test" { { Config: fmt.Sprintf(cfg, srv.URL, source), PlanOnly: true, - // The resource doesn't exist yet, so the plan to - // create it is non-empty by definition. + // The resource doesn't exist yet, so the + // plan is non-empty. ExpectNonEmptyPlan: true, }, }, @@ -3449,9 +3427,7 @@ resource "coderd_template" "test" { } // TestVersionsPlanModifierContentHash checks that the plan modifier hashes a -// version's contents regardless of which source attribute they come from, -// since an unknown or incorrect hash would create a new template version on -// every plan. +// version's contents regardless of which source attribute they come from. func TestVersionsPlanModifierContentHash(t *testing.T) { t.Parallel() ctx := t.Context() diff --git a/internal/provider/util.go b/internal/provider/util.go index bb318469..07001e2c 100644 --- a/internal/provider/util.go +++ b/internal/provider/util.go @@ -88,9 +88,7 @@ func computeDirectoryHash(directory string) (string, error) { } // computeFilesHash hashes a map of relative path to file content, as provided -// by a template version's `files` attribute. Paths are sorted so the hash -// doesn't depend on map iteration order, and each path is hashed alongside its -// contents so that renaming a file produces a new hash. +// by a template version's `files` attribute. func computeFilesHash(files map[string]string) string { paths := make([]string, 0, len(files)) for path := range files {