Terraform
Use modules in your configuration
This page describes how to integrate modules into your configuration so that you can reuse collections of resource definitions. For information about the module workflow and key concepts, refer to Modules overview. For instruction on how to create reusable child modules, refer to Develop modules.
Hands-on: Try the Reuse Configuration with Modules tutorials.
Overview
You can provision collections of resources defined in reusable configurations called modules. After identifying the module you want to use, complete the following steps to integrate modules into your configuration:
- Add a
module
block to your configuration and configure the source, version, and required inputs. - If necessary, configure resources in the root module to reference outputs from the child module.
- Initialize the workspace to install the module. Terraform clones the module source configurations into a hidden subdirectory of the workspace’s working directory.
- Apply the configuration to provision the module's resources.
You can also perform the following actions when integrating modules:
- Transfer resource state into modules
- Reprovision resources within a module
- Remove modules from your configuration
Add a module
block
Add the module
block to your configuration and configure the source
argument, which tells Terraform where to get the child module's configuration files.
You can specify modules hosted on the public or a private Terraform registry, Git repositories, object storage services, and the local file system. Depending on the module source, you can also configure how Terraform installs the module. Refer to the source
argument reference for details.
Install a specific version of the module
If you are using modules from a registry, you can add the version
argument and specify a version constraint. Refer to Version constraints for more information.
If you are using modules hosted in GitHub, BitBucket, or another Git repository, Terraform clones and uses the default branch referenced by HEAD
. You can add the ref
query parameter to the location specified in the source
argument to reference any value supported by the git checkout
command, such as a branch, SHA-1 hash, or tag.
In the following example, Terraform selects the module version from a Git repository tagged as v1.2.0
:
module "vpc" {
source = "git::https://example.com/vpc.git?ref=v1.2.0"
}
You can also source a module using its SHA-1 hash:
```hcl
module "storage" {
source = "git::https://example.com/storage.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}
Refer to the following topics for more information:
- Git documentation on selecting revisions.
source
argument in themodule
block reference.
Use a shallow clone
When retrieving module sources from large repositories, you may prefer to make a shallow clone to reduce how long it takes for Terraform to download the files.
Add the depth
query parameter to the source
URL and specify how many commits the clone operation should include. The depth
parameter adds the --depth
option to the git clone
command, which instructs Git to create a shallow clone that includes only the specified number of commits in the history. Setting depth
to 1
is suitable for most cases because Terraform only uses the most recently selected commit to find the source.
The following module sources support shallow clones:
Specify input values
Module authors expose inputs that you can configure as arguments in the module
block. Inputs let you customize the module's behavior without modifying the module's source code. Refer to the module documentation for inputs that the module supports, including any required inputs. In the following example, the module expects an integer value for the servers
input:
module "servers" {
source = "./app-cluster"
servers = 5
}
Create multiple copies of modules
You can configure Terraform to provision multiple instances of the same module resources in one module
block, instead of adding multiple blocks to your configuration. Add either of the following meta-arguments to your module
block:
count
: Use this argument to state how many instances of a module to provision. All instances have the same configuration.for_each
: Use this argument to loop through a set of keys so that Terraform provisions similar module instances.
Refer to Create multiple instances of module resources for examples.
Set dependencies
Terraform parallelizes module resource creation, but some modules may depend on outputs from other upstream resources. If a module definition references a resource in its arguments, Terraform identifies the implicit dependency and implements the changes in the appropriate order.
You can also explicitly configure dependencies using the depends_on
argument. Terraform completes all operations on the upstream resource before performing operations on the module containing the depends_on
argument.
Refer to Specify a dependency for an example.
Use an alternate provider configuration
By default, Terraform applies the default provider based on the module resource type, but you can create multiple provider configurations and use a non-default configuration for specific modules. To instruct Terraform to apply an alternate provider configuration, add a provider
argument to your module
block.
Refer to Select an alternate provider configuration for an example.
Reference module output values
The resources defined in a module form a self-contained group of resources. Module authors commonly define outputs that expose attribute values for the resources created by the module. You can reference the values in the parent module using the module.<MODULE-NAME>.<OUTPUT-NAME>
expression. Refer to the module documentation for information about its outputs.
In the following example, the aws_subnet
resource references the value of the VCP ID output by the vcp
module:
module "vcp" {
source = "terraform-aws-modules/vpc/aws"
version = "6.0.1"
}
resource "aws_subnet" "main" {
vpc_id = module.vcp.vpc_id
cidr_block = "10.0.1.0/24"
tags = {
Name = "Main"
}
}
For more information about how outputs work, refer to the output
block reference.
Transfer resource state into modules
When you refactor your configuration to use child modules, you may want to move resources that were defined in your root module into the child modules. Because Terraform is declarative, it destroys existing resources and creates new instances when you change the configuration. To change a resource address and move a resource into a child module, use the moved
block. Refer to Refactor modules for details.
Install a module
After configuring the module
block in the root or calling module, run terraform init
to download the module files into the local working directory. Refer to the terraform init
command reference for details.
If you change the source
argument or change the version
argument for a module in a registry, you must rerun terraform init
. For modules that are already installed, include the -upgrade
flag to upgrade the module to the latest version allowed by the version constraint.
Provision modules
Run the terraform plan
command to create preview changes. When you are satisfied with the plan, run terraform apply
to create the resources defined by the module. Refer to the terraform apply
command reference for details.
Reprovision module resources
To reprovision a specific resource managed by a module, add the -replace
flag and the resource address to your terraform apply
command. If the resource you want to replace belongs to a resource within a nested module, specify the full path to that resource, including the nested module. In the following example, Terraform reprovisions the aws_instance.example
resources managed by the example
module:
$ terraform apply -replace=module.example.aws_instance.example
terraform plan -replace=module.example.module.from-child2.aws_instance.child2-inst
Replacing resources is a disruptive operation. You can only select individual resource instances with the -replace
CLI option. Add multiple -replace
options to replace more than one resource in a single command.
Remove modules from your configuration
To remove a module from Terraform, delete the module
block from your Terraform configuration and run terraform apply
. By default, Terraform destroys any resources managed by the module and removes them from the state file. Refer to State for information about Terraform state files.
Terraform v1.7 or later is required to use the removed
block. To remove a resource in earlier versions, use the terraform state rm
CLI command.
You can also remove a module from your Terraform state without destroying the real infrastructure objects it manages:
- Replace the
module
block from your configuration with aremoved
block. - And add the
lifecycle
block to yourremoved
block. - Add the
destroy
argument and set it to `false.
The following example removes the module.example
resources from the Terraform state without destroying them:
removed {
from = module.example
lifecycle {
destroy = false
}
}
Refer to moved
block reference for more information.