From 7b40b316974227cec1753f30db6f4e3b4db08264 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 22 Apr 2022 15:34:34 -0400 Subject: [PATCH 1/5] replace_triggered_by docs --- .../language/meta-arguments/lifecycle.mdx | 37 +++++++++++++++++++ website/docs/language/resources/behavior.mdx | 6 +++ 2 files changed, 43 insertions(+) diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx index 7d1e83fe5ded..65e0ac443195 100644 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -110,6 +110,43 @@ 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) - A list of expressions + referencing managed resources, instances, or instance attributes can be + supplied to `replace_triggered_by` to force replacement of the parent + resource when there is a change in the referenced value. When the containing + resource is using `count` or `for_each`, `count.index` or `each.key` may be + used in the expression to index specific instances. + + `replace_triggered_by` is used to couple the lifecycles of otherwise + independent resources, allowing the configurable replacement of a resource + based on conditions in a dependency. Given the three classes of references + allowed in `replace_triggered_by`, the following conditions can apply: + - 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 + difference in the before and after value will trigger replacement. + + Only managed resources are allowed in the `replace_triggered_by` arguments. + Because the `replace_triggered_by` expressions are used to lookup changes in + managed resources, the `replace_triggered_by` argument can be modified + without forcing replacement. + + ```hcl + resource "aws_appautoscaling_target" "ecs_target" { + # ... + lifecycle { + replace_triggered_by = [ + # This resource must be replaced each time the aws_ecs_service is replaced. + # If we don't want to trigger on every change, we can use a computed + # attribute like id to trigger only on instance replacement. + 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. diff --git a/website/docs/language/resources/behavior.mdx b/website/docs/language/resources/behavior.mdx index 4d53a1f6191c..85636b8c3acf 100644 --- a/website/docs/language/resources/behavior.mdx +++ b/website/docs/language/resources/behavior.mdx @@ -89,6 +89,12 @@ cases, [the `depends_on` meta-argument](/language/meta-arguments/depends_on) can explicitly specify a dependency. +In some cases a resource may need to be replaced when a dependency is updated +or replaced, but there is no natural reference to add in the resource +configuration. In that case +[the `replace_triggered_by` meta-argument](/language/meta-arguments/lifecycle#replace_triggered_by) +can be used to add the necessary dependency and force replacement. + ## Local-only Resources While most resource types correspond to an infrastructure object type that From 840a7437c2097c7e77a8297525ec7e2cd6898021 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Tue, 26 Apr 2022 18:17:41 -0400 Subject: [PATCH 2/5] Update website/docs/language/meta-arguments/lifecycle.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- .../docs/language/meta-arguments/lifecycle.mdx | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx index 65e0ac443195..01e88bd7745a 100644 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -110,23 +110,15 @@ 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) - A list of expressions - referencing managed resources, instances, or instance attributes can be - supplied to `replace_triggered_by` to force replacement of the parent - resource when there is a change in the referenced value. When the containing - resource is using `count` or `for_each`, `count.index` or `each.key` may be - used in the expression to index specific instances. - - `replace_triggered_by` is used to couple the lifecycles of otherwise - independent resources, allowing the configurable replacement of a resource - based on conditions in a dependency. Given the three classes of references - allowed in `replace_triggered_by`, the following conditions can apply: +* `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 - difference in the before and after value will trigger replacement. + change to the attribute value will trigger replacement. Only managed resources are allowed in the `replace_triggered_by` arguments. Because the `replace_triggered_by` expressions are used to lookup changes in From 6c15cab211097820d809f64076ad1673d1567dcb Mon Sep 17 00:00:00 2001 From: James Bardin Date: Tue, 26 Apr 2022 18:17:46 -0400 Subject: [PATCH 3/5] Update website/docs/language/meta-arguments/lifecycle.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/meta-arguments/lifecycle.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx index 01e88bd7745a..7c8ee4469b34 100644 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -130,9 +130,8 @@ References trigger replacement in the following conditions: # ... lifecycle { replace_triggered_by = [ - # This resource must be replaced each time the aws_ecs_service is replaced. - # If we don't want to trigger on every change, we can use a computed - # attribute like id to trigger only on instance replacement. + # Replace `aws_appautoscaling_target` each time this instance of + # the `aws_ecs_service` is replaced. aws_ecs_service.svc.id ] } From 4e95b24022e17189dacf54f5742359cc24cbc5df Mon Sep 17 00:00:00 2001 From: James Bardin Date: Tue, 26 Apr 2022 18:17:52 -0400 Subject: [PATCH 4/5] Update website/docs/language/meta-arguments/lifecycle.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/meta-arguments/lifecycle.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx index 7c8ee4469b34..ed9d9313df0e 100644 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -120,10 +120,7 @@ References trigger replacement in the following conditions: - If the reference is to a single attribute of a resource instance, any change to the attribute value will trigger replacement. - Only managed resources are allowed in the `replace_triggered_by` arguments. - Because the `replace_triggered_by` expressions are used to lookup changes in - managed resources, the `replace_triggered_by` argument can be modified - without forcing 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" { From 0501980b461d8eb4cbc7dd4ba329157ce3b96b66 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Tue, 26 Apr 2022 18:17:58 -0400 Subject: [PATCH 5/5] Update website/docs/language/resources/behavior.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/resources/behavior.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/website/docs/language/resources/behavior.mdx b/website/docs/language/resources/behavior.mdx index 85636b8c3acf..8f3f91f1dbc0 100644 --- a/website/docs/language/resources/behavior.mdx +++ b/website/docs/language/resources/behavior.mdx @@ -89,11 +89,7 @@ cases, [the `depends_on` meta-argument](/language/meta-arguments/depends_on) can explicitly specify a dependency. -In some cases a resource may need to be replaced when a dependency is updated -or replaced, but there is no natural reference to add in the resource -configuration. In that case -[the `replace_triggered_by` meta-argument](/language/meta-arguments/lifecycle#replace_triggered_by) -can be used to add the necessary dependency and force replacement. +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