Use Modules from the Registry

In the previous tutorial, you learned when and why to use Terraform modules. In this tutorial, you will use modules from the Terraform Registry to provision an example environment on AWS. The concepts you use in this tutorial will apply to any modules from any source.

»Prerequisites

Although the concepts in this tutorial apply to any module, this tutorial uses Amazon Web Services (AWS) modules.

To follow this tutorial you will need:

• An AWS account Configure one of the authentication methods described in our AWS Provider Documentation. The examples in this tutorial assume that you are using the shared credentials file method with the default AWS credentials file and default profile.
• The Terraform CLI

If you don't have an AWS account or Terraform installed locally, complete this tutorial in an interactive lab from your web browser. Click the Show Terminal button to launch the lab experience.

»Use the Terraform Registry

Open the Terraform Registry page for the VPC module in a new browser tab or window.

You will see information about the module, as well as a link to the source repository. On the right side of the page, you will see a dropdown interface to select the module version, as well as instructions to use the module to provision infrastructure.

When calling a module, the source argument is required. In this example, Terraform will search for a module in the Terraform registry that matches the given string. You could also use a URL or local file path for the source of your modules. See the Terraform documentation for a list of possible module sources.

The other argument shown here is the version. For supported sources, the version will let you define which version or versions of the module will be loaded. In this tutorial, you will specify an exact version number for the modules you use. You can read about more ways to specify versions in the module documentation.

Other arguments to module blocks are treated as input variables to the modules.

»Create Terraform configuration

In this tutorial, you will use modules to create an example AWS environment using a Virtual Private Cloud (VPC) and two EC2 instances.

You can follow this tutorial by manually building the directory structure and files we describe in the tutorial, or use the following commands to clone this GitHub repo.

Clone the GitHub repository.

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

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

Change into the directory in your terminal.

$ cd learn-terraform-modules-use

$ cd learn-terraform-modules-use

Open main.tf and find the following configuration.

# Terraform configuration

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

provider "aws" {
  region = "us-west-2"
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "2.21.0"

  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 = "2.12.0"

  name           = "my-ec2-cluster"
  instance_count = 2

  ami                    = "ami-0c5204531f799e0c6"
  instance_type          = "t2.micro"
  vpc_security_group_ids = [module.vpc.default_security_group_id]
  subnet_id              = module.vpc.public_subnets[0]

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

# Terraform configuration
terraform {  required_providers {    aws = {      source = "hashicorp/aws"    }  }}
provider "aws" {  region = "us-west-2"}
module "vpc" {  source  = "terraform-aws-modules/vpc/aws"  version = "2.21.0"
  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 = "2.12.0"
  name           = "my-ec2-cluster"  instance_count = 2
  ami                    = "ami-0c5204531f799e0c6"  instance_type          = "t2.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 four blocks:

• terraform configures Terraform itself. This block requires the aws provider from the official Hashicorp provider registry.
• provider "aws" defines your provider. Depending on the authentication method you chose, you may need to include additional arguments in the provider block.
• module "vpc" defines a Virtual Private Cloud (VPC), which will provide networking services for the rest of your infrastructure.
• module "ec2_instances" defines two EC2 instances within your VPC.

»Set values for module input variables

In order to use most modules, you will need to pass input variables to the module configuration. The configuration that calls a module is responsible for setting its input values, which are passed as arguments in the module block. Aside from source and version, most of the arguments to a module block will set variable values.

On the Terraform registry page for the AWS VPC module, you will see an Inputs tab that describes all of the input variables that module supports.

Some input variables are required, meaning that the module doesn't provide a default value — an explicit value must be provided in order for Terraform to run correctly.

Within the module "vpc" block, review the input variables you are setting. You can find each of these input variables documented in the Terraform registry

• name will be the name of the VPC within AWS.
• cidr describes the CIDR blocks used within your VPC.
• azs are the availability zones that will be used for the VPC's subnets.
• private_subnets are subnets within the VPC that will contain resources that do not have a public IP address or route.
• public_subnets are subnets that will contain resources with public IP addresses and routes.
• enable_nat_gateway if true, the module will provision NAT gateways for your private subnets.
• tags specify the tags for each of the resources provisioned by this configuration within AWS.

You can also review the arguments for the module "ec2_instances" block by comparing them to the module documentation.

When creating EC2 instances, you need to specify a subnet and security group for them to use. This example will use the ones provided by the VPC module.

»Define root input variables

Using input variables with modules is very similar to how you use variables in any Terraform configuration. A common pattern is to identify which module input variables you might want to change in the future, and create matching variables in your configuration's variables.tf file with sensible default values. Those variables can then be passed to the module block as arguments.

Not all module input variables need to be set using variables in your configuration. For instance, you might want this VPC to always have a NAT gateway enabled, because the application you are provisioning requires it. In that case, using a variable to set enable_nat_gateway would be counterproductive.

You will need to define these variables in your configuration to use them.

If you have cloned the git repository mentioned earlier in this tutorial, your variables.tf will look like the below.

Otherwise, copy and paste the following into variables.tf:

# Input variable 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"
  }
}

# Input variable 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"  }}

»Define root output values

Modules also have output values, which are defined within the module with the output keyword. You can access them by referring to module.<MODULE NAME>.<OUTPUT NAME>. Module outputs are listed under the outputs tab in the Terraform registry.

Module outputs are usually either passed to other parts of your configuration, or defined as outputs in your root module. You will see both uses in this tutorial.

Inside your configuration's directory, outputs.tf will need to contain:

# Output variable definitions

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
}

# Output variable definitions
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, the value of the vpc_public_subnets will come from the public_subnets output from the module named vpc, and ec2_instance_public_ips is defined as module.ec2_instances.public_ip.

»Provision infrastructure

Initialize your Terraform configuration by running terraform init.

$ terraform init
Initializing modules...
Downloading terraform-aws-modules/ec2-instance/aws 2.12.0 for ec2_instances...
- ec2_instances in .terraform/modules/ec2_instances
Downloading terraform-aws-modules/vpc/aws 2.21.0 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Installing hashicorp/aws v3.25.0...
- Installed hashicorp/aws v3.25.0 (signed by HashiCorp)

Terraform has been successfully initialized!

## ...

$ terraform initInitializing modules...Downloading terraform-aws-modules/ec2-instance/aws 2.12.0 for ec2_instances...- ec2_instances in .terraform/modules/ec2_instancesDownloading terraform-aws-modules/vpc/aws 2.21.0 for vpc...- vpc in .terraform/modules/vpc
Initializing the backend...
Initializing provider plugins...- Reusing previous version of hashicorp/aws from the dependency lock file- Installing hashicorp/aws v3.25.0...- Installed hashicorp/aws v3.25.0 (signed by HashiCorp)
Terraform has been successfully initialized!
## ...

Terraform has installed the provider and both of the modules your configuration refers to.

Now run terraform apply to create your VPC and EC2 instances:

$ terraform apply

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # module.ec2_instances.aws_instance.this[0] will be created
  + resource "aws_instance" "this" {
      + ami                          = "ami-0c5204531f799e0c6"
      + arn                          = (known after apply)
      + associate_public_ip_address  = (known after apply)
      + availability_zone            = (known after apply)

  ## ...

Plan: 22 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + ec2_instance_public_ips = [
      + (known after apply),
      + (known after apply),
    ]
  + vpc_public_subnets      = [
      + (known after apply),
      + (known after apply),
    ]

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

$ terraform apply
An execution plan has been generated and is shown below.Resource actions are indicated with the following symbols:  + create
Terraform will perform the following actions:
  # module.ec2_instances.aws_instance.this[0] will be created  + resource "aws_instance" "this" {      + ami                          = "ami-0c5204531f799e0c6"      + arn                          = (known after apply)      + associate_public_ip_address  = (known after apply)      + availability_zone            = (known after apply)
  ## ...
Plan: 22 to add, 0 to change, 0 to destroy.
Changes to Outputs:  + ec2_instance_public_ips = [      + (known after apply),      + (known after apply),    ]  + vpc_public_subnets      = [      + (known after apply),      + (known after apply),    ]
Do you want to perform these actions?  Terraform will perform the actions described above.  Only 'yes' will be accepted to approve.
  Enter a value:

You will notice that many more resources than just the VPC and EC2 instances will be created. The modules we used define what those resources are.

Respond to the prompt with yes to apply the changes and continue.

You should see the instance IP addresses in your configuration's output:

## ...

Apply complete! Resources: 22 added, 0 changed, 0 destroyed.

Outputs:

ec2_instance_public_ips = [
  "18.236.156.165",
  "52.33.233.143",
]
vpc_public_subnets = [
  "subnet-058e2353c91ca82a3",
  "subnet-043068620cd9f7b83",
]

## ...
Apply complete! Resources: 22 added, 0 changed, 0 destroyed.
Outputs:
ec2_instance_public_ips = [  "18.236.156.165",  "52.33.233.143",]vpc_public_subnets = [  "subnet-058e2353c91ca82a3",  "subnet-043068620cd9f7b83",]

»Understand how modules work

When using a new module for the first time, you must run either terraform init or terraform get to install the module. When either of these commands are run, Terraform will install any new modules in the .terraform/modules directory within your configuration's working directory. For local modules, Terraform will create a symlink to the module's directory. Because of this, any changes to local modules will be effective immediately, without having to re-run terraform get.

After following this tutorial, your .terraform/modules directory will look something like this:

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

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

»Clean up your infrastructure

Now you have seen how to use modules from the Terraform registry, how to configure those modules with input variables, and how to get output values from those modules.

Before moving on to the next tutorial, destroy the infrastructure you created by running the terraform destroy command:

$ terraform destroy
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # module.ec2_instances.aws_instance.this[0] will be destroyed

  ## ...

Plan: 0 to add, 0 to change, 22 to destroy.

Changes to Outputs:
  - ec2_instance_public_ips = [
      - "18.236.156.165",
      - "52.33.233.143",
    ] -> null
  - vpc_public_subnets      = [
      - "subnet-058e2353c91ca82a3",
      - "subnet-043068620cd9f7b83",
    ] -> null

Do 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

module.vpc.aws_route_table_association.public[1]: Destroying... [id=rtbassoc-0ce85e69f0a1e7b7d]
module.vpc.aws_route_table_association.private[0]: Destroying... [id=rtbassoc-0a3f175f31fddf938]

## ...

module.vpc.aws_internet_gateway.this[0]: Destruction complete after 15s
module.vpc.aws_vpc.this[0]: Destroying... [id=vpc-03c8212c24fec96d0]
module.vpc.aws_vpc.this[0]: Destruction complete after 1s

Destroy complete! Resources: 22 destroyed.

$ terraform destroyAn execution plan has been generated and is shown below.Resource actions are indicated with the following symbols:  - destroy
Terraform will perform the following actions:
  # module.ec2_instances.aws_instance.this[0] will be destroyed
  ## ...
Plan: 0 to add, 0 to change, 22 to destroy.
Changes to Outputs:  - ec2_instance_public_ips = [      - "18.236.156.165",      - "52.33.233.143",    ] -> null  - vpc_public_subnets      = [      - "subnet-058e2353c91ca82a3",      - "subnet-043068620cd9f7b83",    ] -> null
Do 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
module.vpc.aws_route_table_association.public[1]: Destroying... [id=rtbassoc-0ce85e69f0a1e7b7d]module.vpc.aws_route_table_association.private[0]: Destroying... [id=rtbassoc-0a3f175f31fddf938]
## ...
module.vpc.aws_internet_gateway.this[0]: Destruction complete after 15smodule.vpc.aws_vpc.this[0]: Destroying... [id=vpc-03c8212c24fec96d0]module.vpc.aws_vpc.this[0]: Destruction complete after 1s
Destroy complete! Resources: 22 destroyed.

After you respond to the prompt with yes, Terraform will destroy the infrastructure you created.

»Next steps

In this tutorial, you have learned how to:

• Use modules in your Terraform configuration
• Manage module versions
• Use the Terraform Registry
• Configure module input variables
• Use module output values

In the next tutorial, you will host a website in an S3 bucket by creating and calling a child module from the configuration you built in this tutorial.