Chrysolites Tech Academy

Infrastructure as Code: Pulumi, Terraform and the AWS CDK · Course book

Chapter 2: A Complete Environment in Terraform

Pairs with Lesson 2: Terraform and AWS: Building a Development Environment

Terraform is the most widely used infrastructure-as-code tool. You describe infrastructure in its own configuration language, HCL, and Terraform creates it on any of hundreds of platforms, from AWS and Azure to DNS providers and monitoring services, through plug-ins called providers. This chapter builds a complete, reusable development environment on AWS step by step: a private network, a subnet, a route to the internet, firewall rules, a virtual machine you can connect to, and the variables and outputs that make the whole thing adjustable. Along the way it explains Terraform's core workflow and its most important idea, the state file.

The Terraform workflow

A Terraform project is a folder of files ending in .tf. The first block names the provider, here AWS, along with the region and the credentials profile to use. Credentials belong to a dedicated AWS user created with IAM, AWS's identity service, and are stored in your local AWS configuration, never in the .tf files.

Four commands make up the everyday cycle.

CommandWhat it doesWhen to run it
terraform initDownloads the providers the configuration needs and prepares the folderOnce at the start, and after adding a provider
terraform planCompares the configuration with the current state and shows what would changeBefore every apply
terraform applyShows the plan again and, after confirmation, makes the changesWhen the plan looks right
terraform destroyRemoves everything the configuration createdWhen the environment is no longer needed

Two more commands keep things tidy. terraform fmt rewrites files in the standard layout, so that everyone's code looks the same, and terraform state list shows every resource Terraform is currently managing.

The state file, terraform.tfstate, is how Terraform remembers what it created: a record linking each resource in your configuration to the real resource's identifier in AWS. When you run plan, Terraform reads the state, asks AWS for the current details of each resource and compares both with your configuration. Without the state it could not tell whether a block of code describes something that already exists or something new. The state can contain sensitive details, so it must not be committed to a public repository; teams usually keep it in shared remote storage.

Remote state brings a second benefit: locking. If two people ran apply against the same environment at the same moment, each working from the same starting state, their changes could clash and leave the state file inconsistent. A remote backend can lock the state while one run is in progress, so the second run waits. The command terraform state show, followed by a resource address, prints everything Terraform knows about one resource, which is often the quickest way to find an identifier or address without opening the cloud console.

Building the network

Everything starts with a VPC, a virtual private cloud: your own isolated network inside AWS. It is defined by an address range in CIDR notation. A range of 10.123.0.0/16 fixes the first 16 of the 32 address bits, leaving 16 bits for addresses inside it, 2 to the power 16, which is 65,536 addresses.

resource "aws_vpc" "dev" {
  cidr_block           = "10.123.0.0/16"
  enable_dns_hostnames = true
  tags = { Name = "dev" }
}

Each resource block has a type, aws_vpc, and a name of your choosing, dev. Other resources refer to it with the expression aws_vpc.dev.id, and Terraform uses such references to work out the order in which to create things: a subnet that refers to the VPC must wait for the VPC.

Inside the VPC goes a subnet, a smaller range in one availability zone, such as 10.123.1.0/24 with its 256 addresses. Setting map_public_ip_on_launch to true gives machines in it a public address. Reaching the internet takes three more pieces. An internet gateway connects the VPC to the internet. A route table holds a route for 0.0.0.0/0, meaning "every address", pointing at that gateway. And a route table association attaches the route table to the subnet. Miss any one of the three and machines in the subnet cannot reach the outside world.

VPC 10.123.0.0/16 public subnet 10.123.1.0/24 security group: SSH from your IP only EC2 instance route table0.0.0.0/0 to IGW internetgateway yourcomputer
Figure 2.1 — The environment being built. Each box is one resource block in the Terraform configuration, and the connections between them are references.

Tags deserve a moment. Giving every resource a Name tag, and perhaps tags for the project and its owner, makes the AWS console readable and makes it possible to find, and bill, everything belonging to one environment.

A security group acts as a firewall for the machine. The sensible rule for a development server is to allow incoming SSH connections only from your own IP address, written as a single-address range such as 203.0.113.7/32, and to allow all outgoing traffic. Opening SSH to 0.0.0.0/0, the whole internet, invites constant automated login attempts.

The virtual machine

An EC2 instance needs a machine image to start from. Rather than copying an image identifier, which differs by region and changes as images are updated, a data source asks AWS to look up the most recent Ubuntu image published by its official owner. Data sources read information without creating or changing anything in the account.

To log in, the instance needs a key pair. You generate a key pair on your own computer, and a Terraform resource uploads only the public half to AWS, using the file function to read it from disk. The private key never leaves your machine.

The instance block then ties everything together: the image from the data source, an instance size such as t2.micro, the key pair, the security group and the subnet. A user data script, read in with the file function, runs on the machine's first boot to install software such as Docker, so the server arrives ready to use.

A final convenience adds the new server to your own SSH configuration, so you can connect by name. Terraform's provisioner feature runs a command on your computer after the instance is created, and the templatefile function fills a small script template with the instance's address. Provisioners are a last resort for tasks that cannot be expressed as resources, and changes to them do not show up in a plan; to rerun one you replace the instance deliberately with terraform apply -replace.

Plan, then read. In a plan, + means create, ~ means update in place and -/+ means destroy and recreate. A -/+ next to a server means it will be replaced, losing anything stored only on it.

Variables, conditions and outputs

Hard-coding values such as the operating system of your own computer makes a configuration rigid. Variables make it adjustable. A variable is declared with an optional type and default, and used as var.name. Values can be supplied in several ways, and when more than one supplies the same variable, the later in Table 2.2 wins.

Source of a valuePriority
The default in the variable declarationLowest
An environment variable named TF_VAR_ followed by the variable nameHigher
A terraform.tfvars fileHigher
Files ending in .auto.tfvarsHigher
-var or -var-file options on the command lineHighest

A conditional expression chooses between values: var.host_os == "windows" ? "powershell" : "bash" picks the right command interpreter for the provisioner depending on the operating system. Finally, an output prints a useful value after apply, such as the instance's public IP address, so you do not need to look it up in the console. The finished configuration can be destroyed and recreated identically in minutes, which is exactly what a development environment should allow.

Variables can carry types and checks. Declaring a variable as type string, number, bool, list or map makes Terraform reject values of the wrong kind before anything is created, and a validation block can enforce rules such as "the instance size must be one of these three", with a helpful message when it is not. Values that should never be printed, such as passwords, can be marked sensitive so that Terraform hides them in its output.

As configurations grow, repeated groups of resources are packaged into modules: folders of Terraform code with their own variables and outputs, used like functions. A team might write one module describing a standard network and reuse it for every environment, passing in only the address range and a name. Public registries offer ready-made modules for common patterns, which saves writing the same blocks again.

Counting resources makes the scale clear: a VPC, a subnet, an internet gateway, a route table, a route, an association, a security group, a key pair and an instance make 9 resources, all created by one apply and removed by one destroy.

Check your understanding

  • What is the difference between terraform plan and terraform apply?
  • Why does Terraform need a state file?
  • How many addresses does a /20 range contain? (Answer: 32 − 20 = 12 bits, so 4,096.)
  • Name the three resources needed for a subnet to reach the internet.
  • Why should SSH be allowed only from your own IP address?
  • A variable has a default of "t2.micro", terraform.tfvars sets "t3.small", and the command line passes -var for "t3.medium". Which value is used? (Answer: t3.medium.)
  • What does -/+ mean in a plan, and why is it worth noticing?

Install Chrysolites Tech Academy

Android / Chrome / Edge: open the browser menu and choose Install app or Add to Home screen.

iPhone / iPad (Safari): tap the Share button, then Add to Home Screen.