In the previous tutorial, you learned when and why to use Terraform modules. Inthis tutorial, you will use modules from the publicTerraformRegistry to provision an example environment onAWS by referencing the modules in Terraform configuration. The concepts you usein this tutorial will apply to any modules from any source.

Prerequisites

You can complete this tutorial using the same workflow with either TerraformCommunity Edition or HCP Terraform. HCP Terraform is a platform that you can use tomanage and execute your Terraform projects. It includes features like remotestate and execution, structured plan output, workspace resource summaries, andmore.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Start interactive lab

Use the Terraform Registry

Open theTerraform Registry page for the VPCmodule.

This page displays information about the module and a link to the source repository.The page also has a dropdown interface to select themodule version, module usage metrics, and example configuration.

The example configuration sets two arguments:source andversion.

1. Thesource argument is required when you use a Terraform module. In theexample configuration, Terraform will search for a module in the TerraformRegistry that matches the given string. You could also use a URL or localmodule. Refer to theTerraformdocumentation fora full list of possible module sources.

2. Theversion argument is not required, but we highly recommend you include itwhen using a Terraform module. For supported sources, this argument specifiesthe module version Terraform will load. Without the version argument, Terraform will load the latest version of the module. In this tutorial, you will specify anexact version number for the modules you use. Refer to themoduledocumentationfor more methods to specify module versions.

Terraform treats other arguments in the module blocks as input variables for themodule.

Clone the example configuration

Clone theexamplerepository. Theconfiguration in this repository uses modules to create an example AWSenvironment using a Virtual Private Cloud (VPC) and two EC2 instances.

$ git clone https://github.com/hashicorp-education/learn-terraform-modules-use

Change to the repository directory.

$ cd learn-terraform-modules-use

Review configuration

Openterraform.tf. This file defines theterraform block, which Terraformuses to configures itself. This block specifies this Terraform configurationmust use theawsprovider that is within the v4.49.0 minor release. It also requires that you usea Terraform version greater than v1.1.0.

terraform {  /* Uncomment this block to use HCP Terraform for this tutorial  cloud {    organization = "organization-name"    workspaces {      name = "learn-terraform-module-use"    }  }  */  required_providers {    aws= {      source= "hashicorp/aws"      version= "~> 4.49.0"    }  }  required_version= ">= 1.1.0"}

Openmain.tf. This file contains the resource configuration.

provider "aws" {  region= "us-west-2"  default_tags {    tags= {      hashicorp-learn= "module-use"    }  }}module "vpc" {  source= "terraform-aws-modules/vpc/aws"  version= "3.18.1"  name= var.vpc_name  cidr= var.vpc_cidr  azs= var.vpc_azs  private_subnets= var.vpc_private_subnets  public_subnets= var.vpc_public_subnets  enable_nat_gateway= var.vpc_enable_nat_gateway  tags= var.vpc_tags}module "ec2_instances" {  source= "terraform-aws-modules/ec2-instance/aws"  version= "4.3.0"  count= 2  name= "my-ec2-cluster-${count.index}"  ami= "ami-0c5204531f799e0c6"  instance_type= "t3.micro"  vpc_security_group_ids= [module.vpc.default_security_group_id]  subnet_id= module.vpc.public_subnets[0]  tags= {    Terraform= "true"    Environment= "dev"  }}

This configuration includes three blocks:

1. Theprovider "aws" block configures the AWS provider. Depending on theauthenticationmethodyou use, you may need to include additional arguments in the provider block.
2. Themodule "vpc" block configures a Virtual Private Cloud (VPC) module, which provisionsnetworking resources such as a VPC, subnets, and internet and NAT gateways based on the arguments provided.
3. Themodule "ec2_instances" block defines two EC2 instances provisioned within the VPC created by the module.

Set values for module input variables

Modules can contain both required and optional arguments. You must specify allrequired arguments to use the module. Most module arguments correspond to themodule's input variables. Optional inputs will use the module's default values ifnot explicitly defined.

On the Terraform Registry page for the AWS VPC module, click on theInputstab to find theinputargumentsthat the module supports.

Review each argument defined in themodule "vpc" block.

module "vpc" {  source= "terraform-aws-modules/vpc/aws"  version= "3.18.1"  name= var.vpc_name  cidr= var.vpc_cidr  azs= var.vpc_azs  private_subnets= var.vpc_private_subnets  public_subnets= var.vpc_public_subnets  enable_nat_gateway= var.vpc_enable_nat_gateway  tags= var.vpc_tags}

Next, review themodule "ec2_instances" block.

module "ec2_instances" {  source= "terraform-aws-modules/ec2-instance/aws"  version= "4.3.0"  count= 2  name= "my-ec2-cluster-${count.index}"  ami= "ami-0c5204531f799e0c6"  instance_type= "t3.micro"  vpc_security_group_ids= [module.vpc.default_security_group_id]  subnet_id= module.vpc.public_subnets[0]  tags= {    Terraform= "true"    Environment= "dev"  }}

• Thecountmeta-argument defines two EC2 instances. For a full list of modulemeta-arguments, refer to themoduledocumentation.
• The requiredvpc_security_group_ids andsubnet_id arguments reference resources created by thevpc module. TheTerraform Registry modulepagecontains the full list of arguments for theec2-instance module.

Review root input variables

Using input variables with modules is similar to using variables in anyTerraform configuration. A common pattern is to identify which module argumentsyou may want to change in the future, and create matching variables in yourconfiguration'svariables.tf file with sensible default values. You can passthe variables to the module block as arguments.

You do not need to set all module input variables with variables. For example,if your organization requires NAT gateway enabled for all VPCs, you should notuse a variable to set theenable_nat_gateway argument.

Openvariables.tf to review the input variable declarations and definitions.

variable "vpc_name" {  description= "Name of VPC"  type= string  default= "example-vpc"}variable "vpc_cidr" {  description= "CIDR block for VPC"  type= string  default= "10.0.0.0/16"}variable "vpc_azs" {  description= "Availability zones for VPC"  type= list(string)  default= ["us-west-2a", "us-west-2b", "us-west-2c"]}variable "vpc_private_subnets" {  description= "Private subnets for VPC"  type= list(string)  default= ["10.0.1.0/24", "10.0.2.0/24"]}variable "vpc_public_subnets" {  description= "Public subnets for VPC"  type= list(string)  default= ["10.0.101.0/24", "10.0.102.0/24"]}variable "vpc_enable_nat_gateway" {  description= "Enable NAT gateway for VPC"  type= bool  default= true}variable "vpc_tags" {  description= "Tags to apply to resources created by VPC module"  type= map(string)  default= {    Terraform= "true"    Environment= "dev"  }}

Review root output values

Modules also have output values. You can reference them with themodule.MODULE_NAME.OUTPUT_NAME naming convention. In the Terraform Registryfor the module, click on theOutputs tab to findalloutputsfor the module.

You can reference module outputs in other parts of your configuration. Terraformwill not display module outputs by default. You must create a correspondingoutput in your root module and set it to the module's output. This tutorialshows both cases.

Openoutputs.tf to find the module outputs.

output "vpc_public_subnets" {  description= "IDs of the VPC's public subnets"  value= module.vpc.public_subnets}output "ec2_instance_public_ips" {  description= "Public IP addresses of EC2 instances"  value= module.ec2_instances[*].public_ip}

In this example, thevpc_public_subnets output references thevpcmodule'spublic_subnets output, andec2_instance_public_ips references the public IP addresses for both EC2 instances created by the module.

Provision infrastructure

Now, apply your configuration to create your VPC and EC2 instances. Respond tothe prompt withyes to apply the changes. Thevpc andec2 modules definemore resources than just the VPC and EC2 instances.

$ terraform applyTerraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:  + create  ## ...Plan: 22 to add, 0 to change, 0 to destroy.## ...Do you want to perform these actions?  Terraform will perform the actions described above.  Only 'yes' will be accepted to approve.  Enter a value: yes## ...Apply complete! Resources: 22 added, 0 changed, 0 destroyed.Outputs:ec2_instance_public_ips = [  "54.245.140.252",  "34.219.48.47",]vpc_public_subnets = [  "subnet-0cb9ff659ba66a7dd",  "subnet-0c2788b6ffb0611c0",]

Once Terraform completes, it will display the configuration outputs.

If you use HCP Terraform to provision your resources, your workspace now displays the list of all of the resources it manages.

Understand how modules work

When using a new module for the first time, you must run eitherterraform initorterraform get to install the module. When you run these commands, Terraformwill install any new modules in the.terraform/modules directory within yourconfiguration's working directory. For local modules, Terraform will create asymlink to the module's directory. Because of this, any changes to local moduleswill be effective immediately, without having to reinitialize or re-runterraform get.

After following this tutorial, your.terraform/modules directory will looklike the following.

.terraform/modules/├── ec2_instances├── modules.json└── vpc

Clean up your infrastructure

Before moving on to the next tutorial, destroy the infrastructure you created.Respond to the confirmation prompt with ayes.

$ terraform destroy## ...Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:  - destroy  ## ...Plan: 0 to add, 0 to change, 22 to destroy.Changes to Outputs:  - ec2_instance_public_ips = [      - "54.245.140.252",      - "34.219.48.47",    ] -> null  - vpc_public_subnets      = [      - "subnet-0cb9ff659ba66a7dd",      - "subnet-0c2788b6ffb0611c0",    ] -> nullDo you really want to destroy all resources?  Terraform will destroy all your managed infrastructure, as shown above.  There is no undo. Only 'yes' will be accepted to confirm.  Enter a value: yes## ...Destroy complete! Resources: 22 destroyed.

If you used HCP Terraform for this tutorial, after destroying your resources,delete thelearn-terraform-module-use workspace from your HCP Terraformorganization.

Next steps

In this tutorial, you learned how to use modules in your Terraformconfiguration, manage module versions, configure module input variables, and usemodule output values.

HCP TerraformStandard Edition lets you add modules to the privateregistry thatusers can deploy without writing configuration. Follow theCreateand Use No-Code Modules tutorial tocreate a no-code ready module.

In the next tutorial, you will create a module for configuration that hosts a website in an S3 bucket.

This tutorial also appears in: