HashiConf The full conference agenda's now LIVE. Buy your pass and plan your schedule. Register
Terraform
Terraform Home

You are viewing documentation for version v1.12.x. View latest version.

Configure a resource

A resource is any infrastructure object you want to create and manage with Terraform, including virtual networks, compute instances, or higher-level components such as DNS records. To create resources in Terraform, add resource blocks to your Terraform configuration and specify the required arguments.

This topic provides information about creating and managing resources using resource blocks. For an overview of how to provision infrastructure, refer to Core Terraform workflow. For details about configuring a resource block, refer to your provider documentation and the resource block reference. The resource block reference describes the native Terraform meta-arguments you can use to configure how Terraform creates a resource and manages its lifecycle.

Hands-on: Try the Terraform: Get Started tutorials.

Overview

Complete the following steps to configure a resource:

  • Declare a resource block and specify its type and a name.
  • Configure provider arguments. Most arguments in your resource configuration are specific to your provider.
  • Configure Terraform meta-arguments arguments. Meta-arguments are arguments built into Terraform configuration language to control how Terraform creates and manages resources.

Prerequisites

Choose and configure your provider. Providers are plugins for Terraform that offer a collection of resource types that you can provision. Refer to Providers for more information.

Most providers require authentication settings, version requirements, or other arguments to access their remote APIs. Terraform expects provider configuration in the root module. Refer to the provider block reference for details.

To manage resources, a Terraform module must specify the required providers. Refer to Provider requirements for more information.

Declare a resource

Add a resource block to your configuration, declare a type, and specify a name for it. The type determines the kind of infrastructure object the resource block manages and what arguments the resource supports. Most resource types are implemented by your provider, but Terraform includes a native resource type, terraform_data, that you can use to create resources for specialized use cases.

You must also specify a local name for the resource. Terraform uses the resource type and name as the resource's address in your workspace's state file.

The following example defines an aws_instance resource named web:

resource "aws_instance" "web" {
  #...
}

After applying the configuration, the address for this resource in the state file is aws_instance.web.

Configure provider-specific arguments

Most of the arguments within the body of a resource block are specific to the selected resource type as defined by the provider developer. Configure your resource by assigning values to the resource block’s arguments in your configuration arguments. The resource type's documentation lists which arguments are required and how to format their values. Refer to your provider documentation for details.

The ami and instance_type arguments are specific to the aws provider in the following example:

resource "aws_instance" "web" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"
}

You can use Terraform expressions and other dynamic Terraform language features to configure resource argument values in addition to hard-coding values.

Terraform providers write and maintain their own documentation. For all publicly-available provider documentation, refer to the public Terraform Registry.

Define operation timeouts

Some resource types support a timeouts argument that lets you customize how long Terraform waits for certain operations to complete before exiting with a timeout error. Each resource type determines the set of configuration operations and handles timeouts differently. Refer to the provider documentation to determine if a resource supports the timeout argument.

Resource types that support timeouts arguments conform to the following convention:

  • The resource supports a child block called timeouts.
  • The child block contains a nested argument corresponding to each operation that has a configurable timeout value.
  • Each of these arguments takes a string representation of a duration, such as "60m" for 60 minutes, "10s" for ten seconds, or "2h" for two hours.

The following example configures how long Terraform runs before timing out when creating and deleting the example AWS database instance: 

resource "aws_db_instance" "example" {
  # ...

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

The following example configures how long Terraform runs before timing out when creating and deleting the example AWS database instance: 

resource "aws_db_instance" "example" {
  # ...

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

Configure Terraform meta-arguments

The Terraform language also includes built-in arguments called meta-arguments that you can use with any resource type. Instead of configuring the behavior of the resources, meta-arguments configure how Terraform creates and manages resources.

The following examples describe some common ways you can use meta-arguments in your resource blocks.

Custom conditions

Add precondition and postcondition blocks to specify assumptions and guarantees about how the resource operates. These blocks help avoid common misconfigurations and can help future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context so that consumers can diagnose issues in their configuration. Refer to Validate your configuration for instructions on creating custom condition checks.

For an example configuration, refer to Apply custom conditions.

Define provider configuration aliases

Terraform uses a resource type's name to determine which provider to use. By convention, resource type names start with their provider's preferred local name. You can declare multiple provider configurations in your configuration and configure each resource to use a different configuration. When using multiple provider configurations, use the provider meta-argument to manually choose a provider configuration.

For an example configuration, refer to Select an alternate provider configuration.

Specify resource dependencies

In most cases, Terraform automatically updates resources in dependency order and in parallel when possible. Terraform analyzes expressions within a resource block to find references to other objects and treats those references as the implicit dependencies when creating, updating, or destroying resources.

When a resource depends on another resource, its configuration often includes information taken from its dependent resource. As a result, you do not usually need to manually specify dependencies between resources.

If Terraform cannot implicitly determine the dependency between two resources, you may need to specify explicit dependencies to control the order in which Terraform makes changes to them. For example, when Terraform manages access control policies and must perform an operation that requires the policies to be created first, there is a hidden dependency between the access policy and a resource whose creation depends on it.

You can use the following methods to control the order that Terraform follows to create resources:

Configure built-in resources

You can declare special resource types that help you program actions without affecting actual infrastructure.

terraform_data resources

The terraform_data resource type implements the standard resource lifecycle, but does not directly take any other actions. Refer to terraform_data resource reference for more information.

Local-only resources

You can create resources that calculate values within Terraform and save them in the state for future use. You can configure local-only resources as you would other resources, but their resulting data exist only within the Terraform state.

Destroying local-only resources removes it from the state and discards its data. There is no corresponding actual infrastructure to delete from your cloud provider.

Local-only resources use the built-in terraform.io/builtin/terraform provider and are documented in the public Terraform registry with other provider documentation.

Refer to the following local-only resource types for examples:

Next steps

Edit this page on GitHub