chore: add template toggle to disable module caching by Emyrk · Pull Request #21931

chore: add template toggle to disable module caching by Emyrk · Pull Request #21931 · coder/coder

There exists use cases to disable the new module caching behavior of workspace builds. This was the legacy behavior.

		@@ -0,0 +1,16 @@
		DROP VIEW template_with_names;
		ALTER TABLE templates ADD COLUMN disable_module_cache BOOL NOT NULL DEFAULT false;

Choose a reason for hiding this comment

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

Make users opt into the legacy behavior.

Choose a reason for hiding this comment

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

TBH I prefer having configuration flags being positive as opposed to negative, so enable_module_cache with default true would be my suggestion. Not a blocker though.

Documentation Check

New Documentation Needed

This PR adds a new template setting that allows disabling Terraform module caching. Documentation should be added to help template admins understand when and why to use this feature.

Update docs/admin/templates/managing-templates/dependencies.md - Add a section explaining the new disable_module_cache template setting
- Explain that Coder caches Terraform modules by default for performance (already documented)
- Document the new toggle available in template settings
- Explain when to disable module caching (e.g., for debugging, testing new module versions, or when module behavior needs to change frequently)
- Note that disabling caching will impact build performance and require downloading modules on every build
- Show where to find this setting in the UI (Template Settings > General)
Consider adding to docs/admin/templates/troubleshooting.md - Add troubleshooting guidance
- Add a troubleshooting entry about module caching issues
- Recommend trying the "Disable module cache" setting if workspace builds are using stale module versions
- Link back to the dependencies.md documentation

Why Documentation is Needed

New feature: This is a new template-level configuration option that template admins need to know about
Performance impact: Disabling module caching has performance implications that should be clearly documented
Use cases: The PR description mentions "use cases to disable the new module caching behavior" but doesn't specify what those are - docs should clarify
Discovery: Users need to know this option exists when troubleshooting module-related issues
Connection to existing docs: The existing dependencies.md page discusses module caching benefits but doesn't mention how to disable it if needed

Automated review via Coder Tasks

		@@ -0,0 +1,16 @@
		DROP VIEW template_with_names;
		ALTER TABLE templates ADD COLUMN disable_module_cache BOOL NOT NULL DEFAULT false;

Choose a reason for hiding this comment

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

TBH I prefer having configuration flags being positive as opposed to negative, so enable_module_cache with default true would be my suggestion. Not a blocker though.

		}
		if err == nil && tfvals.CachedModuleFiles.Valid {
		versionModulesFile = tfvals.CachedModuleFiles.UUID.String()
		if !template.DisableModuleCache {

Choose a reason for hiding this comment

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

This is what I mean, the other way round it would be

if template.EnableModuleCache { ... }

Aside, the below comment is also a bit confusing as it implies that the logic is related to DisableModuleCache being true?

Choose a reason for hiding this comment

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

I will delete that comment, it provides no help.

I do agree the inversion is not great. But I like that the zero value in golang is the correct default

TBH I prefer having configuration flags being positive as opposed to negative, so enable_module_cache with default true would be my suggestion. Not a blocker though.

I agree, but I also want the Golang zero value to be the default

Choose a reason for hiding this comment

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

I'm OK with this change, besides the things I've already mentioned.
(Also, the unrelated golden file changes)

Comment on lines 27 to 34

		"id": "eb9b7f18-c277-48af-af7c-2a8e5fb42bab"
		},
		{
		"workspace_folder": "/workspace2",
		"config_path": "/workspace2/.devcontainer/devcontainer.json",
		"name": "dev2",
		"id": "964430ff-f0d9-4fcb-b645-6333cf6ba9f2",
		"subagent_id": "40a59d56-d3df-488f-b07d-331c0b774bac"
		"id": "964430ff-f0d9-4fcb-b645-6333cf6ba9f2"
		}

Choose a reason for hiding this comment

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

not part of this change

Choose a reason for hiding this comment

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

I don't know what is going on. Fresh workspace, git clean -xfd, make gen -B 🤔

Documentation Check

Updates Needed

docs/tutorials/best-practices/speed-up-templates.md - Add section explaining the disable_module_cache template setting and when to use it. The current "Set up Terraform provider caching" section discusses provider caching but not module caching behavior. Should explain:
- Default behavior: modules are cached at template import (introduced in chore!: send modules archive over the proto messages #21398)
- How to opt out per-template using the new disable_module_cache setting
- Trade-offs: performance vs always fetching latest unpinned modules
- Link to template settings page for configuration
docs/admin/templates/extending-templates/modules.md - Add note about module caching behavior:
- Explain that modules are cached by default during template import/update
- Mention the disable_module_cache template setting as an opt-out
- Clarify that this affects how often modules are re-downloaded from registries/git

Context

This PR adds a disable_module_cache boolean field to templates (defaults to false). It allows templates to opt out of the module caching behavior introduced in PR #21398, which caches Terraform modules at template import time to speed up workspace builds.

The API documentation and audit logs are already updated in this PR. User-facing documentation should explain:

What module caching is and why it improves performance
The behavior change from chore!: send modules archive over the proto messages #21398 (modules cached at import vs downloaded per build)
How to configure the setting via the template settings UI
When you might want to disable it (e.g., development workflows needing latest module versions)

Automated review via Coder Tasks

Documentation Check

I'm not going to document a feature I don't want people to use. The warning label in the product is enough imo.

How I tell the tasks bot "No"?

The chromatic failures are unrelated to my change

@Emyrk I'm not going to document a feature I don't want people to use. The warning label in the product is enough imo.

I think you can just ignore it?

@Emyrk I'm not going to document a feature I don't want people to use. The warning label in the product is enough imo.

I think you can just ignore it?

Ah, it is not required. I'm merging in spite of docs and chromatic

Emyrk deleted the stevenmasley/opt_in_fast_workspaces branch

February 5, 2026 20:38