Kitchen-Terraform enables verification of Terraform state.
Kitchen-Terraform provides a set of Test Kitchen plugins which enable a system to use Test Kitchen to converge a Terraform configuration and verify the resulting Terraform state with InSpec controls.
As Kitchen-Terraform integrates several distinctive technologies in a nontrivial manner, reviewing the documenation of each of the aforementioned products is strongly encouraged.
Kitchen-Terraform integrates with the Terraform command-line interface to implement a Test Kitchen workflow for Terraform modules.
Installation instructions can be found in the Terraform: Install Terraform article.
Kitchen-Terraform supports versions of Terraform in the interval of
>= 0.10.2, < 0.12.0.
tfenv can be used to manage versions of Terraform on the system.
Kitchen-Terraform is written in Ruby which requires an interpreter to be installed on the system.
Installation instructions can be found in the Ruby: Installing Ruby article.
Kitchen-Terraform aims to support all versions of Ruby that are in
"normal" or "security" maintenance, which is currently
the interval of >= 2.2, < 2.5.
rbenv can be used to manage versions of Ruby on the system.
Each version of Kitchen-Terraform is published as a Ruby gem to RubyGems.org which makes them readily available for installation on a system.
To install a version of Kitchen-Terraform using the default Ruby package manager, RubyGems, run a command like the following example.
Installing Kitchen-Terraform with RubyGems
gem install kitchen-terraform --version 3.0.0More information can be found in the RubyGems: Installing Gems article.
Bundler can also be used to manage versions of Kitchen-Terraform on the system in a manner that is easily reproducible on other systems.
First, create a Gemfile with contents like the following example. The
pessimistic pinning of the version is recommended to benefit from
the semantic versioning of the Ruby gem.
Defining Kitchen-Terraform as a dependency for Bundler
source "https://rubygems.org/" do
gem(
"kitchen-terraform",
"~> 3.0"
)
endSecond, run the following command.
Installing Kitchen-Terraform with Bundler
bundle installMore information can be found in the Bundler: In Depth article.
Kitchen-Terraform provides three Test Kitchen plugins which must be configured in a Test Kitchen configuration file in order to successfully test Terraform configuration.
The Terraform driver manages the state of the Terraform root module.
The Terraform provisioner uses the Terraform driver to apply changes to the Terraform state.
The Terraform verifier uses InSpec to verify the Terraform state.
More information can be found in the Ruby gem documentation.
Assume there is a system which has Kitchen-Terraform and Docker installed.
Assume the working directory on said system a hierarchy like the following examples.
Directory hierarchy
.
├── .kitchen.yml
├── main.tf
└── test
└── integration
└── example
├── controls
│ ├── operating_system.rb
└── inspec.yml
./.kitchen.yml
driver:
name: terraform
provisioner:
name: terraform
transport:
name: ssh
password: root
verifier:
name: terraform
groups:
- name: container
port: 2222
username: root
platforms:
- name: ubuntu
suites:
- name: example./main.tf
provider "docker" {
host = "unix://localhost/var/run/docker.sock"
}
data "docker_registry_image" "ubuntu" {
name = "rastasheep/ubuntu-sshd:latest"
}
resource "docker_image" "ubuntu" {
name = "${data.docker_registry_image.ubuntu.name}"
pull_triggers = ["${data.docker_registry_image.ubuntu.sha256_digest}"]
}
resource "docker_container" "ubuntu" {
image = "${docker_image.ubuntu.name}"
must_run = true
name = "ubuntu_container"
ports {
external = 2222
internal = 22
}
}./test/integration/example/inspec.yml
name: example./test/integration/example/controls/operating_system.rb
# frozen_string_literal: true
control "operating_system" do
describe "the operating system" do
subject do
command("lsb_release -a").stdout
end
it "is Ubuntu" do
is_expected.to match /Ubuntu/
end
end
endRunning the following command would initialize the working directory for Terraform, create a Docker container by applying the configuration file, and verify that the container is running Ubuntu.
Verifying with Kitchen-Terraform
$ kitchen test
-----> Starting Kitchen...
...
$$$$$$ Running command `terraform init...`
...
$$$$$$ Running command `terraform apply...`
...
docker_container.ubuntu: Creation complete after 1s...
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
...
Finished converging <example-ubuntu>...
...
-----> Verifying <example-ubuntu>...
Verifying host 'localhost' of group 'container'
...
✔ operating_system: the operating system is Ubuntu
...
Profile Summary: 1 successful control, 0 control failures, 0 controls skipped
...More information can be found on the Kitchen-Terraform Tutorials page.
Kitchen-Terraform thrives on community contributions.
Information about contributing to Kitchen-Terraform can be found in the Contributing document.
Pull requests to Kitchen-Terraform are always welcome!
Information about developing Kitchen-Terraform can be found in the Developing document.
Kitchen-Terraform adheres to semantic versioning and documents all significant changes accordingly.
Information about changes to Kitchen-Terraform can be found in the Changelog.
Kitchen-Terraform is maintained by New Context.
kitchen-terraform@newcontext.com
Kitchen-Terraform is distributed under the Apache License.