This article guides you through the process of installing Terraform, and running Terraform on your AWS environment for the first time. There’s plenty you need to know to prevent destroying your (or someone else’s) network and resources. I’ve added those issues and solutions to the bottom of this article.
Install Terrafrom:
# Ubuntu apt install terraform # Redhat yum install terraform
Create a new directory to work in. This is just for convenience.
mkdir ~/TerraformProject cd ~/TerraformProject
Now we need to create our manifest file. This file is like a recipe. It tells Terraform what we want created.
vi main.tf
The manifest file is in JSON format. It’s simple to work with. The following Terraform manifest tells Terraform to create a new VPC (Virtual Private Cloud). The first segment of JSON says “our target is AWS”. The second segment says “this is our region and AWS login credentials. The third segment says “Create the VPC”.
# Where we're deploying to.
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "3.47.0"
}
}
}
# Credentials and the default region.
# For AWS, this is an IAM key and secret.
provider "aws" {
region = "ap-southeast-2"
access_key = "XXXX"
secret_key = "YYYY"
}
# The name of the VPC we're creating. If it already exists, ignore it.
# We also decide on our network structure. Our subnets will be derived from this network.
resource "aws_vpc" "my_vpc" {
cidr_block = "10.2.0.0/16"
enable_dns_hostnames = true
tags = {
Name = "my_vpc"
Terraform = "true"
}
}
If we run Terraform on the above, we’ll get a new VPC in our AWS account. For this command to work, you need to be in the same directory as the “main.tf” file.
IMPORTANT: The first time you plan to run a manifest, you need to first initialise. This is per directory. For example, if you have two different Terraform projects, create directories for each. Ie “~/terraform/myProject1” and “~/terraform/myProject2”. For each project, you need to run the following command from that directory.
cd ~/terraform/myProject1 terraform init
When we’re ready to run Terraform, we issue the following command from the same directory as the “main.tf” file.
terraform apply
Terraform will give you plenty of output form the above command. The very bottom asks you to enter “yes” to confirm you want to proceed. It’s important that you read the output from Terraform because it’s telling you what it wants to go.
For example, here’s some output prior to me entering “yes” to proceed with the actions. It’s saying what it’s going to do. In this case, it’s going to add 2 resources. This looks safe.
... Plan: 2 to add, 0 to change, 0 to destroy. ...
If we proceed, we can then check our AWS account and we should see our new VPC. Now it’s time to remove our new VPC. Terraform calls this action “destroy” and some people refer to it as “tearing down” the environment. Either way, it deletes everything that it formally created.
terraform destroy
Again, Terraform gives us a summary of everything it’s going to do. Again, pay attention. We need to enter “yes” to confirm we want to proceed. And again we see a one liner of what it’s going to do. Notice it’s not going to “add” anything this time, it’s going to “destroy” 2 resources.
... Plan: 0 to add, 0 to change, 2 to destroy. ...
IMPORTANT:
- If you’re like me, when first using Terraform, you’re concerned that Terraform is going to (or could) destroy things we don’t want it to destroy. Here’s the rule: Terraform tracks what it creates so it knows what it controls, and therefore it knows what it can destroy (delete) without touching anything else.
- If you modify a resource that Terraform created, the next time you run Terraform, it will complain about an inconsistency (Terraform’s state record differs from the actual resources). To prevent this from being a problem, if you create it with Terraform, don’t manually change it unless you’re prepared to deal with the inconsistency.
- Consider that you use Terraform to create the VPC above (in this article), and then you add an ec2 to the VPC, and then you tell Terraform to destroy the VPC, you will get an error because the ec2 is not known by Terraform and the ec2 relies on the VPC existing – AWS won’t allow the EC2 to exist in a VPC that doesn’t exist.
- Consider that you use Terraform to create an ec2, then you expand the hard disk of that ec2, Terraform will see that as a problem. Terraform will try to solve that problem by destroying that ec2, and then recreating it with the correct (according to the Terraform manifest file) disk size. That results in loss of data.
- However, if you run Terraform once, and then again, it will see that everything is how it should be, and no changes will be made. Provided that the actual environment matches Terraform’s state records.