add deprecation marks to resources based on schema

Author: DanielMSchmidt

.changes/v1.15/ENHANCEMENTS-20260120-172831.yaml

@@ -0,0 +1,5 @@
+kind: ENHANCEMENTS
+body: improve detection of deprecated resource attributes / blocks
+time: 2026-01-20T17:28:31.861321+01:00
+custom:
+    Issue: "38077"

internal/configs/configschema/validate_traversal.go

@@ -77,27 +77,6 @@ func (b *Block) StaticValidateTraversal(traversal hcl.Traversal) tfdiags.Diagnos
 	}
 
 	if attrS, exists := b.Attributes[name]; exists {
-		// Check for Deprecated status of this attribute.
-		// We currently can't provide the user with any useful guidance because
-		// the deprecation string is not part of the schema, but we can at
-		// least warn them.
-		//
-		// This purposely does not attempt to recurse into nested attribute
-		// types. Because nested attribute values are often not accessed via a
-		// direct traversal to the leaf attributes, we cannot reliably detect
-		// if a nested, deprecated attribute value is actually used from the
-		// traversal alone. More precise detection of deprecated attributes
-		// would require adding metadata like marks to the cty value itself, to
-		// be caught during evaluation.
-		if attrS.Deprecated {
-			diags = diags.Append(&hcl.Diagnostic{
-				Severity: hcl.DiagWarning,
-				Summary:  `Deprecated attribute`,
-				Detail:   fmt.Sprintf(`The attribute %q is deprecated. Refer to the provider documentation for details.`, name),
-				Subject:  next.SourceRange().Ptr(),
-			})
-		}
-
 		// For attribute validation we will just apply the rest of the
 		// traversal to an unknown value of the attribute type and pass
 		// through HCL's own errors, since we don't want to replicate all

internal/configs/configschema/validate_traversal_test.go

@@ -224,10 +224,6 @@ func TestStaticValidateTraversal(t *testing.T) {
 			`obj.nested_map["key"].optional`,
 			``,
 		},
-		{
-			`obj.deprecated`,
-			`Deprecated attribute: The attribute "deprecated" is deprecated. Refer to the provider documentation for details.`,
-		},
 	}
 
 	for _, test := range tests {

internal/deprecation/deprecation.go

@@ -131,3 +131,7 @@ func (d *Deprecations) IsModuleCallDeprecationSuppressed(addr addrs.Module) bool
 	}
 	return false
 }
+
+func (d *Deprecations) DiagnosticsForValueMarks(valueMarks cty.ValueMarks, module addrs.Module, rng *hcl.Range) tfdiags.Diagnostics {
+	return d.deprecationMarksToDiagnostics(marks.FilterDeprecationMarks(valueMarks), module, rng)
+}

internal/deprecation/schema.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package deprecation
+
+import (
+	"fmt"
+
+	"github.com/hashicorp/terraform/internal/configs/configschema"
+	"github.com/hashicorp/terraform/internal/lang/marks"
+	"github.com/zclconf/go-cty/cty"
+)
+
+// MarkDeprecatedValues inspects the given cty.Value according to the given
+// configschema.Block schema, and marks any deprecated attributes or blocks
+// found within the value with deprecation marks.
+// It works based on the given cty.Value's structure matching the given schema.
+func MarkDeprecatedValues(val cty.Value, schema *configschema.Block, origin string) cty.Value {
+	if schema == nil {
+		return val
+	}
+	newVal := val
+
+	// Check if the block is deprecated
+	if schema.Deprecated {
+		newVal = newVal.Mark(marks.NewDeprecation("deprecated resource block used", origin))
+	}
+
+	if !newVal.IsKnown() {
+		return newVal
+	}
+
+	// Even if the block itself is not deprecated, its attributes might be
+	// deprecated as well
+	if val.Type().IsObjectType() || val.Type().IsMapType() || val.Type().IsCollectionType() {
+		// We ignore the error, so errors are not allowed in the transform function
+		newVal, _ = cty.Transform(newVal, func(p cty.Path, v cty.Value) (cty.Value, error) {
+
+			attr := schema.AttributeByPath(p)
+			if attr != nil && attr.Deprecated {
+				v = v.Mark(marks.NewDeprecation("deprecated resource attribute used", fmt.Sprintf("%s.%s", origin, p)))
+			}
+
+			block := schema.BlockByPath(p)
+			if block != nil && block.Deprecated {
+				v = v.Mark(marks.NewDeprecation("deprecated resource block used", fmt.Sprintf("%s.%s", origin, p)))
+			}
+
+			return v, nil
+		})
+	}
+
+	return newVal
+}