Kitchen-Terraform Logo Kitchen-Terraform

Kitchen-Terraform enables verification of Terraform state.

Gem version Gem downloads version Gem downloads total

Build status Test coverage Maintainability Dependencies

Gitter chat

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 documentation 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.11.4, < 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.3, < 2.6.

rbenv can be used to manage versions of Ruby on the system.

Kitchen-Terraform Ruby Gem

Each version of Kitchen-Terraform is published as a Ruby gem to which makes them readily available for installation on a system.


Bundler should be used to manage versions of Kitchen-Terraform on the system. Using Bundler provides easily reproducible Ruby gem installations that can be shared with 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 in a Gemfile

source "" do
    "~> 4.0"

Second, run the following command.

Installing Kitchen-Terraform with Bundler

bundle install

The preceding command will create a Gemfile.lock comprising a list of the resolved Ruby gem dependencies.

More information can be found in the Bundler: In Depth article.


RubyGems, the default Ruby package manager, can also be used to install a version of Kitchen-Terraform by running a command like the following example.

Installing Kitchen-Terraform with RubyGems

gem install kitchen-terraform --version 4.0.0

This approach is not recommended as it requires more effort to install the gem in a manner that is reproducible and free of dependency conflicts.

More information can be found in the RubyGems: Installing Gems 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.


This example demonstrates how to test a simple Terraform configuration which utilizes the Docker provider.

The test system is assumed to be running Ubuntu 17.04.

Terraform, Ruby, and Bundler are assumed to have been installed on the test system as described in the Installation section.

The Docker Community Edition is assumed to have been installed on the test system.

The working directory on the test system is assumed to contain a hierarchy of files comprising the following blocks.

Directory hierarchy

├── .kitchen.yml
├── Gemfile
└── test
    └── integration
        └── example
            ├── controls
            │   ├── operating_system.rb
            └── inspec.yml


source ""

gem 'kitchen-terraform'

./.kitchen.yml (Test Kitchen configuration)

  name: terraform

  name: terraform

  name: terraform
    - name: container
      backend: ssh
      hosts_output: container_hostname
      password: root
      port: 2222
      user: root

  - name: ubuntu

  - name: example


provider "docker" {
  host    = "unix://localhost/var/run/docker.sock"

data "docker_registry_image" "ubuntu" {
  name = "rastasheep/ubuntu-sshd:latest"

resource "docker_image" "ubuntu" {
  name          = "${}"
  pull_triggers = ["${data.docker_registry_image.ubuntu.sha256_digest}"]

resource "docker_container" "ubuntu" {
  image    = "${}"
  must_run = true
  name     = "ubuntu_container"

  ports {
    external = 2222
    internal = 22


output "container_hostname" {
  description = "The hostname of the container."
  value       = ""


name: example


# frozen_string_literal: true

control "operating_system" do
  describe "the operating system" do
    subject do
      command("cat /etc/os-release").stdout

    it "is Ubuntu" do match /Ubuntu/

Running 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

$ bundle install
$ bundle exec 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 system '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.


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.

New Context logo

Twitter logo @NewContext

LinkedIn logo New Context

GitHub logo @NewContext

Email logo [email protected]

Email logo [email protected]


Kitchen-Terraform is distributed under the Apache License.