fix: Escape interpolation in string inputs when type is verified

Author: yhakbar

docs/src/content/docs/04-reference/01-hcl/03-attributes.mdx

@@ -7,6 +7,7 @@ sidebar:
 ---
 
 import FileTree from '@components/vendored/starlight/FileTree.astro';
+import Since from '@components/Since.astro';
 
 Terragrunt HCL configuration uses [attributes](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md#attribute-definitions) when there are values that need to be defined for Terragrunt as a whole.
 
@@ -24,6 +25,15 @@ when crossing the boundary between Terragrunt and OpenTofu/Terraform. You must s
 constraint](https://opentofu.org/docs/language/values/variables/#type-constraints) on the variable in OpenTofu/Terraform in
 order for OpenTofu/Terraform to process the inputs as the right type.
 
+<Since version="v1.1.4">
+
+The type constraint also decides how the value is read. A variable declared as `string`, or declared with no type at
+all, receives the value verbatim. Every other type constraint makes OpenTofu/Terraform read the value as an HCL
+expression, where `${...}` means interpolation. Terragrunt escapes those sequences for you when the module reads a value
+as HCL, so text like `${just_a_string}` reaches the module as written.
+
+</Since>
+
 Example:
 
 ```hcl

docs/src/data/changelog/v1.1.4/string-inputs-with-interpolation.mdx

@@ -0,0 +1,16 @@
+---
+version: "v1.1.4"
+category: "bug-fixes"
+---
+
+#### String inputs reach modules with `${...}` intact
+
+Passing a string input that contains `${...}` to a variable declared with a type other than `string` used to fail with `Variables not allowed`, because OpenTofu/Terraform parse those values as HCL expressions and read `${...}` as an interpolation. Reading a JSON or YAML file into an input hit this whenever the file happened to contain that sequence:
+
+```hcl
+inputs = {
+  config = file("./config.json")
+}
+```
+
+Terragrunt now escapes interpolation sequences in string inputs when the module declares the variable with a type that makes the value parse as HCL, so `${...}` arrives as literal text instead of failing the run. Variables declared as `string`, and variables declared with no type at all, are read verbatim by OpenTofu/Terraform, and their values are still passed through untouched.

internal/cli/commands/hcl/validate/validate.go

@@ -410,13 +410,11 @@ func runValidateInputs(
 	opts *options.TerragruntOptions,
 	cfg *config.TerragruntConfig,
 ) error {
-	required, optional, err := tf.ModuleVariables(opts.WorkingDir)
+	declared, err := tf.ModuleVariables(v.FS, opts.WorkingDir)
 	if err != nil {
 		return err
 	}
 
-	allVars := slices.Concat(required, optional)
-
 	allInputs, err := getDefinedTerragruntInputs(l, v, opts, cfg)
 	if err != nil {
 		return err
@@ -426,16 +424,16 @@ func runValidateInputs(
 	unusedVars := []string{}
 
 	for _, varName := range allInputs {
-		if !slices.Contains(allVars, varName) {
+		if _, ok := declared[varName]; !ok {
 			unusedVars = append(unusedVars, varName)
 		}
 	}
 
 	// Missing variables are those that are required by the terraform config, but not defined in terragrunt.
 	missingVars := []string{}
 
-	for _, varName := range required {
-		if !slices.Contains(allInputs, varName) {
+	for _, varName := range slices.Sorted(maps.Keys(declared)) {
+		if !declared[varName].HasDefault && !slices.Contains(allInputs, varName) {
 			missingVars = append(missingVars, varName)
 		}
 	}

internal/prepare/prepare.go

@@ -217,7 +217,7 @@ func PrepareInputsAsEnvVars(
 		return err
 	}
 
-	return run.SetTerragruntInputsAsEnvVars(l, v.Env, cfg)
+	return run.SetTerragruntInputsAsEnvVars(l, v.FS, v.Env, runOpts.CacheDir, cfg)
 }
 
 // PrepareInit runs terraform init if needed. This is the final preparation stage.
@@ -237,7 +237,7 @@ func PrepareInit(
 		return err
 	}
 
-	if err := run.SetTerragruntInputsAsEnvVars(l, v.Env, cfg); err != nil {
+	if err := run.SetTerragruntInputsAsEnvVars(l, v.FS, v.Env, runOpts.CacheDir, cfg); err != nil {
 		return err
 	}
 

internal/runner/run/debug.go

@@ -3,13 +3,15 @@ package run
 import (
 	"encoding/json"
 	"fmt"
+	"maps"
 	"os"
 	"path/filepath"
 	"slices"
 	"strings"
 
 	"github.com/gruntwork-io/terragrunt/internal/runner/runcfg"
 	"github.com/gruntwork-io/terragrunt/internal/tf"
+	"github.com/gruntwork-io/terragrunt/internal/vfs"
 	"github.com/gruntwork-io/terragrunt/pkg/log"
 )
 
@@ -21,6 +23,7 @@ const defaultPermissions = int(0600)
 // that terragrunt invokes the module, so that users can debug issues with the terragrunt config.
 func WriteTerragruntDebugFile(
 	l log.Logger,
+	fsys vfs.FS,
 	env map[string]string,
 	opts *Options,
 	cfg *runcfg.RunConfig,
@@ -31,12 +34,12 @@ func WriteTerragruntDebugFile(
 		opts.CacheDir,
 	)
 
-	required, optional, err := tf.ModuleVariables(opts.CacheDir)
+	declared, err := tf.ModuleVariables(fsys, opts.CacheDir)
 	if err != nil {
 		return err
 	}
 
-	variables := slices.Concat(required, optional)
+	variables := slices.Sorted(maps.Keys(declared))
 
 	tofuImpl := "tofu"
 	if opts.TofuImplementation != "" {

internal/runner/run/run.go

@@ -192,7 +192,7 @@ func Run(
 	// We do the debug file generation here, after all the terragrunt generated terraform files are created so that we
 	// can ensure the tfvars json file only includes the vars that are defined in the module.
 	if updatedOpts.Debug {
-		if err := WriteTerragruntDebugFile(l, v.Env, updatedOpts, cfg); err != nil {
+		if err := WriteTerragruntDebugFile(l, v.FS, v.Env, updatedOpts, cfg); err != nil {
 			return err
 		}
 	}
@@ -309,7 +309,7 @@ func runTerragruntWithConfig(
 		maps.Copy(v.Env, extraEnvVars)
 	}
 
-	if err := SetTerragruntInputsAsEnvVars(l, v.Env, cfg); err != nil {
+	if err := SetTerragruntInputsAsEnvVars(l, v.FS, v.Env, opts.CacheDir, cfg); err != nil {
 		return err
 	}
 
@@ -495,14 +495,20 @@ func RunActionWithHooks(
 // Requires a non-nil env: it is the destination the entries are written into.
 func SetTerragruntInputsAsEnvVars(
 	l log.Logger,
+	fsys vfs.FS,
 	env map[string]string,
+	modulePath string,
 	cfg *runcfg.RunConfig,
 ) error {
 	if env == nil {
 		panic(venv.ErrVenvEnvUnset)
 	}
 
-	asEnvVars, err := ToTerraformEnvVars(l, cfg.Inputs)
+	asEnvVars, err := ToTerraformEnvVars(
+		l,
+		cfg.Inputs,
+		declaredVariables(l, fsys, modulePath, cfg.Inputs),
+	)
 	if err != nil {
 		return err
 	}
@@ -708,7 +714,15 @@ func FilterTerraformExtraArgs(l log.Logger, fsys vfs.FS, opts *Options, cfg *run
 // ToTerraformEnvVars converts the given variables to a map of environment variables that will expose those variables to Terraform. The
 // keys will be of the format TF_VAR_xxx and the values will be converted to JSON, which Terraform knows how to read
 // natively.
-func ToTerraformEnvVars(l log.Logger, vars map[string]any) (map[string]string, error) {
+//
+// A string value only has its interpolation sequences escaped when the module declares the matching
+// variable with a type constraint that makes OpenTofu/Terraform parse the value as HCL. Escaping a
+// value that is read literally would deliver $${...} to the module instead of ${...}.
+func ToTerraformEnvVars(
+	l log.Logger,
+	vars map[string]any,
+	declared map[string]tf.ModuleVariable,
+) (map[string]string, error) {
 	out := map[string]string{}
 
 	for varName, varValue := range vars {
@@ -718,6 +732,10 @@ func ToTerraformEnvVars(l log.Logger, vars map[string]any) (map[string]string, e
 
 		envVarName := fmt.Sprintf(tf.EnvNameTFVarFmt, varName)
 
+		if str, ok := varValue.(string); ok && declared[varName].ParsingMode == tf.VariableParseHCL {
+			varValue = util.EscapeInterpolationInString(str)
+		}
+
 		envVarValue, err := util.AsTerraformEnvVarJSONValue(varValue)
 		if err != nil {
 			return nil, err
@@ -729,6 +747,41 @@ func ToTerraformEnvVars(l log.Logger, vars map[string]any) (map[string]string, e
 	return out, nil
 }
 
+// declaredVariables reads how the module at modulePath declared its variables, so that only the
+// values OpenTofu/Terraform parse as HCL get escaped.
+//
+// Reading the module is skipped unless an input actually carries an interpolation sequence, and a
+// module that cannot be read yields no declarations at all: values are then passed through
+// untouched, and OpenTofu/Terraform report the malformed module themselves.
+func declaredVariables(
+	l log.Logger,
+	fsys vfs.FS,
+	modulePath string,
+	inputs map[string]any,
+) map[string]tf.ModuleVariable {
+	needsDeclarations := false
+
+	for _, value := range inputs {
+		if str, ok := value.(string); ok && strings.Contains(str, "${") {
+			needsDeclarations = true
+			break
+		}
+	}
+
+	if !needsDeclarations {
+		return nil
+	}
+
+	declared, err := tf.ModuleVariables(fsys, modulePath)
+	if err != nil {
+		l.Debugf("Failed to read variable declarations in %s: %v", modulePath, err)
+
+		return nil
+	}
+
+	return declared
+}
+
 // filterTerraformEnvVarsFromExtraArgsRunCfg extracts terraform env vars from extra args using runcfg types.
 func filterTerraformEnvVarsFromExtraArgsRunCfg(
 	opts *Options,

internal/runner/run/run_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/gruntwork-io/terragrunt/internal/iacargs"
 	"github.com/gruntwork-io/terragrunt/internal/runner/run"
 	"github.com/gruntwork-io/terragrunt/internal/runner/runcfg"
+	"github.com/gruntwork-io/terragrunt/internal/tf"
 	"github.com/gruntwork-io/terragrunt/internal/util"
 	"github.com/gruntwork-io/terragrunt/internal/vfs"
 	"github.com/gruntwork-io/terragrunt/pkg/log"
@@ -26,6 +27,7 @@ func TestSetTerragruntInputsAsEnvVars(t *testing.T) {
 	testCases := []struct {
 		envVarsInOpts  map[string]string
 		inputsInConfig map[string]any
+		moduleFiles    map[string]string
 		expected       map[string]string
 		description    string
 	}{
@@ -96,6 +98,30 @@ func TestSetTerragruntInputsAsEnvVars(t *testing.T) {
 				"TF_VAR_map":  `{"a":"b"}`,
 			},
 		},
+		{
+			description:    "input with an interpolation pattern for a string variable",
+			inputsInConfig: map[string]any{"foo": `{"a": "${b}"}`},
+			moduleFiles:    map[string]string{"main.tf": `variable "foo" { type = string }`},
+			expected:       map[string]string{"TF_VAR_foo": `{"a": "${b}"}`},
+		},
+		{
+			description:    "input with an interpolation pattern for an untyped variable",
+			inputsInConfig: map[string]any{"foo": `{"a": "${b}"}`},
+			moduleFiles:    map[string]string{"main.tf": `variable "foo" {}`},
+			expected:       map[string]string{"TF_VAR_foo": `{"a": "${b}"}`},
+		},
+		{
+			description:    "input with an interpolation pattern for a variable of any type",
+			inputsInConfig: map[string]any{"foo": `{"a": "${b}"}`},
+			moduleFiles:    map[string]string{"main.tf": `variable "foo" { type = any }`},
+			expected:       map[string]string{"TF_VAR_foo": `{"a": "$${b}"}`},
+		},
+		{
+			description:    "input with an interpolation pattern for an unparseable module",
+			inputsInConfig: map[string]any{"foo": `{"a": "${b}"}`},
+			moduleFiles:    map[string]string{"main.tf": `variable "foo" {`},
+			expected:       map[string]string{"TF_VAR_foo": `{"a": "${b}"}`},
+		},
 	}
 
 	for _, tc := range testCases {
@@ -111,8 +137,18 @@ func TestSetTerragruntInputsAsEnvVars(t *testing.T) {
 				env = map[string]string{}
 			}
 
+			fsys := vfs.NewMemMapFS()
+			moduleDir := "/module"
+
+			require.NoError(t, fsys.MkdirAll(moduleDir, 0755))
+
+			for filename, content := range tc.moduleFiles {
+				path := filepath.Join(moduleDir, filename)
+				require.NoError(t, vfs.WriteFile(fsys, path, []byte(content), 0644))
+			}
+
 			l := logger.CreateLogger()
-			require.NoError(t, run.SetTerragruntInputsAsEnvVars(l, env, cfg))
+			require.NoError(t, run.SetTerragruntInputsAsEnvVars(l, fsys, env, moduleDir, cfg))
 
 			assert.Equal(t, tc.expected, env)
 		})
@@ -223,6 +259,7 @@ func TestToTerraformEnvVars(t *testing.T) {
 
 	testCases := []struct {
 		vars        map[string]any
+		declared    map[string]tf.ModuleVariable
 		expected    map[string]string
 		description string
 	}{
@@ -286,8 +323,26 @@ func TestToTerraformEnvVars(t *testing.T) {
 			expected:    map[string]string{"TF_VAR_stuff": `{"foo":"test $${bar} test"}`},
 		},
 		{
-			description: "plain string with interpolation pattern not escaped",
+			description: "string with interpolation pattern for a literally read variable",
+			vars:        map[string]any{"mystr": "plain ${bar} string"},
+			expected:    map[string]string{"TF_VAR_mystr": `plain ${bar} string`},
+		},
+		{
+			description: "string with interpolation pattern for an HCL parsed variable",
+			vars:        map[string]any{"mystr": "plain ${bar} string"},
+			declared:    map[string]tf.ModuleVariable{"mystr": {ParsingMode: tf.VariableParseHCL}},
+			expected:    map[string]string{"TF_VAR_mystr": `plain $${bar} string`},
+		},
+		{
+			description: "already escaped string for an HCL parsed variable",
+			vars:        map[string]any{"mystr": "plain $${bar} string"},
+			declared:    map[string]tf.ModuleVariable{"mystr": {ParsingMode: tf.VariableParseHCL}},
+			expected:    map[string]string{"TF_VAR_mystr": `plain $${bar} string`},
+		},
+		{
+			description: "declarations of other variables leave a string alone",
 			vars:        map[string]any{"mystr": "plain ${bar} string"},
+			declared:    map[string]tf.ModuleVariable{"other": {ParsingMode: tf.VariableParseHCL}},
 			expected:    map[string]string{"TF_VAR_mystr": `plain ${bar} string`},
 		},
 		{
@@ -302,7 +357,7 @@ func TestToTerraformEnvVars(t *testing.T) {
 			t.Parallel()
 
 			l := logger.CreateLogger()
-			actual, err := run.ToTerraformEnvVars(l, tc.vars)
+			actual, err := run.ToTerraformEnvVars(l, tc.vars, tc.declared)
 			require.NoError(t, err)
 			assert.Equal(t, tc.expected, actual)
 		})