Terraform
Migrating timeouts
You can use the
terraform-plugin-framework-timeouts
module with the plugin framework, which lets you define timeouts in configuration. The module also lets you make timeouts available in Read
functions.
You can implement configurable timeouts for your provider under development. Timeouts let you account for known delays in data source APIs when implementing the read function of your data source. Timeouts help improve the user experience when booting operating systems, discovering services, state replication across network edges, and other operations take longer than expected.
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. Remember to only introduce breaking changes to your provider in major version updates.
Migrating timeouts in nested blocks
If your configuration is using a nested block to define timeouts, such as the following:
resource "timeouts_example" "example" {
/* ... */
timeouts {
read = "60m"
}
}
Import the timeouts module.
Framework
import (
/* ... */
"github.com/hashicorp/terraform-plugin-framework-timeouts/datasource/timeouts"
)
You can use this module to mutate the schema.Schema
as follows:
Framework
func (d *ThingDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{
/* ... */
Blocks: map[string]schema.Block{
"timeouts": timeouts.Block(ctx),
},
Migrating timeouts in nested attributes
If your configuration is using nested attributes to define timeouts, such as the following:
resource "timeouts_example" "example" {
/* ... */
timeouts = {
read = "60m"
}
}
You can use this module to mutate the schema.Schema
as follows:
Framework
func (d *ThingDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{
Attributes: map[string]schema.Attribute{
/* ... */
"timeouts": timeouts.Attributes(ctx),
},
Updating models
Given a Read
method which fetches the entire configuration:
Framework
func (e *exampleDataSource) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {
var data exampleDataSourceData
diags := req.Config.Get(ctx, &data)
resp.Diagnostics.Append(diags...)
Modify the exampleDataSourceData
model to include a field for timeouts using a
timeouts.Value
type.
Framework
type exampleDataSourceData struct {
/* ... */
Timeouts timeouts.Value `tfsdk:"timeouts"`
Accessing timeouts in the Read function
Call the timeouts.Read()
function
to access a timeout's value in your data source's Read()
function.
Framework
func (e *exampleDataSource) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {
var data exampleDataSourceData
diags := req.Config.Get(ctx, &data)
resp.Diagnostics.Append(diags...)
if resp.Diagnostics.HasError() {
return
}
readTimeout, diags := data.Timeouts.Read(ctx, 20*time.Minute)
resp.Diagnostics.Append(diags...)
if resp.Diagnostics.HasError() {
return
}
ctx, cancel := context.WithTimeout(ctx, readTimeout)
defer cancel()
/* ... */
}