---
page_title: 'Plugin Development - Framework: Timeouts'
description: >-
  How to use timeouts with the provider development framework.
---

# Timeouts

The reality of cloud infrastructure is that it typically takes time to perform operations such as booting operating systems, discovering services, and replicating state across network edges. As the provider developer you should take known delays in resource APIs into account in the CRUD functions of the resource. Terraform supports configurable timeouts to assist in these situations.

The Framework can be used in conjunction with the [terraform-plugin-framework-timeouts](https://github.com/hashicorp/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](https://github.com/hashicorp/terraform-plugin-framework)
then we recommend using nested attributes.

If you are [migrating a provider from SDKv2 to the Framework](/terraform/plugin/framework/migrating) 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:

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

  timeouts {
    create = "60m"
  }
}
```

Import the [timeouts module](https://github.com/hashicorp/terraform-plugin-framework-timeouts).

```go
import (
    /* ... */
    "github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts"
)
````

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

```go
func (t *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        /* ... */

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

#### Attribute

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

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

  timeouts = {
    create = "60m"
  }
}
```

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

```go
func (t *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.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.

```go
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...)
```

Modify the `exampleResourceData` model to include a field for timeouts using a [`timeouts.Value`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts#Value) type.

```go
type exampleResourceData struct {
    /* ... */
    Timeouts    timeouts.Value `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 function (e.g., [`timeouts.Create`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts#Value.Create)) and then used to configure timeout behaviour, for instance:

```go
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
    }

    createTimeout, diags := data.Timeouts.Create(ctx, 20*time.Minute)

    resp.Diagnostics.Append(diags...)

    if resp.Diagnostics.HasError() {
        return
    }

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

    /* ... */
}
```
