helper/schema: Add configurable Timeouts

[catsby]

This adds to helper/schema the concept of Timeouts, allowing Provider developers to opt-in to offering customizable timeouts for a given Create, Read, Update, Delete action. By exposing timeouts per action, operators can customize the amount of time Terraform is allowed to operate a specific action before timing out.

A concrete example can be found in aws_db_instance.go, a resource that notoriously takes a very long time to provision. In the past there have been frequent requests to increase the amount of time allowed for provisioning, modification, and deletion. Because these actions vary on configuration (instance size, backup creation requirements), some require more time than others. While bumping the timeout is generally fine, it does have drawbacks, mainly being that any change requires a new release of Terraform, and there exists possibilities of unknown issues that would cause an operation to get stuck in a retry loop, thus taking a very long time to surface a currently uncaught error.

With Timeouts, Resource/Provider developers expose configurable options for users like so:

• The Resource defines Timeouts for Create, Update, and Delete operations, alongside the schema:

Schema: &schema.Schema{
  [...],
},
Timeouts: &schema.ResourceTimeout{
  Create: schema.DefaultTimeout(40 * time.Minute),
  Update: schema.DefaultTimeout(80 * time.Minute),
  Delete: schema.DefaultTimeout(40 * time.Minute),
},

• The Resource code references these via the new ResourceData method Timeout:

    d.Timeout("create") 

• Users can overwrite these builtin times in their configuration:

resource "aws_db_instance" "timeout_example" {
  allocated_storage    = 10
  engine               = "mysql"
  engine_version       = "5.6.17"
  instance_class       = "db.t1.micro"
  name                 = "mydb"
  [...]

  timeout {
    create = "60m"
    delete = "2h"
  }
}

This allows Provider/Resource developers the ability to provide good default timeouts for operations, but allows for users with possibly very different workload expectations to customize this time.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.