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:

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 the module 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:

• GitHub repositories
• Git repositories
• BitBucket repositories

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:

1. Replace the module block from your configuration with a removed block.
2. And add the lifecycle block to your removed block.
3. 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.