Terraform Docker Provider

This is an example of how to utilize Kitchen-Terraform to test a Docker container running on localhost configured with the Terraform Docker Provider.

Author: Erik R. Rygg

Updated by: Carlos Gutierrez
Requirements are a Docker host listening on the Unix socket located at: unix:///var/run/docker.sock.

The Docker container that will be tested must be running an SSH daemon in the foreground to enable the Kitchen-Terraform verifier to remotely execute tests.
To setup the project, run the following commands in the terminal: 

mkdir -p docker_provider_example/test/integration/example/controls
cd docker_provider_example
Create the

Gemfile

in the root of the project by running: 

touch Gemfile
In this file we will place the dependencies that are required for the project by copying the code below into the

Gemfile

. 

source 'https://rubygems.org/' do
  gem 'kitchen-terraform', '~> 7.0'
end
Next we to install kitchen-terraform and the other rubygems required, we also need to install bundler if it is not installed yet, by running the commands below in a terminal in the root of the project: 

gem install bundler
bundle install
Create a

.kitchen.yml

file in the root of the project. 

touch .kitchen.yml
This file brings together the Terraform module code and Inspec controls. Copy the configuration below into the

.kitchen.yml

file. 

---
driver:
  name: terraform

provisioner:
  name: terraform

verifier:
  name: terraform
  systems:
    - name: docker container
      backend: ssh
      password: root
      hosts_output: container_host
      controls:
        - operating_system
      port: 2222
    - name: localhost
      backend: local
      controls:
        - state_files

platforms:
  - name: ubuntu

suites:
  - name: example


The Kitchen-Terraform driver is enabled.


The Kitchen-Terraform provisioner is enabled.

The Kitchen-Terraform verifier is configured with two systems.

The Test Kitchen backend is configured to use SSH with password authentication to connect to the Docker container.

The container system includes a control for the operating system of the Docker container.

For each Docker host (see step 3. Create Terraform outputs), the verifier will run the control over SSH on port 2222.

The platforms provide arbitrary grouping for the test suite matrix.

The suite name corresponds to the directory containing the Inspec profile: 
test/integration/example/


Below is the example Terraform code that uses the Docker provider. The resources created by this code is what we'll be testing later on.

Create the file

versions.tf

in the root of the project. 

touch versions.tf
Add the following block of code into the file.

The configuration is restricted to Terraform versions equal to or greater than 0.14.0 and less than 2.0.0. The Docker provider is used to interact with Docker containers and images, it uses the Docker API to manage the lifecycle of Docker containers. 

# Set the required provider and versions
terraform {
  required_version = ">= 0.14.0, < 2.0.0"

  required_providers {
  # We recommend pinning to the specific version of the Docker Provider you're using
  # since new versions are released frequently
    docker = {
      source = "kreuzwerker/docker"
      version = "2.23.1"
      }
    }
  }
Create the file

main.tf

in the root of the project. 

touch main.tf
Add each of the following blocks of code into the file.

The Docker provider is configured to communicate with a Docker host listening on a Unix socket. 

provider "docker" {
  host = "unix:///var/run/docker.sock"
}
A SSH daemon Docker image from the public registry is configured as a data source. 

data "docker_registry_image" "ubuntu_sshd" {
  name = "rastasheep/ubuntu-sshd:latest"
}
A Docker image is configured on the Docker host using the data source. 

resource "docker_image" "ubuntu_sshd" {
  keep_locally = true
  name = data.docker_registry_image.ubuntu_sshd.name
  pull_triggers = [data.docker_registry_image.ubuntu_sshd.sha256_digest]
}
A Docker container based on the Docker image is configured to be running on the Docker host. The container forwards localhost:2222 to its internal SSH daemon. 

resource "docker_container" "ubuntu" {
  image = docker_image.ubuntu_sshd.latest
  must_run = true
  name = "ubuntu_container"

  ports {
    external = 2222
    internal = 22
  }
}
To assist with testing, Terraform outputs will provide the path of the backend state file and the container host name. The Kitchen-Terraform verifier can use these artifacts to validate the Terraform code.

Create the file

output.tf



touch output.tf
Add each block of code into the file. 

output "terraform state" {
  description = "The path to the backend state file"
  value = "${path.module}/terraform.tfstate.d/${terraform.workspace}/terraform.tfstate"
}

output "container_host" {
  description = "The container's host name"
  value = "localhost"
}
Refer back to the

.kitchen.yml

file and in the verifier section you will see a reference to the above container host output.

We've created the Terraform code, now it's time to create the Inspec control tests. Please see the Inspec documentation to learn more about profiles and controls.

Create a default profile file

test/integration/example/inspec.yml



touch test/integration/examples/inspec.yml
Add the block below into the file. 

---
name: default
Referring back to the

.kitchen.yml

file and inside the verifier section there is an operating_system control which we need to create.

Create the file

test/integration/example/controls/operating_system.rb

# frozen_string_literal: true

control 'operating_system' do
  describe command("lsb_release -a") do
    its('stderr') { should match /lsb_release: command not found/ }
  end

  describe command('uname -ar') do
    its('stdout') { should match(/Linux/) }
  end

  describe command("env -i bash -c '. /etc/os-release; echo $NAME'") do
    its('stdout') { should match /Ubuntu/ }
  end
end
Let's create the state_files control, which will validate the Terraform state file is created and has the proper content.

Create the file

test/integration/example/controls/state_file.rb

# frozen_string_literal: true

terraform_state = input('terraform_state', {})

control 'state_files' do
  describe 'the terraform state file' do
    subject do
      file terraform_state
    end

    it do
      is_expected.to exist
    end
  end
end


Before commencing this section of the tutorial please ensure docker is running on your machine, failure to do will mean that you will not be able to successfully run the commands.

Execute Kitchen-Terraform by running the command below in the terminal: 

bundle exec kitchen converge
This creates resources from the Terraform code in the main.tf file. Below is an example output of Kitchen-Terraform running when you use the converge command. 

-----> Starting Test Kitchen (v3.4.0)
-----> Creating <example-ubuntu>...
$$$$$$ Reading the Terraform client version...
       Terraform v0.14.0
       + provider registry.terraform.io/kreuzwerker/docker v2.23.1

       Your version of Terraform is out of date! The latest version
       is 1.3.6. You can update by downloading from https://www.terraform.io/downloads.html
$$$$$$ Finished reading the Terraform client version.
$$$$$$ Verifying the Terraform client version is in the supported interval of >= 0.11.4, < 2.0.0...
$$$$$$ Finished verifying the Terraform client version.
$$$$$$ Initializing the Terraform working directory...

       Initializing the backend...

       Initializing provider plugins...
       - Finding kreuzwerker/docker versions matching "2.23.1"...
       - Installing kreuzwerker/docker v2.23.1...
       - Installed kreuzwerker/docker v2.23.1 (self-signed, key ID BD080C4571C6104C)

       Partner and community providers are signed by their developers.
       If you'd like to know more about provider signing, you can read about it here:
       https://www.terraform.io/docs/plugins/signing.html

       Terraform has been successfully initialized!
$$$$$$ Finished initializing the Terraform working directory.
$$$$$$ Creating the kitchen-terraform-example-ubuntu Terraform workspace...
       Created and switched to workspace "kitchen-terraform-example-ubuntu"!

       You're now on a new, empty workspace. Workspaces isolate their state,
       so if you run "terraform plan" Terraform will not see any existing state
       for this configuration.
$$$$$$ Finished creating the kitchen-terraform-example-ubuntu Terraform workspace.
       Finished creating <example-ubuntu> (0m3.36s).
-----> Converging <example-ubuntu>...
$$$$$$ Reading the Terraform client version...
       Terraform v0.14.0
       + provider registry.terraform.io/kreuzwerker/docker v2.23.1

       Your version of Terraform is out of date! The latest version
       is 1.3.6. You can update by downloading from https://www.terraform.io/downloads.html
$$$$$$ Finished reading the Terraform client version.
$$$$$$ Verifying the Terraform client version is in the supported interval of >= 0.11.4, < 2.0.0...
$$$$$$ Finished verifying the Terraform client version.
$$$$$$ Selecting the kitchen-terraform-example-ubuntu Terraform workspace...
$$$$$$ Finished selecting the kitchen-terraform-example-ubuntu Terraform workspace.
$$$$$$ Downloading the modules needed for the Terraform configuration...
$$$$$$ Finished downloading the modules needed for the Terraform configuration.
$$$$$$ Validating the Terraform configuration files...
       Success! The configuration is valid.

$$$$$$ Finished validating the Terraform configuration files.
$$$$$$ Building the infrastructure based on the Terraform configuration...
       docker_image.ubuntu_sshd: Creating...
       docker_image.ubuntu_sshd: Creation complete after 0s [id=sha256:49533628fb371c9f1952c06cedf912c78a81fbe3914901334673c369376e077erastasheep/ubuntu-sshd:latest]
       docker_container.ubuntu: Creating...
       docker_container.ubuntu: Creation complete after 1s [id=b2766cde74c528e46638f5ab273476431402f7053668499145bc03a12e07291f]

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

       Outputs:

       container_host = "localhost"
       terraform_state = "./terraform.tfstate.d/kitchen-terraform-example-ubuntu/terraform.tfstate"
$$$$$$ Finished building the infrastructure based on the Terraform configuration.
$$$$$$ Reading the output variables from the Terraform state...
$$$$$$ Finished reading the output variables from the Terraform state.
$$$$$$ Parsing the Terraform output variables as JSON...
$$$$$$ Finished parsing the Terraform output variables as JSON.
$$$$$$ Writing the output variables to the Kitchen instance state...
$$$$$$ Finished writing the output variables to the Kitchen instance state.
$$$$$$ Writing the input variables to the Kitchen instance state...
$$$$$$ Finished writing the input variables to the Kitchen instance state.
       Finished converging <example-ubuntu> (0m3.32s).
-----> Test Kitchen is finished. (0m7.86s)
Now run the Kitchen-Terraform tests using: 

bundle exec kitchen verify
This executes the Inspec controls from the .kitchen.yml verifier section and will run the tests in the operating_system.rb and state_file.rb files. The output below is an example of Kitchen-Terraform running when you use the verify command. 

-----> Starting Test Kitchen (v3.4.0)
-----> Setting up <example-ubuntu>...
       Finished setting up <example-ubuntu> (0m0.00s).
-----> Verifying <example-ubuntu>...
$$$$$$ Reading the Terraform input variables from the Kitchen instance state...
$$$$$$ Finished reading the Terraform input variables from the Kitchen instance state.
$$$$$$ Reading the Terraform output variables from the Kitchen instance state...
$$$$$$ Finished reading the Terraform output variables from the Kitchen instance state.
$$$$$$ Verifying the systems...
$$$$$$ Verifying the 'docker container' system...

       Profile: default
       Version: (not specified)
       Target:  ssh://root@localhost:2222

       ✔  operating_system: Command: `lsb_release -a`
           ✔  Command: `lsb_release -a` stderr is expected to match /lsb_release: command not found/
           ✔  Command: `uname -ar` stdout is expected to match /Linux/
           ✔  Command: `env -i bash -c '. /etc/os-release; echo $NAME'` stdout is expected to match /Ubuntu/


       Profile Summary: 1 successful control, 0 control failures, 0 controls skipped
       Test Summary: 3 successful, 0 failures, 0 skipped
$$$$$$ Finished verifying the 'docker container' system.
$$$$$$ Verifying the 'terraform state' system...

       Profile: default
       Version: (not specified)
       Target:  local://

       ✔  state_files: the terraform state file
           ✔  the terraform state file is expected to exist


       Profile Summary: 1 successful control, 0 control failures, 0 controls skipped
       Test Summary: 1 successful, 0 failures, 0 skipped
$$$$$$ Finished verifying the 'terraform state' system.
$$$$$$ Finished verifying the systems.
       Finished verifying <example-ubuntu> (0m6.20s).
-----> Test Kitchen is finished. (0m7.62s)
Once you are finished running the tests with: 

bundle exec kitchen verify
Run the following in the terminal: 

bundle exec kitchen destroy
This will destroy the docker container and delete all information for that instance.