Terraform Amazon Provider

Hello! This tutorial will walk you through setting up a Terraform config to spin up an Amazon Web Services (AWS) EC2 instance using Inspec and Kitchen-Terraform from scratch.

(Note: these instructions are for Unix based systems only)

Author: Nell Shamrell-Harrington

1. Prerequisites 2. Setup development environment 3. Setup Test Kitchen 4. Writing a test

Make sure you have the following prerequisites for this tutorial

An AWS Account
An AWS Access Key ID
An AWS Secret Key
An AWS Keypair
Terraform installed
Bundler installed
Ruby >= 2.4, < 2.8
The default security group on your account must allow SSH access from your IP address.

So let's start building this config from scratch!

First, let's create a new directory for our config:

mkdir tf_aws_cluster
cd tf_aws_cluster

Now, create some skeleton terraform files:

touch main.tf variables.tf output.tf testing.tfvars

Edit the

Gemfile

vim Gemfile

Add in the Kitchen-Terraform gem like below (substituting your Ruby version if necessary):

ruby '>= 3.0'

source 'https://rubygems.org/' do
  gem 'kitchen-terraform', '~> 7.0'
end

Close and save the file then run bundler to install these gems:

bundle install

Now let's set up Test Kitchen.

Go ahead and open your

.kitchen.yml

file:

vim .kitchen.yml

Let's go ahead and add in configuration for for both Test-Kitchen and Kitchen-Terraform in the

.kitchen.yml

config file.

Kitchen-Terraform provides three plugins for use with Test-Kitchen - a driver, a provisioner, and a verifier. We will go through each of these plugins in this tutorial.

First the driver - the driver we are using is called terraform.

Edit the

.kitchen.yml

file:

---
driver:
  name: terraform
  variable_files:
    - testing.tfvars

Now let's add the provisioner. The provisioner we will use is also called terraform.

---
driver:
  name: terraform
  variable_files:
    - testing.tfvars

provisioner:
  name: terraform

Now, we need to add in a platform. Although our terraform config will determine what OS we use, we need to include at least one value here.

---
driver:
  name: terraform
  variable_files:
    - testing.tfvars

provisioner:
  name: terraform

platforms:
  - name: ubuntu

And now let's add another section, the verifier section. The verifier is what will verify whether your Test Kitchen instances match what is laid out in your inspec files.

---
driver:
  name: terraform
  variable_files:
    - testing.tfvars

provisioner:
  name: terraform

platforms:
  - name: ubuntu

verifier:
  name: terraform
  systems:
    - name: default
      controls:
        - operating_system
      backend: ssh
      user: ubuntu
      key_files:
        - ~/path/to/your/private/aws/key.pem
      hosts_output: public_dns
      reporter:
        - documentation

And let's stop and talk about what we did here - as this is where you will see some of the uniqueness of Kitchen-Terraform.

With these lines:

verifier:
  name: terraform

We have specified that we are using the terraform verifier.

And we have also specified a group of controls:

systems:
  - name: default
    controls:
      - operating_system

Our system's name is default, and we expect to find a control file called

operating_system_spec.rb

within that group.

Additionally, we have specified the ssh backend. We would like Kitchen-Terraform to ssh into an instance and run the Inspec tests there:

      backend: ssh
      user: ubuntu
      key_files:
        - ~/path/to/your/private/aws/key.pem
      hosts_output: public_dns
      reporter:
        - documentation

Kitchen-Terraform also needs to know a username, private keys, and hostnames to ssh run those specs. We have set the hosts_output key to public_dns - which is an output value we will need to add to

output.tf

in a bit. The user key specifies the username that kitchen terraform will use to ssh into the hostnames with. In this tutorial we are using Ubuntu instances and the default username is ubuntu. Finally the reporter key specifies the InSpec reporters for reporting test output. In this example, we are specifying documentation which shows the tests passed with a small summary at the end.

And, last, let's add a test suite to the

.kitchen.yml

file:

---
driver:
  name: terraform
  variable_files:
    - testing.tfvars

provisioner:
  name: terraform

platforms:
  - name: ubuntu

verifier:
  name: terraform
  systems:
    - name: default
      controls:
        - operating_system
      backend: ssh
      user: ubuntu
      key_files:
        - ~/path/to/your/private/aws/key.pem
      hosts_output: public_dns
      reporter:
        - documentation

suites:
  - name: default

Save and close the file.

Now, we have some work to do on our workstation. First, let's set up an inspec directory within our test directories

mkdir -p test/integration/default/controls

This will be our default group of tests. Now we need to provide a yml file with the name of that group within the group directory. Go ahead and create this:

vim test/integration/default/inspec.yml

And add this content:

---
name: default

Save and close the file.

Now, just one more bit of housekeeping. Our

.kitchen.yml

is expecting an output of our test kitchen instances' hostnames within the output variable, public_dns. In order to have a hostname within that public_dns variable, we need to create an EC2 instance.

First, open up the main config file:

vim main.tf

And add this content: Terraform 0.10, 0.11

provider "aws" {
  access_key = "${var.access_key}"
  secret_key = "${var.secret_key}"
  region = "${var.region}"
}

resource "aws_security_group" "allow_ssh" {
  name        = "allow_ssh"
  description = "Allow SSH inbound traffic"

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

resource "aws_instance" "example" {
  ami = "${var.ami}"
  instance_type = "${var.instance_type}"
  key_name = "${var.key_name}"
  security_groups = "${aws_security_group.allow_ssh.name]"
}

Terraform 0.12

provider "aws" {
  access_key = var.access_key
  secret_key = var.secret_key
  region     = var.region
}

resource "aws_security_group" "allow_ssh" {
  name        = "allow_ssh"
  description = "Allow SSH inbound traffic"

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

resource "aws_instance" "example" {
  ami             = var.ami
  instance_type   = var.instance_type
  key_name        = var.key_name
  security_groups = [aws_security_group.allow_ssh.name]
}

Save and close the file. Notice that we used some variable values there? We need to add these into our

variables.tf

file.

Go ahead and create it.

vim variables.tf

And add this content:

variable "access_key" {}
variable "secret_key" {}
variable "key_name" {}
variable "region" {}
variable "ami" {}
variable "instance_type" {}

And, finally, we need to add in some values for these variables.

Open up your

testing.tfvars

file:

vim testing.tfvars

And add in this content (substitute in the appropriate values for your AWS account, region, etc. key_name will be the existing key pair name already existing in AWS)

access_key = "my_aws_access_key"
secret_key = "my_aws_secret_key"
key_name = "my_aws_key_pair_name"
region = "us-east-1"
ami = "ami-fce3c696"
instance_type = "m3.medium"

Save and close the file.

Finally, let's define that output that will be expected by our

.kitchen.yml

Go ahead and open up your

output.tf

file.

vim output.tf

And add this content:

output "public_dns" {
  value = "${aws_instance.example.public_dns}"
}

Ok! Now we're ready to finally create some Test Kitchen instances!

Go ahead and run:

bundle exec kitchen converge

NOTE: If you receive the error "Error launching source instance: VPCResourceNotSpecified: The specified instance type can only be used in a VPC", check out the EC2 t2 Instance Type Requirement document.

And it should converge successfully and you should see output that includes:

Outputs:

public_dns = your_aws_instance_public_ip

Let's first try running the tests as is - even though we haven't written any yet.

bundle exec kitchen verify

And if it runs successfully, you should see output that includes:

Finished in 0.002 seconds (files took 2.54 seconds to load)
0 examples, 0 failures

Let's add some tests!

Open up the file

vim test/integration/default/controls/operating_system_spec.rb

And let's add in a very basic test to make sure we are running on an Ubuntu system.

control 'operating_system' do
  describe command('lsb_release -a') do
    its('stdout') { should match (/Ubuntu/) }
  end
end

Now save and close the file and run the test.

bundle exec kitchen verify

And hey, it passed! You should see output that includes:

Command: `lsb_release -a`
  stdout
    is expected to match /Ubuntu/

Finished in 0.23381 seconds (files took 2.62 seconds to load)
1 example, 0 failures

It's nice that it passed...but we still need to make sure that it fails to be certain it tests what we think it tests. Let's try changing our Terraform config to spin up an Amazon Linux System, rather than an Ubuntu system, and make sure that this test fails.

Go ahead and destroy your current test kitchen instances with:

bundle exec kitchen destroy

Open up your variables file

vim testing.tfvars

And change this content:

region = "us-east-1"
instance_type = "m3.medium"
ami = "ami-fce3c696"

To this content (we are changing our AMI type to be an Amazon Linux AMI within the us-east-1 AWS region.

region = "us-east-1"
instance_type = "m3.medium"
ami = "ami-6869aa05"

Now create your test kitchen instance:

bundle exec kitchen converge

Now run the tests:

bundle exec kitchen verify

Whoops! Looks like we got an error this run!

>>>>>> ------Exception-------
>>>>>> Class: Kitchen::ActionFailed
>>>>>> Message: 1 actions failed.
>>>>>>     Verify failed on instance <default-ubuntu>.  Please see
.kitchen/logs/default-ubuntu.log for more details

So let's take a look at the

.kitchen/log/default-ubuntu.log

Parsing through the output, we see this:

ERROR -- default-ubuntu: Message: Transport error, can't connect to
'ssh' backend: SSH session could not be established

This is because of the verifier in our

.kitchen.yml

verifier:
  name: terraform
  systems:
    - name: default
      controls:
        - operating_system
      hostnames: public_dns
      username: ubuntu
      reporter:
        - documentation

Notice that the username we have specified for our test is ubuntu - this is fine for an ubuntu instance, but for an Amazon Linux instance, we need to use the ec2-user username

So let's go ahead and change that, the verifier section of your

.kitchen.yml

should now look like this:

verifier:
  name: terraform
  systems:
    - name: default
      controls:
        - operating_system
      backend: ssh
      key_files:
        - ~/.ssh/ncs-laptop.pem
      hosts_output: public_dns
      user: ec2-user
      reporter:
        - documentation

Now try running the tests again:

bundle exec kitchen verify

And now we see a test failure:

Command: `lsb_release -a`
  stdout
    is expected to match /Ubuntu/ (FAILED - 1)

Failures:

  1) Command: `lsb_release -a` stdout is expected to match /Ubuntu/
     Failure/Error: DEFAULT_FAILURE_NOTIFIER = lambda { |failure, _opts| raise failure }

       expected "" to match /Ubuntu/
       Diff:
       @@ -1,2 +1,2 @@
       -/Ubuntu/
       +""
     # ./test/integration/default/controls/operating_system_spec.rb:3:in `block (3 levels) in load_with_context'

Finished in 0.26506 seconds (files took 5.52 seconds to load)
1 example, 1 failure

Failed examples:

rspec  # Command: `lsb_release -a` stdout is expected to match /Ubuntu/

Alright, that means our test is failing when it is supposed to be failing, and passing when it is supposed to pass.

Open up your

.kitchen.yml

file and change the username back to ubuntu

verifier:
  name: terraform
  systems:
    - name: default
      controls:
        - operating_system
      backend: ssh
      key_files:
        - ~/.ssh/ncs-laptop.pem
      hosts_output: public_dns
      user: ec2-user
      reporter:
        - documentation

And open up your

testing.tfvars

file and switch back to an Ubuntu AMI

region = "us-east-1"
instance_type = "m3.medium"
ami = "ami-fce3c696"

Then destroy your current kitchen instances:

bundle exec kitchen destroy

Then converge again:

bundle exec kitchen converge

And then run verify one more time, now you should see everything pass:

bundle exec kitchen verify

Huzzah! This concludes our Terraform AWS Provider walk-through tutorial.

Now, make sure to destroy your test instances

bundle exec kitchen destroy