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 toModules overview. For instruction on how to create reusable child modules, refer toDevelop modules.

Hands-on: Try theReuse 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 amodule 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 amodule block

Add themodule block to your configuration and configure thesource 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 thesource argument reference for details.

Install a specific version of the module

If you are using modules from a registry, you can add theversion argument and specify a version constraint. Refer toVersion 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 byHEAD. You can add theref query parameter to the location specified in thesource argument to reference any value supported by thegit 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 asv1.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:

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 thedepth query parameter to thesource URL and specify how many commits the clone operation should include. Thedepth parameter adds the--depth option to thegit clone command, which instructs Git to create a shallow clone that includes only the specified number of commits in the history. Settingdepth to1 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:

• GitHub repositories
• Git repositories
• BitBucket repositories

Specify input values

Module authors expose inputs that you can configure as arguments in themodule 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 theservers 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 onemodule block, instead of adding multiple blocks to your configuration. Add either of the following meta-arguments to yourmodule 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 toCreate 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 thedepends_on argument. Terraform completes all operations on the upstream resource before performing operations on the module containing thedepends_on argument.

Refer toSpecify 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 aprovider argument to yourmodule block.

Refer toSelect 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 themodule.<MODULE-NAME>.<OUTPUT-NAME> expression. Refer to the module documentation for information about its outputs.

In the following example, theaws_subnet resource references the value of the VCP ID output by thevcp 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 theoutput 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 themoved block. Refer toRefactor modules for details.

Install a module

After configuring themodule block in the root or calling module, runterraform init to download the module files into the local working directory. Refer to theterraform init command reference for details.

If you change thesource argument or change theversion argument for a module in a registry, you must rerunterraform 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 theterraform plan command to create preview changes. When you are satisfied with the plan, runterraform apply to create the resources defined by the module. Refer to theterraform 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 yourterraform 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 theaws_instance.example resources managed by theexample module:

$ terraform apply -replace=module.example.aws_instance.exampleterraform 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 themodule block from your Terraform configuration and runterraform apply. By default, Terraform destroys any resources managed by the module and removes them from the state file. Refer toState for information about Terraform state files.

Terraform v1.7 or later is required to use theremoved block. To remove a resource in earlier versions, use theterraform state rm CLI command.

You can also remove a module from your Terraform state without destroying the real infrastructure objects it manages:

1. Replace themodule block from your configuration with aremoved block.
2. And add thelifecycle block to yourremoved block.
3. Add thedestroy argument and set it to `false.

The following example removes themodule.example resources from the Terraform state without destroying them:

removed {  from= module.example  lifecycle {    destroy= false  }}

Refer tomoved block reference for more information.