timeouts.mdx

page_title	description
Plugin Development - Framework: Timeouts	How to migrate timeouts from SDKv2 to the Framework.

Timeouts

-> Note: The Plugin Framework is in beta.

The Framework can be used in conjunction with the terraform-plugin-framework-timeouts module in order to allow defining timeouts in configuration and have them be available in CRUD functions.

Specifying Timeouts in Configuration

Timeouts can be defined using either nested blocks or nested attributes.

If you are writing a new provider using terraform-plugin-framework then we recommend using nested attributes.

If you are migrating a provider from SDKv2 to the Framework and you are already using timeouts you can either continue to use block syntax, or switch to using nested attributes. However, switching to using nested attributes will require that practitioners that are using your provider update their Terraform configuration.

Block

If your configuration is using a nested block to define timeouts, such as the following:

resource "timeouts_example" "example" {
  /* ... */

  timeouts {
    create = "60m"
  }
}

You can use this module to mutate the tfsdk.Schema as follows:

func (t *exampleResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        /* ... */

        Blocks: map[string]tfsdk.Block{
            "timeouts": timeouts.Block(ctx, timeouts.Opts{
                Create: true,
            }),
        },

Attribute

If your configuration is using nested attributes to define timeouts, such as the following:

resource "timeouts_example" "example" {
  /* ... */

  timeouts = {
    create = "60m"
  }
}

You can use this module to mutate the tfsdk.Schema as follows:

func (t *exampleResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            /* ... */
            "timeouts": timeouts.Attributes(ctx, timeouts.Opts{
                Create: true,
            }),
        },

Updating Models

In functions in which the config, state or plan is being unmarshalled, for instance, the Create function, the model will need to be updated.

func (e *exampleResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
	var data exampleResourceData

	diags := req.Plan.Get(ctx, &data)
	resp.Diagnostics.Append(diags...)

The exampleResourceData model needs to be modified to include a field for timeouts, which is types.Object.

type exampleResourceData struct {
    /* ... */
    Timeouts    types.Object `tfsdk:"timeouts"`

Accessing Timeouts in CRUD Functions

Once the model has been populated with the config, state or plan the duration of the timeout can be accessed by calling the appropriate helper (e.g., timeouts.Create) function and then used to configure timeout behaviour, for instance:

func (e *exampleResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
    var data exampleResourceData

    diags := req.Plan.Get(ctx, &data)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    defaultCreateTimeout := 20 * time.Minute

    createTimeout := timeouts.Create(ctx, data.Timeouts, defaultCreateTimeout)

    ctx, cancel := context.WithTimeout(ctx, createTimeout)
    defer cancel()

    /* ... */
}