Sep 30, 2025 · Oct 1, 2025
diff --git a/docs/tutorials/best-practices/speed-up-templates.md b/docs/tutorials/best-practices/speed-up-templates.md

 ### Cache directory

 Coder will instruct Terraform to cache its downloaded providers in the
 configured [`CODER_CACHE_DIRECTORY`](../../reference/cli/server.md#--cache-dir)
 directory.
 Coder will instruct Terraform to cache its downloaded providers in the configured [`CODER_CACHE_DIRECTORY`](../../reference/cli/server.md#--cache-dir) directory.

 Ensure that this directory is set to a location on disk which will persist
 across restarts of Coder or
 [external provisioners](../../admin/provisioners/index.md), if you're using them.
 Ensure that this directory is set to a location on disk which will persist across restarts of Coder or [external provisioners](../../admin/provisioners/index.md), if you're using them.

 #### Cache cleanup configuration

 Provisioner cache cleanup can be controlled at runtime via environment variables (on both built-in and external provisioners):

 - `CODER_PROVISIONER_CACHE_CLEANUP` (default `true`): enable or disable cleanup.
 - `CODER_PROVISIONER_CACHE_RETENTION` (default `720h`): age threshold for considering a cached provider stale, parsed with Go's `time.ParseDuration` (example: `720h` ~30 days).

 If unset, cleanup runs with a default 30-day retention.
diff --git a/provisioner/terraform/provision.go b/provisioner/terraform/provision.go
 "github.com/coder/coder/v2/provisionersdk/proto"
 )

 const staleTerraformPluginRetention = 30 * 24 * time.Hour
 var staleTerraformPluginRetention = 30 * 24 * time.Hour

 // terraformPluginCleanupEnabled controls whether plugin cache cleanup runs.
 // Defaults to true.
 var terraformPluginCleanupEnabled = true

 func (s *server) setupContexts(parent context.Context, canceledOrComplete <-chan struct{}) (
 ctx context.Context, cancel func(), killCtx context.Context, kill func(),
 }
 }

 err := CleanStaleTerraformPlugins(sess.Context(), s.cachePath, afero.NewOsFs(), time.Now(), s.logger)
 if err != nil {
 return provisionersdk.PlanErrorf("unable to clean stale Terraform plugins: %s", err)
 if terraformPluginCleanupEnabled {
 err := CleanStaleTerraformPlugins(sess.Context(), s.cachePath, afero.NewOsFs(), time.Now(), s.logger)
 if err != nil {
 return provisionersdk.PlanErrorf("unable to clean stale Terraform plugins: %s", err)
 }
 }

 s.logger.Debug(ctx, "running initialization")
 initTimings := newTimingAggregator(database.ProvisionerJobTimingStageInit)
 initTimings.ingest(createInitTimingsEvent(timingInitStart))

 var err error
 err = e.init(ctx, killCtx, sess)
 if err != nil {
 initTimings.ingest(createInitTimingsEvent(timingInitErrored))
diff --git a/provisioner/terraform/serve.go b/provisioner/terraform/serve.go
 import (
 "context"
 "errors"
 "os"
 "path/filepath"
 "strconv"
 "strings"
 "sync"
 "time"


 // Serve starts a dRPC server on the provided transport speaking Terraform provisioner.
 func Serve(ctx context.Context, options *ServeOptions) error {
 // Optional environment overrides for plugin cache cleanup behavior.
 if v, ok := os.LookupEnv("CODER_PROVISIONER_CACHE_CLEANUP"); ok {
 if b, err := strconv.ParseBool(strings.TrimSpace(v)); err == nil {
 terraformPluginCleanupEnabled = b
 }
 }
 if v, ok := os.LookupEnv("CODER_PROVISIONER_CACHE_RETENTION"); ok {
 if d, err := time.ParseDuration(strings.TrimSpace(v)); err == nil {
 staleTerraformPluginRetention = d
 }
 }
 if options.BinaryPath == "" {
 binaryDetails, err := systemBinary(ctx)
 if err != nil {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -159,10 +159,15 @@ provider versions.

		### Cache directory

		Coder will instruct Terraform to cache its downloaded providers in the
		configured [`CODER_CACHE_DIRECTORY`](../../reference/cli/server.md#--cache-dir)
		directory.
		Coder will instruct Terraform to cache its downloaded providers in the configured [`CODER_CACHE_DIRECTORY`](../../reference/cli/server.md#--cache-dir) directory.

		Ensure that this directory is set to a location on disk which will persist
		across restarts of Coder or
		[external provisioners](../../admin/provisioners/index.md), if you're using them.
		Ensure that this directory is set to a location on disk which will persist across restarts of Coder or [external provisioners](../../admin/provisioners/index.md), if you're using them.

		#### Cache cleanup configuration

		Provisioner cache cleanup can be controlled at runtime via environment variables (on both built-in and external provisioners):

		- `CODER_PROVISIONER_CACHE_CLEANUP` (default `true`): enable or disable cleanup.
		- `CODER_PROVISIONER_CACHE_RETENTION` (default `720h`): age threshold for considering a cached provider stale, parsed with Go's `time.ParseDuration` (example: `720h` ~30 days).

		If unset, cleanup runs with a default 30-day retention.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,7 +24,11 @@ import (
		"github.com/coder/coder/v2/provisionersdk/proto"
		)

		const staleTerraformPluginRetention = 30 * 24 * time.Hour
		var staleTerraformPluginRetention = 30 * 24 * time.Hour

		// terraformPluginCleanupEnabled controls whether plugin cache cleanup runs.
		// Defaults to true.
		var terraformPluginCleanupEnabled = true

		func (s *server) setupContexts(parent context.Context, canceledOrComplete <-chan struct{}) (
		ctx context.Context, cancel func(), killCtx context.Context, kill func(),
Expand DownExpand Up		@@ -100,9 +104,11 @@ func (s *server) Plan(
		}
		}

		err := CleanStaleTerraformPlugins(sess.Context(), s.cachePath, afero.NewOsFs(), time.Now(), s.logger)
		if err != nil {
		return provisionersdk.PlanErrorf("unable to clean stale Terraform plugins: %s", err)
		if terraformPluginCleanupEnabled {
		err := CleanStaleTerraformPlugins(sess.Context(), s.cachePath, afero.NewOsFs(), time.Now(), s.logger)
		if err != nil {
		return provisionersdk.PlanErrorf("unable to clean stale Terraform plugins: %s", err)
		}
		}

		s.logger.Debug(ctx, "running initialization")
Expand All		@@ -112,6 +118,7 @@ func (s *server) Plan(
		initTimings := newTimingAggregator(database.ProvisionerJobTimingStageInit)
		initTimings.ingest(createInitTimingsEvent(timingInitStart))

		var err error
		err = e.init(ctx, killCtx, sess)
		if err != nil {
		initTimings.ingest(createInitTimingsEvent(timingInitErrored))
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,7 +3,10 @@ package terraform
		import (
		"context"
		"errors"
		"os"
		"path/filepath"
		"strconv"
		"strings"
		"sync"
		"time"

Expand DownExpand Up		@@ -86,6 +89,17 @@ func systemBinary(ctx context.Context) (*systemBinaryDetails, error) {

		// Serve starts a dRPC server on the provided transport speaking Terraform provisioner.
		func Serve(ctx context.Context, options *ServeOptions) error {
		// Optional environment overrides for plugin cache cleanup behavior.
		if v, ok := os.LookupEnv("CODER_PROVISIONER_CACHE_CLEANUP"); ok {
		if b, err := strconv.ParseBool(strings.TrimSpace(v)); err == nil {
		terraformPluginCleanupEnabled = b
		}
		}
		if v, ok := os.LookupEnv("CODER_PROVISIONER_CACHE_RETENTION"); ok {
		if d, err := time.ParseDuration(strings.TrimSpace(v)); err == nil {
		staleTerraformPluginRetention = d
		}
		}
		if options.BinaryPath == "" {
		binaryDetails, err := systemBinary(ctx)
		if err != nil {
Expand Down