variable and output deprecation

Variables can be deprecated through the `deprecated` attribute. If set the variable
will emit a diagnostic if a values is passed to it. This entails both root level and
module variables.

Outputs can be deprecated through the `deprecated` attribute as well. If set wherever
the value is used a diagnostic will be emitted. Root level outputs can not be deprecated.
The only acceptable usage of a deprecated output is another deprecated output (forwarding
the deprecation to the module user).

If modules not under your control have deprecation warnings you can add a `suppress_deprecations_warnigns`
attribute to the module call in question to silence any deeply nested warnings.

Author: DanielMSchmidt

.changes/v1.15/NEW FEATURES-20251205-171418.yaml

@@ -0,0 +1,5 @@
+kind: NEW FEATURES
+body: You can set a `deprecated` attribute on variable and output blocks to indicate that they are deprecated. This will produce warnings when passing in a value for a deprecated variable or when referencing a deprecated output.
+time: 2025-12-05T17:14:18.623477+01:00
+custom:
+    Issue: "37795"

internal/addrs/check.go

@@ -106,6 +106,11 @@ func (c AbsCheck) CheckRule(typ CheckRuleType, i int) CheckRule {
 	}
 }
 
+// ModuleInstance returns the module instance portion of the address.
+func (c AbsCheck) ModuleInstance() ModuleInstance {
+	return c.Module
+}
+
 // ConfigCheckable returns the ConfigCheck address for this absolute reference.
 func (c AbsCheck) ConfigCheckable() ConfigCheckable {
 	return ConfigCheck{

internal/addrs/check_rule.go

@@ -115,3 +115,8 @@ func (c CheckRuleType) Description() string {
 		return "Condition"
 	}
 }
+
+// ModuleInstance returns the module instance address containing this check rule.
+func (c CheckRule) ModuleInstance() ModuleInstance {
+	return c.Container.ModuleInstance()
+}

internal/addrs/checkable.go

@@ -39,6 +39,7 @@ type Checkable interface {
 
 	CheckableKind() CheckableKind
 	String() string
+	ModuleInstance() ModuleInstance
 }
 
 var (

internal/addrs/input_variable.go

@@ -81,6 +81,11 @@ func (v AbsInputVariableInstance) CheckRule(typ CheckRuleType, i int) CheckRule
 	}
 }
 
+// ModuleInstance returns the module instance portion of the address.
+func (v AbsInputVariableInstance) ModuleInstance() ModuleInstance {
+	return v.Module
+}
+
 func (v AbsInputVariableInstance) ConfigCheckable() ConfigCheckable {
 	return ConfigInputVariable{
 		Module:   v.Module.Module(),

internal/addrs/output_value.go

@@ -77,6 +77,11 @@ func (m ModuleInstance) OutputValue(name string) AbsOutputValue {
 	}
 }
 
+// ModuleInstance returns the module instance portion of the address.
+func (v AbsOutputValue) ModuleInstance() ModuleInstance {
+	return v.Module
+}
+
 func (v AbsOutputValue) CheckRule(t CheckRuleType, i int) CheckRule {
 	return CheckRule{
 		Container: v,

internal/addrs/resource.go

@@ -280,6 +280,11 @@ func (m ModuleInstance) ResourceInstance(mode ResourceMode, typeName string, nam
 	}
 }
 
+// ModuleInstance returns the module instance portion of the address.
+func (r AbsResourceInstance) ModuleInstance() ModuleInstance {
+	return r.Module
+}
+
 // ContainingResource returns the address of the resource that contains the
 // receving resource instance. In other words, it discards the key portion
 // of the address to produce an AbsResource value.

internal/configs/module_call.go

@@ -9,6 +9,7 @@ import (
 	"github.com/hashicorp/hcl/v2"
 	"github.com/hashicorp/hcl/v2/gohcl"
 	"github.com/hashicorp/hcl/v2/hclsyntax"
+	"github.com/zclconf/go-cty/cty"
 
 	"github.com/hashicorp/terraform/internal/addrs"
 	"github.com/hashicorp/terraform/internal/getmodules/moduleaddrs"
@@ -35,6 +36,8 @@ type ModuleCall struct {
 	DependsOn []hcl.Traversal
 
 	DeclRange hcl.Range
+
+	IgnoreNestedDeprecations bool
 }
 
 func decodeModuleBlock(block *hcl.Block, override bool) (*ModuleCall, hcl.Diagnostics) {
@@ -163,6 +166,30 @@ func decodeModuleBlock(block *hcl.Block, override bool) (*ModuleCall, hcl.Diagno
 		mc.Providers = append(mc.Providers, providers...)
 	}
 
+	if attr, exists := content.Attributes["ignore_nested_deprecations"]; exists {
+		// We only allow static boolean values for this argument.
+		val, evalDiags := attr.Expr.Value(&hcl.EvalContext{})
+		if len(evalDiags.Errs()) > 0 {
+			diags = append(diags, &hcl.Diagnostic{
+				Severity: hcl.DiagError,
+				Summary:  "Invalid value for ignore_nested_deprecations",
+				Detail:   "The value for ignore_nested_deprecations must be a static boolean (true or false).",
+				Subject:  attr.Expr.Range().Ptr(),
+			})
+		}
+
+		if val.Type() != cty.Bool {
+			diags = append(diags, &hcl.Diagnostic{
+				Severity: hcl.DiagError,
+				Summary:  "Invalid type for ignore_nested_deprecations",
+				Detail:   fmt.Sprintf("The value for ignore_nested_deprecations must be a boolean (true or false), but the given value has type %s.", val.Type().FriendlyName()),
+				Subject:  attr.Expr.Range().Ptr(),
+			})
+		}
+
+		mc.IgnoreNestedDeprecations = val.True()
+	}
+
 	var seenEscapeBlock *hcl.Block
 	for _, block := range content.Blocks {
 		switch block.Type {
@@ -278,6 +305,9 @@ var moduleBlockSchema = &hcl.BodySchema{
 		{
 			Name: "providers",
 		},
+		{
+			Name: "ignore_nested_deprecations",
+		},
 	},
 	Blocks: []hcl.BlockHeaderSchema{
 		{Type: "_"}, // meta-argument escaping block

internal/configs/named_values.go

@@ -48,6 +48,10 @@ type Variable struct {
 	Nullable    bool
 	NullableSet bool
 
+	Deprecated      string
+	DeprecatedSet   bool
+	DeprecatedRange hcl.Range
+
 	DeclRange hcl.Range
 }
 
@@ -186,6 +190,13 @@ func decodeVariableBlock(block *hcl.Block, override bool) (*Variable, hcl.Diagno
 		v.Default = val
 	}
 
+	if attr, exists := content.Attributes["deprecated"]; exists {
+		valDiags := gohcl.DecodeExpression(attr.Expr, nil, &v.Deprecated)
+		diags = append(diags, valDiags...)
+		v.DeprecatedSet = true
+		v.DeprecatedRange = attr.Range
+	}
+
 	for _, block := range content.Blocks {
 		switch block.Type {
 
@@ -345,14 +356,17 @@ type Output struct {
 	DependsOn   []hcl.Traversal
 	Sensitive   bool
 	Ephemeral   bool
+	Deprecated  string
 
 	Preconditions []*CheckRule
 
 	DescriptionSet bool
 	SensitiveSet   bool
 	EphemeralSet   bool
+	DeprecatedSet  bool
 
-	DeclRange hcl.Range
+	DeclRange       hcl.Range
+	DeprecatedRange hcl.Range
 }
 
 func decodeOutputBlock(block *hcl.Block, override bool) (*Output, hcl.Diagnostics) {
@@ -402,6 +416,13 @@ func decodeOutputBlock(block *hcl.Block, override bool) (*Output, hcl.Diagnostic
 		o.EphemeralSet = true
 	}
 
+	if attr, exists := content.Attributes["deprecated"]; exists {
+		valDiags := gohcl.DecodeExpression(attr.Expr, nil, &o.Deprecated)
+		diags = append(diags, valDiags...)
+		o.DeprecatedSet = true
+		o.DeprecatedRange = attr.Range
+	}
+
 	if attr, exists := content.Attributes["depends_on"]; exists {
 		deps, depsDiags := DecodeDependsOn(attr)
 		diags = append(diags, depsDiags...)
@@ -441,6 +462,7 @@ func (o *Output) Addr() addrs.OutputValue {
 type Local struct {
 	Name string
 	Expr hcl.Expression
+	Body hcl.Body // for better diagnostics
 
 	DeclRange hcl.Range
 }
@@ -466,6 +488,7 @@ func decodeLocalsBlock(block *hcl.Block) ([]*Local, hcl.Diagnostics) {
 			Name:      name,
 			Expr:      attr.Expr,
 			DeclRange: attr.Range,
+			Body:      block.Body,
 		})
 	}
 	return locals, diags
@@ -499,6 +522,9 @@ var variableBlockSchema = &hcl.BodySchema{
 		{
 			Name: "nullable",
 		},
+		{
+			Name: "deprecated",
+		},
 	},
 	Blocks: []hcl.BlockHeaderSchema{
 		{
@@ -525,6 +551,9 @@ var outputBlockSchema = &hcl.BodySchema{
 		{
 			Name: "ephemeral",
 		},
+		{
+			Name: "deprecated",
+		},
 	},
 	Blocks: []hcl.BlockHeaderSchema{
 		{Type: "precondition"},

internal/configs/named_values_test.go

@@ -48,3 +48,56 @@ func TestVariableInvalidDefault(t *testing.T) {
 		}
 	}
 }
+
+func TestOutputDeprecation(t *testing.T) {
+	src := `
+		output "foo" {
+			value = "bar"
+			deprecated = "This output is deprecated"
+			}
+		`
+
+	hclF, diags := hclsyntax.ParseConfig([]byte(src), "test.tf", hcl.InitialPos)
+	if diags.HasErrors() {
+		t.Fatal(diags.Error())
+	}
+
+	b, diags := parseConfigFile(hclF.Body, nil, false, false)
+	if diags.HasErrors() {
+		t.Fatalf("unexpected error: %q", diags)
+	}
+	if !b.Outputs[0].DeprecatedSet {
+		t.Fatalf("expected output to be deprecated")
+	}
+
+	if b.Outputs[0].Deprecated != "This output is deprecated" {
+		t.Fatalf("expected output to have deprecation message")
+	}
+}
+
+func TestVariableDeprecation(t *testing.T) {
+	src := `
+		variable "foo" {
+			type = string
+			deprecated = "This variable is deprecated, use bar instead"
+		}
+	`
+
+	hclF, diags := hclsyntax.ParseConfig([]byte(src), "test.tf", hcl.InitialPos)
+	if diags.HasErrors() {
+		t.Fatal(diags.Error())
+	}
+
+	b, diags := parseConfigFile(hclF.Body, nil, false, false)
+	if diags.HasErrors() {
+		t.Fatalf("unexpected error: %q", diags)
+	}
+
+	if !b.Variables[0].DeprecatedSet {
+		t.Fatalf("expected variable to be deprecated")
+	}
+
+	if b.Variables[0].Deprecated != "This variable is deprecated, use bar instead" {
+		t.Fatalf("expected variable to have deprecation message")
+	}
+}