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 and effectively.

In this tutorial, you create an EC2 instance running a pre-built webapp. You will:

• use the templatefile function to create a user_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.

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

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

Navigate to the repo directory in your terminal.

$ cd learn-terraform-functions

$ cd learn-terraform-functions

»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.

#!/bin/bash

# Install necessary dependencies
sudo DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" dist-upgrade
sudo apt-get -y -qq install curl wget git vim apt-transport-https ca-certificates
sudo add-apt-repository ppa:longsleep/golang-backports -y
sudo apt -y -qq install golang-go

# Setup sudo to allow no-password sudo for your group and adding your user
sudo groupadd -r ${department}
sudo useradd -m -s /bin/bash ${name}
sudo usermod -a -G ${department} ${name}
sudo cp /etc/sudoers /etc/sudoers.orig
echo "${name} ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/${name}

# Create GOPATH for your user & download the webapp from github
sudo -H -i -u ${name} -- env bash << EOF
cd /home/${name}
export GOROOT=/usr/lib/go
export GOPATH=/home/${name}/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
go get -d github.com/hashicorp/learn-go-webapp-demo
cd go/src/github.com/hashicorp/learn-go-webapp-demo
go run webapp.go
EOF

#!/bin/bash

# Install necessary dependencies
sudo DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" dist-upgrade
sudo apt-get -y -qq install curl wget git vim apt-transport-https ca-certificates
sudo add-apt-repository ppa:longsleep/golang-backports -y
sudo apt -y -qq install golang-go

# Setup sudo to allow no-password sudo for your group and adding your user
sudo groupadd -r ${department}
sudo useradd -m -s /bin/bash ${name}
sudo usermod -a -G ${department} ${name}
sudo cp /etc/sudoers /etc/sudoers.orig
echo "${name} ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/${name}

# Create GOPATH for your user & download the webapp from github
sudo -H -i -u ${name} -- env bash << EOF
cd /home/${name}
export GOROOT=/usr/lib/go
export GOPATH=/home/${name}/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
go get -d github.com/hashicorp/learn-go-webapp-demo
cd go/src/github.com/hashicorp/learn-go-webapp-demo
go run webapp.go
EOF

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.

variable "user_name" {
  description = "The user creating this infrastructure"
  default     = "terraform"
}

variable "user_department" {
  description = "The organization the user belongs to: dev, prod, qa"
  default     = "learn"
}

variable "user_name" {
  description = "The user creating this infrastructure"
  default     = "terraform"
}

variable "user_department" {
  description = "The organization the user belongs to: dev, prod, qa"
  default     = "learn"
}

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 ({}).

##...
resource "aws_instance" "web" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
  vpc_security_group_ids      = [aws_security_group.sg_8080.id]
  associate_public_ip_address = true
+ user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
}
##...

##...
resource "aws_instance" "web" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
  vpc_security_group_ids      = [aws_security_group.sg_8080.id]
  associate_public_ip_address = true
+ user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
}
##...

Save your changes.

»Initialize and apply the Terraform configuration

In your terminal, initialize the directory.

$ terraform init

$ terraform init

Apply your configuration. Your deployment includes the network configuration, instance, and provisioning script necessary to launch the example web app.

$ terraform apply

$ terraform apply

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.

$ terraform destroy

$ terraform destroy

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.

variable "aws_amis" {
  type = map
  default = {
    "us-east-1" = "ami-0739f8cdb239fe9ae"
    "us-west-2" = "ami-008b09448b998a562"
    "us-east-2" = "ami-0ebc8f6f580a04647"
  }
}

variable "aws_amis" {
  type = map
  default = {
    "us-east-1" = "ami-0739f8cdb239fe9ae"
    "us-west-2" = "ami-008b09448b998a562"
    "us-east-2" = "ami-0ebc8f6f580a04647"
  }
}

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.

- data "aws_ami" "ubuntu" {
- most_recent = true

- filter {
-  name = "name"
-  values = ["ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-*"]
- }

- filter {
-   name = "virtualization-type"
-   values = ["hvm"]
-  }
- owners = ["099720109477"] # Canonical
- }

- data "aws_ami" "ubuntu" {
- most_recent = true

- filter {
-  name = "name"
-  values = ["ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-*"]
- }

- filter {
-   name = "virtualization-type"
-   values = ["hvm"]
-  }
- owners = ["099720109477"] # Canonical
- }

In your aws_instance resource, change the ami attribute to your lookup function.

##...
resource "aws_instance" "web" {
- ami                         = data.aws_ami.ubuntu.id
+ ami                         = lookup(var.aws_amis, var.aws_region)
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
  vpc_security_group_ids      = [aws_security_group.sg_8080.id]
  associate_public_ip_address = true
  user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
}

##...
resource "aws_instance" "web" {
- ami                         = data.aws_ami.ubuntu.id
+ ami                         = lookup(var.aws_amis, var.aws_region)
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
  vpc_security_group_ids      = [aws_security_group.sg_8080.id]
  associate_public_ip_address = true
  user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
}

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.

output "ami_value" {
  value = lookup(var.aws_amis, var.aws_region)
}

output "ami_value" {
  value = lookup(var.aws_amis, var.aws_region)
}

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.

$ terraform apply -var "aws_region=us-east-2"

$ terraform apply -var "aws_region=us-east-2"

The new pre-apply plan should reflect this change.

Plan: 7 to add, 0 to change, 1 to destroy.

Changes to Outputs:
  ~ ami_value              = "ami-0739f8cdb239fe9ae" -> "ami-0ebc8f6f580a04647"
  ~ web_public_address     = "3.85.242.102:8080" -> (known after apply)
  ~ web_public_ip          = "3.85.242.102" -> (known after apply)

Plan: 7 to add, 0 to change, 1 to destroy.

Changes to Outputs:
  ~ ami_value              = "ami-0739f8cdb239fe9ae" -> "ami-0ebc8f6f580a04647"
  ~ web_public_address     = "3.85.242.102:8080" -> (known after apply)
  ~ web_public_ip          = "3.85.242.102" -> (known after apply)

Accept these changes by typing yes when prompted.

Destroy your infrastructure.

$ terraform destroy -var "aws_region=us-east-2"

$ terraform destroy -var "aws_region=us-east-2"

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.

$ ssh-keygen -C "your_email@example.com" -f ssh_key

$ ssh-keygen -C "your_email@example.com" -f ssh_key

In main.tf, add a new aws_security_group resource. Copy and append the resource block below to your main.tf file.

resource "aws_security_group" "sg_22" {
  name = "sg_22"
  vpc_id = aws_vpc.vpc.id

  ingress {
    from_port = 22
    to_port  = 22
    protocol  = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_security_group" "sg_22" {
  name = "sg_22"
  vpc_id = aws_vpc.vpc.id

  ingress {
    from_port = 22
    to_port  = 22
    protocol  = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

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.

resource "aws_key_pair" "ssh_key" {
  key_name = "ssh_key"
  public_key = file("ssh_key.pub")
}

resource "aws_key_pair" "ssh_key" {
  key_name = "ssh_key"
  public_key = file("ssh_key.pub")
}

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.

resource "aws_instance" "web" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
- vpc_security_group_ids      = [aws_security_group.sg_8080.id]
+ vpc_security_group_ids      = [aws_security_group.sg_22.id, aws_security_group.sg_8080.id]
  associate_public_ip_address = true
  user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
+ key_name                    = aws_key_pair.ssh_key.key_name
}

resource "aws_instance" "web" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = "t2.micro"
  subnet_id                   = aws_subnet.subnet_public.id
- vpc_security_group_ids      = [aws_security_group.sg_8080.id]
+ vpc_security_group_ids      = [aws_security_group.sg_22.id, aws_security_group.sg_8080.id]
  associate_public_ip_address = true
  user_data                   = templatefile("user_data.tftpl", { department = var.user_department, name = var.user_name })
+ key_name                    = aws_key_pair.ssh_key.key_name
}

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.

output "web_security_group_ids" {
  value = concat([aws_security_group.sg_22.id, aws_security_group.sg_8080.id])
}

output "web_security_group_ids" {
  value = concat([aws_security_group.sg_22.id, aws_security_group.sg_8080.id])
}

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.

$ terraform apply

$ terraform apply

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.

$ ssh ubuntu@$(terraform output -raw web_public_ip) -i ssh_key

$ ssh ubuntu@$(terraform output -raw web_public_ip) -i ssh_key

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.

$ terraform destroy

$ terraform destroy

»Next steps

Now that you have used functions in your configuration, explore the following resources.

• Functions documentation
• Variables documentation
• Resources documentation