kitchen-terraform is a set of Test Kitchen plugins for testing Terraform configuration.
kitchen-terraform is packaged as a cryptographically signed Ruby gem which means it can be installed with Bundler.
Once Bundler is installed, add kitchen-terraform to the project's Gemfile:
source 'https://rubygems.org/' do
gem 'kitchen-terraform', '~> 0.7'
end
Then, use Bundler to install the gems:
bundle install
The provided plugins must all be used together in the Test Kitchen configuration in order to successfully test the provided Terraform configuration.
Refer to Getting Started Readme for a detailed walkthrough of setting up and using kitchen-terraform.
Refer to the examples directory for a detailed example project.
The driver is a wrapper around the Terraform command-line interface. It is responsible for enforcing Terraform version support and works with the provisioner to manage the Terraform state.
The driver ensures that the parent directories of the plan and state files exist.
The driver applies a destructive Terraform plan to the Terraform state based on the Terraform configuration provided to the provisioner.
The pathname of the Terraform command-line interface (CLI) executable or an executable that implements an equivalent interface.
---
driver:
name: terraform
cli: /usr/local/bin/terraform
The default cli
is 'terraform'
, and is assumed to exist in the
user's PATH.
The provisioner is the bridge between Terraform and Test Kitchen. It is responsible for managing the Test Kitchen configuration options related to the Terraform configuration and works with the driver to manage the Terraform state.
The provisioner uses the driver to apply a constructive Terraform plan to the Terraform state based on the provided Terraform configuration.
The number of seconds to wait for the Terraform apply
command to be
successful before raising an error.
---
provisioner:
name: terraform
apply_timeout: 1000
The default apply_timeout
is 600 seconds.
Enable or disable colored output from the Terraform command.
---
provisioner:
name: terraform
color: false
The default value for color
is true.
The pathname of the directory containing the Terraform configuration to be tested; corresponds to the directory specified in several Terraform commands.
---
provisioner:
name: terraform
directory: directory/containing/terraform/configuration
The default directory
is the current working directory of Test Kitchen.
The number of concurrent operations to allow for the Terraform apply
and
plan
commands.
provisioner:
name: terraform
parallelism: 2
The default parallelism
is 10.
The pathname of the execution plan that Terraform will generate and apply.
---
provisioner:
name: terraform
plan: /terraform/plan
The default plan
is under the current working directory of Test
Kitchen at .kitchen/kitchen-terraform/<suite_name>/terraform.tfplan
.
The pathname of the state file that Terraform will generate.
---
provisioner:
name: terraform
state: /terraform/state
The default state
is under the current working directory of Test
Kitchen at .kitchen/kitchen-terraform/<suite_name>/terraform.tfstate
.
A collection of pathnames of Terraform variable files to be evaluated for the configuration.
---
provisioner:
name: terraform
variable_files:
- first/terraform/variable/file
- second/terraform/variable/file
---
provisioner:
name: terraform
variable_files: a/terraform/variable/file
The default variable_files
collection is empty.
A mapping of Terraform variables to be set in the configuration.
---
provisioner:
name: terraform
variables:
foo: bar
# deprecated
---
provisioner:
name: terraform
variables:
- foo=bar
- biz=baz
---
# deprecated
provisioner:
name: terraform
variables: foo=bar
The default variables
collection is empty.
The verifier is a wrapper around InSpec. It is responsible for verifying the behaviour of any server instances in the Terraform state.
The verifier verifies the test suite's configured groups of server
instances in the Terraform state using an InSpec profiles located in
<Test Kitchen working directory>/test/integration/<suite name>
.
The verifier inherits from kitchen-inspec and should support any
configuration defined by that plugin with the exception of the port
and
username
configuration which are specified under groups
.
A collection of mappings that define how to test different resources in the Terraform configuration.
Each group consists of:
-
a
name
to use for logging purposes -
an optional
attributes
mapping of InSpec profile attribute names to Terraform output variable names to define for the suite's InSpec profile -
a
controls
collection of InSpec controls to include from the suite's InSpec profile -
a mapping of InSpec profile attribute names to Terraform output variable names; the attributes will be with the resolved output values
-
an optional
hostnames
output variable name to use for extracting hostnames from the Terraform state; the resolved output value is assumed to be a list of strings or a string in CSV format -
an optional
port
to use when connecting to the group's hosts -
an optional
username
to use when connecting to the group's hosts
If hostnames
is empty then the group's controls
will be executed
locally; this enables testing of a provider's API to verify non-server
resources.
verifier:
name: terraform
groups:
- name: arbitrary
attributes:
foo: bar
controls:
- biz
hostnames: hostnames_output
port: 123
username: test-user
The default groups
collection is empty.
For each group:
-
the default
attributes
mapping consists of equivalently named attributes for each output variable as well as a "terraform_state" attribute containing the pathname of the state file; additional or overridden associations can be added. -
the default
controls
collection is empty -
the default
hostnames
string is empty -
the default
port
is obtained from the transport -
the default
username
is obtained from the transport