Kitchen-Terraform enables verification of infrastructure systems provisioned with Terraform.
Warning Deprecation Notice
⚠️ With the announcement of a native test framework with Terraform 1.6 on 2023-10-04, we are excited/saddened/relieved to announce the deprecation of Kitchen-Terraform 🎉 The project will enter a maintenance-only period for about 1 year, after which time it will be archived.
We strongly recommend that users begin to learn about Terraform tests and plan their migration to the new framework accordingly.
So long, and thanks for all the tests 💖
Kitchen-Terraform provides a set of Test Kitchen plugins which enable the use of Test Kitchen to converge a Terraform configuration and verify the resulting infrastructure systems 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, < 2.0.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.4, < 2.8.
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.
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 "https://rubygems.org/" do
gem "kitchen-terraform", "~> 7.0"
endSecond, run the following command.
Installing Kitchen-Terraform with Bundler
bundle installThe 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 7.0.2This 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.
The RbNaCl gem may need to be installed in order to use Ed25519-type SSH keys to connect to systems with the SSH backend. This gem implicitly depends on the system package libsodium, and its presence when libsodium is not installed causes unexpected errors when loading InSpec transport plugins like GCP, so it is not included by default to reduce the burden on users whom do not require support for Ed25519-type SSH keys.
A familiarity with Test Kitchen workflows and commands is required to use Kitchen-Terraform.
Kitchen-Terraform provides four Test Kitchen plugins which must be configured in a Test Kitchen configuration file in order to successfully test Terraform configuration.
The Terraform driver is the bridge between Test Kitchen and Terraform. It manages the state of the Terraform root module under test by shelling out and running Terraform commands.
The Terraform provisioner applies changes to the Terraform state based on the configuration of the root module.
The Terraform transport is responsible for the integration with the Terraform CLI.
The Terraform verifier utilizes InSpec to verify the behaviour and state of resources in the Terraform state.
More information can be found in the Ruby gem documentation.
The kitchen doctor command can be used to validate the system and the
configuration file.
Versions of Terraform in the 0.11 series may cause kitchen test to
fail if the initial destroy targets an empty Terraform state. A
workaround for this problem is to use
kitchen verify && kitchen destroy instead of kitchen test. More
details about the problem are available in
issue #271.
Several tutorials are available on the Kitchen-Terraform Tutorials page.
The integration tests for Kitchen-Terraform can also be viewed as examples of how it works. The integration test Test Kitchen configuration file and the integration test directory provide several functional examples which exercise various features of Kitchen-Terraform.
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 community contributors and Copado NCS LLC.
Kitchen-Terraform is distributed under the Apache License.