fix: Adjusting lockfile handling when modules define constraints (#4514)

* fix: Addressing lint findings

* fix: Addressing test failures

* fix: Addressing lint failures

* fix: Fixing `TestParseProviderConstraintsWithEnvironmentOverride` test

* fix: Dropping log levels

* fix: Fixing `TestMockUpdateLockfile`

Author: yhakbar

internal/providercache/provider_cache.go

@@ -211,7 +211,40 @@ func (cache *ProviderCache) warmUpCache(
 		return nil, err
 	}
 
+	providerConstraints, err := getproviders.ParseProviderConstraints(opts, filepath.Dir(opts.TerragruntConfigPath))
+	if err != nil {
+		l.Debugf("Failed to parse provider constraints from %s: %v", filepath.Dir(opts.TerragruntConfigPath), err)
+
+		providerConstraints = make(getproviders.ProviderConstraints)
+	}
+
+	for _, provider := range caches {
+		if providerCache, ok := provider.(*services.ProviderCache); ok {
+			providerAddr := provider.Address()
+			if constraint, exists := providerConstraints[providerAddr]; exists {
+				providerCache.Provider.OriginalConstraints = constraint
+				l.Debugf("Applied constraint %s to provider %s", constraint, providerAddr)
+			} else {
+				l.Debugf("No constraint found for provider %s", providerAddr)
+			}
+		}
+	}
+
 	err = getproviders.UpdateLockfile(ctx, opts.WorkingDir, caches)
+	if err != nil {
+		return nil, err
+	}
+
+	// For upgrade scenarios where no providers were newly cached, we still need to update
+	// the lock file if module constraints have changed. This only happens during upgrades.
+	// Check if user passed -upgrade flag to terraform init
+	isUpgrade := util.ListContainsElement(opts.TerraformCliArgs, "-upgrade")
+
+	if len(caches) == 0 && len(providerConstraints) > 0 && isUpgrade {
+		l.Debugf("No new providers cached, but constraints exist. Updating lock file constraints for upgrade scenario.")
+
+		err = getproviders.UpdateLockfileConstraints(ctx, opts.WorkingDir, providerConstraints)
+	}
 
 	return nil, err
 }

test/fixtures/provider-cache/constraint-issue/app/main.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+    time = {
+      source  = "hashicorp/time"
+      version = ">= 0.10.0"
+    }
+  }
+}

test/fixtures/provider-cache/constraint-issue/app/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "."
+}

test/integration_provider_cache_constraint_test.go

@@ -0,0 +1,146 @@
+package test_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/gruntwork-io/terragrunt/test/helpers"
+	"github.com/gruntwork-io/terragrunt/util"
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/hcl/v2/hclwrite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	testFixtureProviderCacheConstraintIssue = "fixtures/provider-cache/constraint-issue"
+)
+
+// TestTerragruntProviderCacheConstraintIssue tests that provider cache preserves
+// module constraints instead of pinning exact versions in .terraform.lock.hcl files.
+// Reproduces and validates the fix for GitHub issue #4512.
+//
+//nolint:paralleltest,tparallel
+func TestTerragruntProviderCacheConstraintIssue(t *testing.T) {
+	t.Parallel()
+
+	helpers.CleanupTerraformFolder(t, testFixtureProviderCacheConstraintIssue)
+	tmpEnvPath := helpers.CopyEnvironment(t, testFixtureProviderCacheConstraintIssue)
+	rootPath := util.JoinPath(tmpEnvPath, testFixtureProviderCacheConstraintIssue)
+	appPath := filepath.Join(rootPath, "app")
+
+	providerCacheDir := t.TempDir()
+
+	t.Run("initial_setup_preserves_module_constraints", func(t *testing.T) {
+		helpers.RunTerragrunt(t, fmt.Sprintf("terragrunt init --provider-cache --provider-cache-dir %s --log-level trace --non-interactive --working-dir %s", providerCacheDir, appPath))
+
+		constraintsValue := extractConstraintsFromLockFile(t, appPath, "cloudflare/cloudflare")
+
+		expectedConstraints := "~> 4.0"
+		assert.Equal(t, expectedConstraints, constraintsValue, "Initial lock file should preserve module's required_providers constraints")
+	})
+
+	t.Run("upgrade_updates_constraints_to_match_module", func(t *testing.T) {
+		// Update the main.tf file to change cloudflare version constraint from "~> 4.0" to "~> 4.40"
+		mainTfPath := filepath.Join(appPath, "main.tf")
+		originalContent, err := os.ReadFile(mainTfPath)
+		require.NoError(t, err)
+
+		// Replace the version constraint
+		updatedContent := strings.ReplaceAll(string(originalContent), `version = "~> 4.0"`, `version = "~> 4.40"`)
+		require.NotEqual(t, string(originalContent), updatedContent, "Content should be different after replacement")
+
+		err = os.WriteFile(mainTfPath, []byte(updatedContent), 0644)
+		require.NoError(t, err)
+
+		lockFilePreInit, err := os.ReadFile(filepath.Join(appPath, ".terraform.lock.hcl"))
+		require.NoError(t, err)
+
+		// Run terragrunt init and check that the lock file isn't updated
+		helpers.RunTerragrunt(t, fmt.Sprintf("terragrunt init --provider-cache --provider-cache-dir %s --log-level trace --non-interactive --working-dir %s", providerCacheDir, appPath))
+		lockFilePostInit, err := os.ReadFile(filepath.Join(appPath, ".terraform.lock.hcl"))
+		require.NoError(t, err)
+		assert.Equal(t, string(lockFilePreInit), string(lockFilePostInit), "Lock file should not be updated")
+
+		// Run terragrunt init -upgrade to update the lock file
+		helpers.RunTerragrunt(t, fmt.Sprintf("terragrunt init -upgrade --provider-cache --provider-cache-dir %s --log-level trace --non-interactive --working-dir %s", providerCacheDir, appPath))
+
+		lockFilePostUpgrade, err := os.ReadFile(filepath.Join(appPath, ".terraform.lock.hcl"))
+		require.NoError(t, err)
+		assert.NotEqual(t, string(lockFilePostInit), string(lockFilePostUpgrade), "Lock file should be updated")
+
+		// Verify the lock file constraints are updated to match the module
+		constraintsValue := extractConstraintsFromLockFile(t, appPath, "cloudflare/cloudflare")
+
+		expectedConstraints := "~> 4.40"
+		assert.Equal(t, expectedConstraints, constraintsValue, "Constraints should be updated to match the module's required_providers")
+	})
+
+	t.Run("fresh_start_uses_module_constraints", func(t *testing.T) {
+		// Delete the lock file
+		lockfilePath := filepath.Join(appPath, ".terraform.lock.hcl")
+		err := os.Remove(lockfilePath)
+		require.NoError(t, err)
+
+		// Also clean up .terraform directory to ensure fresh start
+		terraformDir := filepath.Join(appPath, ".terraform")
+		if util.FileExists(terraformDir) {
+			err = os.RemoveAll(terraformDir)
+			require.NoError(t, err)
+		}
+
+		helpers.RunTerragrunt(t, fmt.Sprintf("terragrunt init --provider-cache --provider-cache-dir %s --log-level trace --non-interactive --working-dir %s", providerCacheDir, appPath))
+
+		constraintsValue := extractConstraintsFromLockFile(t, appPath, "cloudflare/cloudflare")
+
+		expectedConstraints := "~> 4.40"
+		assert.Equal(t, expectedConstraints, constraintsValue, "Fresh lock file should use module's required_providers constraints")
+	})
+}
+
+// Helper function to extract constraints value from lock file
+func extractConstraintsFromLockFile(t *testing.T, appPath string, providerName string) string {
+	t.Helper()
+
+	lockfilePath := filepath.Join(appPath, ".terraform.lock.hcl")
+	require.True(t, util.FileExists(lockfilePath), "Lock file should exist")
+
+	// Read and parse the lock file
+	lockfileContent, err := os.ReadFile(lockfilePath)
+	require.NoError(t, err)
+
+	lockfile, diags := hclwrite.ParseConfig(lockfileContent, lockfilePath, hcl.Pos{Line: 1, Column: 1})
+	require.False(t, diags.HasErrors(), "Lock file should be valid HCL")
+
+	// Find the provider block (handle both short and full provider names)
+	var providerBlock *hclwrite.Block
+	if strings.Contains(providerName, "/") {
+		// Full name like "cloudflare/cloudflare"
+		providerBlock = lockfile.Body().FirstMatchingBlock("provider", []string{"registry.terraform.io/" + providerName})
+		if providerBlock == nil {
+			// Try OpenTofu registry as well
+			providerBlock = lockfile.Body().FirstMatchingBlock("provider", []string{"registry.opentofu.org/" + providerName})
+		}
+	} else {
+		// Short name - search for matching block
+		for _, block := range lockfile.Body().Blocks() {
+			if block.Type() == "provider" && len(block.Labels()) > 0 {
+				if strings.Contains(block.Labels()[0], providerName) {
+					providerBlock = block
+					break
+				}
+			}
+		}
+	}
+	require.NotNil(t, providerBlock, "Provider block should exist in lock file")
+
+	// Get the constraints attribute
+	constraintsAttr := providerBlock.Body().GetAttribute("constraints")
+	require.NotNil(t, constraintsAttr, "Constraints attribute should exist")
+
+	constraintsValue := strings.Trim(string(constraintsAttr.Expr().BuildTokens(nil).Bytes()), ` "`)
+	return constraintsValue
+}

tf/cache/models/provider.go

@@ -108,6 +108,9 @@ type Provider struct {
 	Version      string
 	OS           string
 	Arch         string
+
+	// OriginalConstraints holds the version constraints from the module's required_providers block
+	OriginalConstraints string
 }
 
 func ParseProvider(str string) *Provider {
@@ -155,6 +158,10 @@ func (provider *Provider) Address() string {
 	return path.Join(provider.RegistryName, provider.Namespace, provider.Name)
 }
 
+func (provider *Provider) Constraints() string {
+	return provider.OriginalConstraints
+}
+
 // Match returns true if all defined provider properties are matched.
 func (provider *Provider) Match(target *Provider) bool {
 	registryNameMatch := provider.RegistryName == "" || target.RegistryName == "" || provider.RegistryName == target.RegistryName