Does a framework resource plan modifier run multiple times like a validator?

hQnVyLRx · March 19, 2025, 8:08pm

Resources which implement the ResourceWithValidateConfig interface may find their ValidateConfig() method invoked multiple times, possibly with some attribute values unknown in the early invocations.

Does the same apply to ModifyPlan()?

I’m facing a situation where the plan modifier is flagging a resource for replacement because (I believe) at the time the modifier is run, a critical attribute is unknown. That attribute will eventually turn out to be unchanged.

In fact, if I’m reading the plan summary correctly, the whole resource is unchanged. The only attributes indicating modification are those which say (known after apply) … and which should have been a no-op because they turn out to have the same value in the end.

So…

How should I handle these unknowns in the plan modifier?
I’m struggling to reproduce this condition (the real user’s configuration is impossibly complicated) … How can I reliably force a known after apply value for an attribute in a simple test environment?

edit: Okay, I’ve managed #2 by running the value through a terraform_data resource’s input and output attributes.

austin.valle · March 19, 2025, 11:09pm

Ref: terraform/docs/resource-instance-change-lifecycle.md at main · hashicorp/terraform · GitHub

Framework itself, for a single PlanResourceChange call, will only call your ModifyPlan function once. If you run terraform apply, you’ll observe two PlanResourceChange calls made to your provider, the first producing the Initial Planned State and the second producing the Final Planned State (after the approval and after it’s dependencies have been resolved). So for an apply command, you can expect two calls to ModifyPlan, a plan command would be one call to ModifyPlan.

The Initial Planned State can have unknowns in the configuration, the Final Planned State will always have a fully known configuration (the entire plan itself isn’t fully known, since you likely have computed values that you’ll set during Create/Update (ApplyResourceChange).

How should I handle these unknowns in the plan modifier?

Similar to validation, if you encounter an unknown value that is in the configuration, you should skip modifying the plan. So you should only require replacement when the value is known and satisfies whatever your plan modifier is trying to do.

I’m struggling to reproduce this condition (the real user’s configuration is impossibly complicated) … How can I reliably force a known after apply value for an attribute in a simple test environment?

edit: Okay, I’ve managed #2 by running the value through a terraform_data resource’s input and output attributes.

Yeah that’s exactly what I do if I’m using a later version of Terraform. If you’re not, you can use the null_resource or one of the random provider resources, since they both have an easy way to trigger new unknown values.

hQnVyLRx · March 20, 2025, 12:37am

Similar to validation, if you encounter an unknown value that is in the configuration, you should skip modifying the plan. So you should only require replacement when the value is known and satisfies whatever your plan modifier is trying to do.

Awesome I’m so relieved to hear this!

But I remain a little confused:

two PlanResourceChange calls made to your provider, the first producing the Initial Planned State and the second producing the Final Planned State (after the approval and after it’s dependencies have been resolved).

I assume that “after the approval” is referring to the interactive “Do you want to perform these actions?” prompt. Do I have that right?

It seems like Terraform, having already presented a plan and received user approval, should already know what’s going to happen. Springing a RequiresReplace at this point seems a little late…

I hope I misunderstood!

austin.valle · March 20, 2025, 12:11pm

I assume that “after the approval” is referring to the interactive “Do you want to perform these actions?” prompt. Do I have that right?

Yes that’s correct

It seems like Terraform, having already presented a plan and received user approval, should already know what’s going to happen. Springing a RequiresReplace at this point seems a little late…

Apologies, my answer was incomplete for your scenario. Assuming that your resource absolutely needs to be replaced when you finally determine what the final value is (which you cannot definitively get until all dependencies have been applied), you can set it as needing to be replaced during the final plan but Terraform will prompt the user with an error message indicating that the final plan has changed (which can be resolved with a follow-up apply):

│ Error: Provider produced inconsistent final plan
│ 
│ When expanding the plan for examplecloud_thing.test to include new values learned so far during apply, provider "registry.terraform.io/austinvalle/sandbox" changed the planned action from Update to
│ DeleteThenCreate.
│ 
│ This is a bug in the provider, which should be reported in the provider's own issue tracker.

The only difference tolerated from the initial plan to the final plan are unknown values becoming known, from that lifecycle link I gave above:

Terraform Core compares the final with the initial planned state, enforcing the following additional constraints along with those listed above:

* Any attribute that had a known value in the Initial Planned State must have an identical value in the Final Planned State.
* Any attribute that had an unknown value in the Initial Planned State may either remain unknown in the second or take on any known value that conforms to the unknown value's type constraint.

If the practitioner then runs another plan/apply (which would now have a known value for your dependencies in prior state), then the initial plan would show the replacement.

So in general, it’d be best to avoid determining replacement during the final plan if possible since that’s considered an error state to Terraform.

austin.valle · March 20, 2025, 12:15pm

Not sure if it’d be helpful in your exact scenario for determining replacement earlier, but there was a proposed enhancement we had for terraform-plugin-framework to understand partially unknown values (like that a value will definitely not be null), which could aid in some of these early plan modifiers. That work has since stalled but I imagine it’ll get merged some day

github.com/hashicorp/terraform-plugin-framework

Consider allowing providers to refine unknown values as "definitely not null"

opened 01:50AM - 02 Nov 23 UTC

apparentlymart

enhancement types protocol

### Module version v1.4.2 is current at the time I'm writing this, although t…his issue is discussing an entirely new capability. ### Use-cases It's relatively common to write a module with an optional input variable whose presence (non-nullness) causes additional resource instances to get declared. Here's a simple, though somewhat-contrived example: ```hcl variable "iam_policy" { type = string default = null } resource "aws_iam_role_policy" "example" { count = var.iam_policy != null ? 1 : 0 policy = var.iam_policy } ``` The above declares that there should be one instance of `aws_iam_role_policy.example` if `var.iam_policy` is not null, or zero instances if it's null. This is a reasonable module design, but it has a hidden trap: IAM policy documents are often unknown during the planning phase because the AWS provider tends to populate `arn` attributes only during the apply step, and IAM policy documents typically include ARNs, leading to the policy JSON string being unknown during the plan phase too. ```hcl data "aws_iam_policy_document" "example" { # ... } module "as_above" { source = "./as_above" # ... iam_policy = data.aws_iam_policy_document.example.json } ``` Whenever the policy includes an unknown ARN, `data.aws_iam_policy_document.example.json` itself will be unknown. Providers are allowed to decide that an unknown attribute is finally set to `null` during the apply step, and so Terraform cannot make any assumptions about what `var.iam_policy != null` would return inside the module in this case, leading to the dreaded error about the number of instances not being known. ### Attempted Solutions The classic workaround for this is to wrap the possibly-unknown string up in some kind of container whose nullness can be independent of the string inside: ```hcl variable "iam_policy" { type = object({ json = string }) default = null } resource "aws_iam_role_policy" "example" { count = var.iam_policy != null ? 1 : 0 policy = var.iam_policy.json } ``` In the above example, the caller could set `iam_policy = data.aws_iam_policy_document.example`, and Terraform knows that a reference to an entire resource instance cannot possibly be null and so this would succeed. However, it requires the module author to have been aware of this problem when writing the module originally; if they learn about the problem later only once someone encounters the problem, it would be a breaking change to introduce the extra container. Terraform Core v1.6 has introduced the ability for the language runtime to track if an unknown value is known to be non-null even though its final value isn't known, and various built-in language features and functions already know how to generate that additional information and so that's made available a new workaround that is under the control of the caller of the module, rather than the author of the module, by passing the value through one of Terraform's functions that guarantees that its result cannot be null. For example: ```hcl module "as_above" { source = "./as_above" # ... iam_policy = trimspace(data.aws_iam_policy_document.example.json) } ``` The `trimspace` function returns an error if its argument is null, and so its argument cannot possibly be null. Leading and trailing space is not significant in a JSON document, so trimming it is effectively a no-op, but this also secretly makes `var.iam_policy` be "unknown but definitely not null", rather than just "unknown", which means that `var.iam_policy != null` will now return `true` instead of an unknown boolean result. This is a slightly more satisfying workaround because it doesn't involve making a breaking change to the callee, but it also relies on some "magic" that would be unclear to a future reader who isn't familiar with all of the fine details of the Terraform language: there's nothing in the above that explains that `trimspace` is "load-bearing", and so it would be reasonable for a future maintainer to remove it believing it's doing nothing, and then not notice they've broken things until the policy document next becomes unknown, which could be in the far future. ### Proposal I think it would be ideal if we offered provider developers a way to participate in this ability to declare that an unknown value is definitely not null, so that `data.aws_iam_policy_document.example.json` alone would be sufficient to get a functional result: this data source will always either produce a valid JSON string or it will return an error, so it's a good candidate for being marked as definitely-not-null. I don't have a concrete proposal for how to represent this in the framework API, however. I'm creating this issue only to mark that it might be a good time to start thinking about that, since the built-in value refinement capabilities in Terraform Core now seem to be working reasonably well and so I don't expect the "definitely not null" part of it to need significant changes that would be more difficult to make once providers are using it. Terraform Core also supports some other "refinements" for unknown values, such as known prefixes on unknown strings and upper and lower bounds on possible collection lengths. It might be good to think about how and whether those could be incorporated in future too, but I would suggest holding on actually implementing those until we get a little more experience with the behaviors in Terraform Core, since they arise less often in practice and so I've not seen so many practical examples of them working yet. "Definitely not null" seems both working well enough that I feel willing to commit to not significantly changing it and is also the refinement that has the most impact on practical use of Terraform. ### References As discussed over in https://github.com/hashicorp/terraform/issues/30937, I'd like to in future reach a point where the presence of unknown values is dealt with in a different way than totally failing with an error, which would make the situation I described under "use-cases" less significant than it is today. However, based on my research so far it seems that the most likely change in that area is for Terraform to propose only a partial plan and defer planning some actions until a future run when more information is available, and so that would be better than a hard failure but still non-ideal. Therefore I think it would still be better to reduce the number of situations where unknown values arise, so that this "deferring" behavior will be reserved only for when it's absolutely unavoidable. Because Terraform Core uses the same MessagePack encoding for its plan file format and for the provider protocol, there's already [wire protocol support for refinements](https://github.com/hashicorp/terraform/blob/main/docs/plugin-protocol/object-wire-format.md#schemaattribute-mapping-rules-for-messagepack) which the framework could begin using, but I think the bigger question here is what would be a good way to represent this in the framework API as experienced by provider developers, so that it's relatively convenient to use and thus more likely that provider developers will make use of it.

github.com/hashicorp/terraform-plugin-framework

all: Add support for unknown value refinement data to all types

main ← av/refinements

opened 03:50PM - 03 Dec 24 UTC

austinvalle

+11967 -153

Closes #869 Ref: https://github.com/hashicorp/terraform/issues/30937 Ref: h…ttps://github.com/hashicorp/terraform-plugin-go/pull/448 ----------------- This PR introduces [value refinement](https://github.com/zclconf/go-cty/blob/63279be090d7ca5fd01e5ecb7f02ac5f0c273ef2/docs/refinements.md) support to the `basetypes` Go package, which allows Framework providers to communicate unknown value refinements to/from Terraform core (first introduced in Terraform 1.6). Value refinements are additional constraints that can be applied to unknown values in Terraform that can be used to produce known results from unknown values. For example, with value refinements, providers can now indicate specific attributes will "definitely not be null" during `PlanResourceChange`, which would allow Terraform core to successfully evaluate expressions like count during plan: ```terraform resource "examplecloud_thing" "a" { # Has a computed attribute (id) where the final value will not be null } resource "examplecloud_thing" "b" { // Will successfully evaluate during plan with a "not null" refinement on "id" count = examplecloud_thing.a.id != null ? 1 : 0 } ``` Without unknown value refinements, the above config will return an error when running `terraform plan`: ```bash │ Error: Invalid count argument │ │ ... │ │ The "count" value depends on resource attributes that cannot be │ determined until apply, so Terraform cannot predict how many │ instances will be created. To work around this, use the -target │ argument to first apply only the resources that the count depends │ on. ``` ------------- > No changes to existing provider code will be necessary as partially unknown values will still evaluate the same as a wholly unknown value today. ### TODOs left on this PR - Design is still under review - Couple open items to investigate - Double check the `Dynamic` paths with refinements. There shouldn't be any changes needed since it's just a container (and dynamic itself cannot have a refinement) - Double check the int vs. float refinements (int attributes could possible receive a floating point number in a refinement, need to determine how we should handle that) - Website documentation - Update to use released version of `terraform-plugin-go`, once that's ready - Changelogs

hQnVyLRx · March 20, 2025, 12:37pm

This helped a lot.

In fact, you have helped me a lot here over the last year-ish. Thank you, @austin.valle.

I understand the situation much better now.

In the specific case I’m facing (a bug report from a practitioner with some awesomely convoluted HCL), the unknown values are going to wind up with unmodified final values.

If I defer triggering RequiresReplace until all values are known, I might wind up triggering the Provider produced inconsistent final plan error, but it’s probably exceedingly rare that a configuration will satisfy both conditions required to wind up there:

an unknown critical attribute
the critical attribute’s final value represents a change from the previous value

I’m leaning toward deferring RequiresReplace until final plan, like you recommended.

Maybe I’ll add a boolean which allows the practitioner to opt-in to this behavior. I’m wary of writing a “feature” which I know might lead to “This is a bug in the provider…”

Thanks!

Topic		Replies	Views
Computed attributes and plan modifiers Plugin Development	19	4346	July 18, 2023
No way to validate an unknown attribute value? Plugin Development	10	109	July 25, 2024
Is there a way to avoid produced inconsistent result after apply? Plugin Development	6	1643	April 15, 2024
Required attribute is unknown for ValidateConfig? Plugin Development	4	40	November 11, 2024
Need to run terraform plan/apply twice to effect all changes AWS	6	3006	August 14, 2023

Does a framework resource plan modifier run multiple times like a validator?

Related topics