Perform dynamic operations with functions
The Terraform configuration language allows you to write declarative expressions to create infrastructure. While the configuration language is not a programming language, you can use several built-in functions to perform operations dynamically.
In this tutorial, you will:
- use the
templatefile
function to dynamically create an EC2 instance user data script. - use the
lookup
function to reference values from a map. - use the
file
function to read the contents of a file.
Prerequisites
You can complete this tutorial using the same workflow with either Terraform Community Edition or HCP Terraform. HCP Terraform is a platform that you can use to manage and execute your Terraform projects. It includes features like remote state and execution, structured plan output, workspace resource summaries, and more.
Select the HCP Terraform tab to complete this tutorial using HCP Terraform.
This tutorial assumes that you are familiar with the Terraform workflow. If you are new to Terraform, complete the [Get Started tutorials(/collections/terraform/aws-get-started) first.
In order to complete this tutorial, you will need the following:
- Terraform v1.2+ installed locally.
- An AWS account with local credentials configured for use with Terraform.
Clone the example repository
Clone the Learn Terraform Functions example repository. This repository contains example configuration for you to use to practice using functions to create dynamic EC2 configuration.
Navigate to the repository directory in your terminal.
Use templatefile
to dynamically generate a script
AWS lets you configure EC2 instances to run a user-provided script -- called a user-data script -- at boot time. You can use Terraform's templatefile
function to interpolate values into the script at resource creation time. This makes the script more adaptable and re-usable.
Open the user_data.tftpl
file, which will be the user data script for your EC2 instance. This template file is a shell script to
configure and deploy an application. Notice the ${department}
and ${name}
references -- Terraform will interpolate these values using the templatefile
function.
Next, open the variables.tf
file. This file includes definitions for the user_name
and user_department
input variables, which the configuration uses to set the values for the corresponding template file keys.
Now open main.tf
. Add the user_data
attribute to the aws_instance
resource block as shown below. The templatefile
function takes two arguments: the template file name and a map of template value assignments.
Save your changes.
Create infrastructure
Initialize this configuration.
Apply your configuration. Respond yes
to confirm the operation.
Terraform provisions your network configuration, instance, and provisioning script necessary to launch the example web app.
Your web_public_address
output in your terminal is the address of your web app instance. Navigate to that address in your web browser to verify your configuration.
Destroy your infrastructure before moving to the next section.
Enter yes
when prompted to accept your changes.
Use lookup
function to select AMI
The lookup
function retrieves the value of a single element from a map, given its key.
Add the following configuration to your variables.tf
file to declare a new input variable.
This input variable includes a default value of a map of region-specific AMI IDs for three regions.
Now, open the main.tf
file and remove the data source for your AMI ID.
In your aws_instance
resource, update the ami
attribute to use the lookup
function.
The ami
is a required attribute for the aws_instance
resource, so the lookup
function must return a valid value for Terraform to apply your configuration. The lookup
function arguments are a map, the key to access in the map, and an optional default value in case the key does not exist.
Next, add the following configuration for an ami_value
output to your outputs.tf
file. This output lets you verify the AMI returned by the lookup
function.
Now run terraform plan
to review the execution plan for these changes, using
a command-line variable flag to set the region to us-east-2.
The output now
includes the selected AMI ID, which Terraform determined using the lookup
function.
Use the file
function
In this section, you will create a new security group to allow SSH ingress traffic to your instance and configure the instance with an SSH key.
Create an SSH key and a security group resource
Create a local SSH key to pair with the new instance you create so that you can connect securely to your instance.
Generate a new SSH key called ssh-key
. The argument provided with the -f
flag creates the key in the current directory and creates two files called ssh_key
and ssh_key.pub
. Change the placeholder email address to your email address.
When prompted, press enter to leave the passphrase blank on this key.
Next, add the following configuration to main.tf
to create a new security group and AWS key pair.
In main.tf
, add a new aws_security_group
resource. Copy and append the resource block below to your main.tf
file.
This configuration uses the file
function to read
the contents of a file to configure an SSH key pair. The file
function does
not interpolate values into file contents; you should only use it with files
that do not need modification.
Next, edit your aws_instance.web
resource to use the new security group and key pair. Be sure to save your changes.
Warning
This configuration enables public SSH traffic to the example instance for tutorial purposes. Lock down access to your services in production environments.
Apply your configuration to create the resources. Enter yes
when prompted to confirm the operation.
To confirm that your instance now accepts traffic on port 22, SSH into it from your terminal.
Note
It may take up to 5 minutes to provision your instance. If you receive a public key
error message, wait a couple minutes before trying again.
Clean up resources
Now that you have completed this tutorial, destroy the resources to avoid incurring unnecessary costs. Respond yes
when prompted to confirm the operation.
If you used HCP Terraform for this tutorial, after destroying your resources, delete the learn-terraform-functions
workspace from your HCP Terraform organization.
Next steps
In this tutorial, you learned how to make your Terraform configuration dynamic
by using built-in functions. You used the lookup
function to access values
from maps based on an input variable, the templatefile
function to generate a
script with interpolated values, and the file
function to use the
contents of a file as-is within configuration.
Check out the following resources to learn more about how to make your Terraform configuration more flexible:
- Review the functions documentation to learn more about the functions Terraform supports.
- Learn how to manage similar resources using
count
. - Learn how to create dynamic expressions in your configuration.
- Use
for_each
to dynamically configure your resources based on a map.