Part I - Local Basics

This part goes over the very basic concepts that you use when Terraforming.

In it we cover:

• Resources
• Planning
• State files
• Data sources
• Ouptut
• Destruction

You will be using only local resources (such as local files on the host you run Terraform on) so that these concepts get fully embdedded. It won’t necessarily look to you like the Terraform you might use at work, but it’s fundamenally the same and will give you a good grounding to go further.

Terraform 101

This first section will take you through one of the simplest possible Terraform scripts.

It will create a file in the folder you run it in, and is completely safe.

You will cover the following concepts:

• Terraform resources
• The path.module variable
• The terraform init command
• The terraform apply command

We’ll also briefly discuss Terraform’s relationship to traditional configuration management tools like Chef, Puppet, and Ansible. By the end you should begin to have a much clearer idea of what Terraform does, and how.

How Important is this Section?

This section is essential, as it introduces core Terraform concepts and commands.

Your First Terraform Module

1 $ mkdir -p ltthw_resources
2 $ cd ltthw_resources

You’ve created and moved into a folder where you can safely do some work with Terraform without fear of breaking anything else. The other chapters in this book will follow the same pattern.

Now you’re going to create a file called hello_local_file.tf. If the following commands don’t work for you, check you’ve got the pre-requisites listed at the start of the book.

If you don’t understand it, don’t worry: just type it in. It’s an unambiguous method to edit a file in a bash shell without using an external editor.

3 $ cat > hello_local_file.tf << 'EOF'
4 > resource "local_file" "hello_local_file" {
5 >     content     = "Hello terraform local!"
6 >     filename = "${path.module}/hello_local_file.txt"
7 > }
8 > EOF

Stop here and think about what you expect that file to do when Terraform ‘runs’ it. Have a guess as to what a resource is, and what ${path.module} does.

If you’re not sure, do a Google search and see what turns up. Don’t worry about finding the answer and being right, just get a feel for what looking things up in Terraform looks like. You might find resources you want to look at later.

Done that? OK, now type:

9 $ ls -1a

You should see something like this:

.
..
hello_local_file.tf

The . represents the current directory, and the .. represents the parent directory. These are virtual files put in every folder in the filesystem so you can always refer to the parent folder or the current one. The other file is the one just created.

We’re checking what’s in the folder to show what happens when we bring Terraform in:

10 $ terraform init

You’ll see some output as Terraform initialises the environment. If you run ls -1a again:

11 $ ls -1a

You’ll see an extra .terraform folder.

.
..
.terraform
hello_local_file.tf

Have a root around that folder if you’re so inclined. Terraform has downloaded the local_file plugin and placed it in this folder.

Now we’re ready to ‘run’ this module, and create the local file:

12 $ terraform apply

Now (and whenever you run this command and there’s something to change), you will get a prompt asking you if you are sure you want to go ahead.

You will need to type yes to approve.

Before you do that, read the output carefully. It explains a phase called ‘plan’ where Terraform takes your module and compares its desired state with what it thinks is the current state in the ‘real’ world. We will cover plans later. Finally, you get a summary of the plan:

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

Because there’s something to change, you get the prompt asking you if you are sure you want to go ahead and make a change. Type yes to continue:

13 Enter a value: yes

You should have seen the output at the end which tells you what was changed:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Again, read the output carefully before running ls -1a again:

14 $ ls -1a

.
..
.terraform
hello_local_file.txt
hello_local_file.tf
terraform.tfstate

Now you see that there’s two new files in the folder: terraform.tfstate and the hello_local_file.txt we created. We will cover the terraform.tfstate file later.

Now remove the hello_local_file.txt file and re-run terraform apply.

What do you think will happen?

15 $ rm hello_local_file.txt
16 $ ls -1a
17 $ terraform apply
18 $ ls -1a

Did it do what you expected? What if you change the file?

19 $ echo 'I just moved in' >> hello_local_file.txt
20 $ cat hello_local_file.txt
21 $ terraform apply
22 $ cat hello_local_file.txt

What happened?

Terraform vs ‘Traditional’ Configuration Management Tools

If you’ve used configuration management tools like Chef, Puppet, or Ansible before, then you may notice that Terraform can do similar things. It can examine the state of something and bring its state into line with the state that was specified, as you saw above.

There are key differences between Terraform and other tools, and these spring from Terraform being designed for infrastructure rather than software configuration.

When managing files (as we saw here), this looks pretty similar to configuration management tools. As we move to managing things such as load balancers, virtual private networks, or fleets of machines, the design decisions of Terraform make it behave in different ways to those tools.

For example, configuration management tools are usually agent-based (ie runs on the machine it’s managing), or ssh-based (ie goes to the machine it’s managing and does work on it). In other words, they are managing from ‘within’ the system they are affecting. Terraform, by contrast, must manage ‘from outside’, as (normally) the management takes place via a remote API.

Fundamentally, though, it’s worth keeping in mind that Terraform is a configuration management tool, but designed as one that is for what your software runs on, rather than for what software runs where.

What You Learned

You’ve just written and run your first Terraform module.

It might not have been what you expected, in that you affected a local file with your module rather than some cloud infrastructure, like an AWS EC2 instance. This is deliberate: the point of this book is to show you how Terraform works in simple ways so that you grasp the key concepts as quickly as possible. Then you can apply the same concepts to your infrastructure.

Using examples like this, you will gain the knowledge needed to write, debug, explain and maintain Terraform recipes in the real world.

Later you will create and destroy infrastructure items on AWS, but only when that helps show up some key point about Terraform itself.

In this section you learned about:

• Terraform resources
• What the terraform init command does
• The files terraform init creates
• What the terraform apply command does

Cleanup

To clean up what you just did, run:

23 $ terraform destroy -auto-approve
24 $ cd ..
25 $ rm -rf ltthw_resources

What Next?

In the next section you look more closely at Terraform’s state file, which keeps track of the resources the module is concerned with.

Exercises

1) Read the Terraform documentation on the init and apply commands.

2) Research some of the Terraform resources and what they manage.