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 and effectively.
In this tutorial, you create an EC2 instance running a pre-built webapp. You will:
- use the
templatefile
function to create auser_data
script to dynamically configure an EC2 instance with resource information from your configuration. - use the
lookup
function to pass a map output to a variable as an input. - use the
concat
function to concatenate and output multiple lists of rules to an AWS Security Group.
»Prerequisites
For this tutorial, you will need:
- an AWS account
»Clone the example repository
Clone the Learn Terraform Functions example repository. This repository contains the configuration to create and provision an EC2 instance with a bash script populated with your interpolated variables.
Navigate to the repo directory in your terminal.
»Create a bash script with templatefile
The templatefile
function fills in a file with Terraform input variables and reads the file into your configuration.
»Review the template file
Provisioning an instance with user data is a common way to quickly provision instances you create. If your user data information scripts are shared with multiple teams, it is useful to paramaterize the script with the user information by templating the script for wider use.
Open the user_data.tftpl
file. This template file is the shell script to configure and deploy an app using name and department information that Terraform will interpolate into the file from variables you will define later on. Review the script here and notice the ${department}
and ${name}
references.
The two keys in the template file, name
and department
, need to have values assigned to them in the Terraform configuration.
»Add the templatefile
function
Open the variables.tf
file in your editor to find the variables associated you will assign to the name
and department
keys in your template file.
Navigate to the Terraform configuration file and open main.tf.
Add the user_data
attribute to the aws_instance
resource block. The templatefile
function takes two arguments: the template file name and the template assignments in curly brackets ({}
).
Save your changes.
»Initialize and apply the Terraform configuration
In your terminal, initialize the directory.
Apply your configuration. Your deployment includes the network configuration, instance, and provisioning script necessary to launch the example web app.
Type yes
when prompted to confirm your changes.
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.
»Map regions to AMIs with lookup
The lookup
function retrieves the value of a single element from a map, given its key.
You will use the lookup
function to dynamically apply the region-appropriate AMI ID for the EC2 instance.
»Review the AMI variables
Open variables.tf
file. Copy and append the aws_amis
map variable block below to your variables.tf
file.
This map variable declares an available AMI for each of the three regions where you could deploy your EC2 instance. The lookup
function in the next section uses the region you choose as a key. The region key, mapped to a specific AMI ID, assigns that AMI to the instance.
»Review the main configuration
Open the main.tf
file and remove the data source for your AMI ID.
In your aws_instance
resource, change the ami
attribute to your lookup
function.
The instance
resource uses the lookup
function in a required attribute, so you must create a key and value for Terraform to apply the configuration successfully. The lookup
function arguments are the map variable, the key you want to lookup, and an optional default value.
Copy and append the ami_value
output block below to your outputs.tf
file.
This is to verify the lookup function works as expected.
Save your changes.
»Edit your region variable and observe the changes
Run terraform apply
with a command-line variable flag changing the region to us-east-2.
The new pre-apply plan should reflect this change.
Accept these changes by typing yes
when prompted.
Destroy your infrastructure.
Enter yes
when prompted to accept your changes.
»Use the concat
function to output lists of security groups
The concat
function takes two or more lists and combines them into a single list.
You will create several lists of security groups and display them as a single list as they would appear to another resource. The configuration currently contains one aws_security_group
that exposes port 8080 to everyone.
You will add another aws_security_group
that allows you to SSH into your instance in case you need to restart the service.
»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.
In main.tf
, add a new aws_security_group
resource. Copy and append the resource block below to your main.tf
file.
Create a new aws_key_pair
resource to add your newly created SSH key to the instance. Copy and append the resource block below to your main.tf
file.
In the example above, you are using a file
function. The file
function reads the contents of a file in the provided path and renders it as plaintext in your configuration file. This function does not accept interpolated values in the text and should only be used when a file already on disk is necessary for the configuration.
Edit your aws_instance
web
resource to allow this security group and the ssh key.
Save your changes.
»Add the list of Security Groups to your outputs
Open the outputs.tf
file. The vpc_security_group_ids
attribute in your aws_instance
resource compiled these values as a list. To join the ID values as a list in your outputs, and add the concat
function to display your security groups. Copy and append the output block below to your outputs.tf
file.
This will return the IDs of the security groups attached to your web instance as a list. You can use these lists as inputs in submodules.
»Apply and verify your configuration
Apply your configuration.
Type yes
when prompted to confirm your changes.
Terraform will output the security group and AMI regions as single lists.
To confirm that you have port 22 access, SSH into the instance from your terminal.
Note: It may take up to five minutes for your instance to be fully built and configured. If you receive a public key
error message, wait a couple minutes before trying again.
On your local machine, navigate to the web_public_address
in the Terraform output to verify your port 8080 security group.
»Clean up resources
After verifying that the resources were deployed successfully, run terraform destroy
to destroy them. Remember to respond to the confirmation prompt with yes
.
»Next steps
Now that you have used functions in your configuration, explore the following resources.