hashicorp / hashicorp/terraform-plugin-framework

[RFE]: distinguish planning vs apply-time ModifyPlan execution for plan-time side-effect warnings

Open
#1,306 0 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
384
Forks
107
Avg merge
3m
Merged PRs (30d)
1

Description

### Module version

```bash
github.com/hashicorp/terraform-plugin-framework v1.19.0
```

### Use-cases

Some resources need to emit an informational warning at plan time when an in-place update has an operational side effect.

A minimal example is a generic resource like `example_resource` where changing one attribute performs an in-place update but temporarily interrupts the managed object while the change is applied. The provider should be able to warn during planning so users understand that side effect before apply.

In this case, the warning should appear during normal planning, but not be repeated later during apply if nothing about the warning itself has changed. Showing the same warning during planning and again after apply can be confusing for users in this type of use-case, because the warning describes the impact of the upcoming change, while the second appearance happens after the change has already completed.

### Attempted Solutions

`ModifyPlan` is currently the only framework function I found that fits this use-case, because it provides:
- access to both prior state and planned values
- the ability to return diagnostics during planning

Minimal config:
```hcl
resource "example_resource" "test" {
name = "example"
value = "value-1"
}
```

Then updated to:
```hcl
resource "example_resource" "test" {
name = "example"
value = "value-2"
}
```
```go
// Provider code shape:
func (r *exampleResource) ModifyPlan(ctx context.Context, req resource.ModifyPlanRequest, resp *resource.ModifyPlanResponse) {
if req.State.Raw.IsNull() || req.Plan.Raw.IsNull() {
return
}
var state exampleResourceModel
var plan exampleResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
if resp.Diagnostics.HasError() {
return
}
if state.Value.ValueString() != plan.Value.ValueString() {
resp.Diagnostics.AddWarning(
"Updating this resource has a temporary side effect",
"Changing value performs an in-place update that temporarily interrupts the resource during apply.",
)
}
}
```

Per the Terraform resource instance change lifecycle, `PlanResourceChange` is called twice per run for each resource instance: once during the planning phase and again during the apply step to produce the final planned state. Because framework `ModifyPlan` participates in `PlanResourceChange`, the same warning can be emitted again during apply-time planning even when it was already shown during terraform plan.

### Proposal

It would help to support one of these options:

1. Add context to ModifyPlanRequest so a resource can detect whether ModifyPlan is running for standalone planning or as part of apply.
2. Add a new hook similar to `ModifyPlan` that:
- has access to both state and plan
- can return diagnostics
- runs only during the planning phase

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.