Merge pull request #30931 from hashicorp/jbardin/replace_triggered_by-docs

replace_triggered_by docs

website/docs/language/meta-arguments/lifecycle.mdx

@@ -110,6 +110,31 @@ The following arguments can be used within a `lifecycle` block:
   Only attributes defined by the resource type can be ignored.
   `ignore_changes` cannot be applied to itself or to any other meta-arguments.
 
+* `replace_triggered_by` (list of resource references) - Forces Terraform to replace the parent resource when there is a change to a referenced resource or resource attribute. Supply a list of expressions referencing managed resources, instances, or instance attributes. When the containing resource uses `count` or `for_each`, you can use `count.index` or `each.key` in the expression to index specific instances. 
+
+References trigger replacement in the following conditions:
+  - If the reference is to a resource with multiple instances, a plan to
+    update or replace any instance will trigger replacement.
+  - If the reference is to a single resource instance, a plan to update or
+    replace that instance will trigger replacement.
+  - If the reference is to a single attribute of a resource instance, any
+    change to the attribute value will trigger replacement.
+
+  You can only reference managed resources in `replace_triggered_by` expressions. This lets you modify these expressions without forcing replacement.
+
+  ```hcl
+  resource "aws_appautoscaling_target" "ecs_target" {
+    # ...
+    lifecycle {
+      replace_triggered_by = [
+        # Replace `aws_appautoscaling_target` each time this instance of 
+        # the `aws_ecs_service` is replaced.
+        aws_ecs_service.svc.id
+      ]
+    }
+  }
+  ```
+
 ## Custom Condition Checks
 
 You can add `precondition` and `postcondition` blocks with a `lifecycle` block to specify assumptions and guarantees about how resources and data sources operate. The following examples creates a precondition that checks whether the AMI is properly configured.

website/docs/language/resources/behavior.mdx

@@ -89,6 +89,8 @@ cases,
 [the `depends_on` meta-argument](/language/meta-arguments/depends_on)
 can explicitly specify a dependency.
 
+You can also use the [`replace_triggered_by` meta-argument](/language/meta-arguments/lifecycle#replace_triggered_by) to add dependencies between otherwise independent resources. It forces Terraform to replace the parent resource when there is a change to a referenced resource or resource attribute.
+
 ## Local-only Resources
 
 While most resource types correspond to an infrastructure object type that