Creating Modules

Hands-on: Try theReuse Configuration with Modules tutorials.

Amodule is a container for multiple resources that are used together.You can use modules to create lightweight abstractions, so that you candescribe your infrastructure in terms of its architecture, rather thandirectly in terms of physical objects.

The.tf files in your working directory when you runterraform planorterraform apply together form therootmodule. That module maycall other modulesand connect them together by passing output values from one to input valuesof another.

To learn how touse modules, seethe Modules configuration section.This section is aboutcreating re-usable modules that other configurationscan include usingmodule blocks.

Module structure

Re-usable modules are defined using all of the sameconfiguration language concepts we use in root modules.Most commonly, modules use:

• Input variables to accept values fromthe calling module.
• Output values to return results to thecalling module, which it can then use to populate arguments elsewhere.
• Resources to define one or moreinfrastructure objects that the module will manage.

To define a module, create a new directory for it and place one or more.tffiles inside just as you would do for a root module. Terraform can load moduleseither from local relative paths or from remote repositories; if a module willbe re-used by lots of configurations you may wish to place it in its ownversion control repository.

Modules can also call other modules using amodule block, but we recommendkeeping the module tree relatively flat and usingmodule compositionas an alternative to a deeply-nested tree of modules, because this makesthe individual modules easier to re-use in different combinations.

When to write a module

In principle any combination of resources and other constructs can be factoredout into a module, but over-using modules can make your overall Terraformconfiguration harder to understand and maintain, so we recommend moderation.

A good module should raise the level of abstraction by describing a new conceptin your architecture that is constructed from resource types offered byproviders.

For example,aws_instance andaws_elb are both resource types belonging tothe AWS provider. You might use a module to represent the higher-level concept"HashiCorp Consul cluster running in AWS" whichhappens to be constructed from these and other AWS provider resources.

Wedo not recommend writing modules that are just thin wrappers around singleother resource types. If you have trouble finding a name for your module thatisn't the same as the main resource type inside it, that may be a sign thatyour module is not creating any new abstraction and so the module isadding unnecessary complexity. Just use the resource type directly in thecalling module instead.

No-Code Provisioning in HCP Terraform

You can also create no-code ready modules to enable the no-code provisioning workflow in HCP Terraform. No-code provisioning lets users deploy a module's resources in HCP Terraform without writing any Terraform configuration.

No-code ready modules have additional requirements and considerations. Refer toDesigning No-Code Ready Modules in the HCP Terraform documentation for details.

Refactoring module resources

You can includerefactoring blocks to record how resourcenames and module structure have changed from previous module versions.Terraform uses that information during planning to reinterpret existing objectsas if they had been created at the corresponding new addresses, eliminating aseparate workflow step to replace or migrate existing objects.