Plan Modification

Add Custom Plan Modification Logic

Use the x-speakeasy-plan-modifiers extension to add custom plan modification logic to Terraform plan operations. Plan modifiers enable advanced default value, resource replacement, and difference suppression logic.

components:

  schemas:

    Pet:

      type: object

      x-speakeasy-entity: Pet

      properties:

        name:

          type: string

        age:

          type: integer

          x-speakeasy-plan-modifiers: AgeModifier

In this scenario, when Speakeasy next generates the Terraform provider, it will bootstrap a custom plan modifier file located at internal/planmodifiers/int64planmodifier/age_modifier.go, and import the schema configuration wherever x-speakeasy-plan-modifiers: AgeModifier is referenced. You can edit the plan modifier file to contain your logic.

Implementation Notes

  1. A plan modifier is a type conformant to the terraform-plugin-framework expected interface. A unique plan modifier will be bootstrapped in the appropriate subfolder for the Terraform type it is applied to: boolplanmodifiers, float64planmodifiers, int64planmodifiers, listplanmodifiers, mapplanmodifiers, numberplanmodifiers, objectplanmodifiers, setplanmodifiers, or stringplanmodifiers. Speakeasy will always create and use a file as snake_case.go for a given x-speakeasy-plan-modifiers value.

  2. A plan modifier operates on the raw (untyped) Terraform value types. However, you can convert a Terraform type to a value type Speakeasy manages (type_mytype.go) by using the included reflection utility. This is useful for applying modifiers to complex types like list, map, object, and set.

  3. While working with a plan modifier, you have the ability to perform various tasks, including initiating network requests. However, it’s important to ensure that plan modifiers do not result in any unintended side effects. Please refer to the HashiCorp guidance on plan modifier development (opens in a new tab) or reach out in our Slack if you have questions.

  4. It is possible to have an array of plan modifiers, for example, x-speakeasy-plan-modifiers: [FirstModifier, SecondModifier].

  5. A modifier can only be applied to a resource attribute. The annotation will be ignored for data sources. Modifiers cannot be applied at the same level as the x-speakeasy-entity annotation because that becomes the “root” of the Terraform resource.

  6. Speakeasy regenerations do not delete user-written code. If the modifier is no longer in use, it will be ignored (no longer referenced) but the source file will remain. You might want to delete such an orphaned modifier file for repository hygiene.

Specify Resource Version

The x-speakeasy-entity-version extension specifies the version of a given resource and should only be used if you need to write a state migrator, for instance, if you are changing the type of a field.

Terraform resource versions are zero-indexed and default to 0. For your first breaking change requiring a state migrator, set x-speakeasy-entity-version: 1. Each state migrator function must migrate from the previous version of the state.

If this is set, a boilerplate state upgrader will be written and hooked into internal/stateupgraders/your_resource_v1.go. Please refer to the Terraform documentation (opens in a new tab) for guidance on writing a state migrator.