kitchen-terraform
kitchen-terraform is a set of Test Kitchen plugins for testing Terraform configuration.
Requirements
Installation
kitchen-terraform is packaged as a cryptographically signed Ruby gem which means it can be installed with Bundler.
Adding kitchen-terraform to a Terraform project
Once Bundler is installed, add kitchen-terraform to the project's Gemfile:
source 'https://rubygems.org/' do
gem 'kitchen-terraform', '~> 0.4'
end
Then, use Bundler to install the gems:
bundle install
Usage
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.
Plugins
Driver
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.
Actions
kitchen create
The driver ensures that the parent directories of the plan and state files exist.
kitchen destroy
The driver applies a destructive Terraform plan to the Terraform state based on the Terraform configuration provided to the provisioner.
Configuration
There are no configuration options for the driver.
Example .kitchen.yml
---
driver:
name: terraform
Provisioner
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.
Actions
kitchen converge
The provisioner uses the driver to apply a constructive Terraform plan to the Terraform state based on the provided Terraform configuration.
Configuration
apply_timeout
The number of seconds to wait for the Terraform apply
command to be
successful before raising an error.
Example .kitchen.yml
---
provisioner:
name: terraform
apply_timeout: 1000
Default
The default apply_timeout
is 600 seconds.
color
Enable or disable colored output from the Terraform command.
Example .kitchen.yml
---
provisioner:
name: terraform
color: false
Default
The default value for color
is true.
directory
The pathname of the directory containing the Terraform configuration to be tested; corresponds to the directory specified in several Terraform commands.
Example .kitchen.yml
---
provisioner:
name: terraform
directory: directory/containing/terraform/configuration
Default
The default directory
is the current working directory of Test Kitchen.
parallelism
The number of concurrent operations to allow for the Terraform apply
and
plan
commands.
Example .kitchen.yml
provisioner:
name: terraform
parallelism: 2
Default
The default parallelism
is 10.
variable_files
A collection of pathnames of Terraform variable files to be evaluated for the configuration.
Example .kitchen.yml
---
provisioner:
name: terraform
variable_files:
- first/terraform/variable/file
- second/terraform/variable/file
---
provisioner:
name: terraform
variable_files: a/terraform/variable/file
Default
The default variable_files
collection is empty.
variables
A mapping of Terraform variables to be set in the configuration.
Example .kitchen.yml
---
provisioner:
name: terraform
variables:
foo: bar
# deprecated
---
provisioner:
name: terraform
variables:
- foo=bar
- biz=baz
---
# deprecated
provisioner:
name: terraform
variables: foo=bar
Default
The default variables
collection is empty.
Verifier
The verifier is a wrapper around InSpec. It is responsible for verifying the behaviour of any server instances in the Terraform state.
Actions
kitchen verify
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>
.
Configuration
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
.
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 purposesan optional
attributes
mapping of InSpec profile attribute names to Terraform output variable names to define for the suite's InSpec profilea
controls
collection of InSpec controls to include from the suite's InSpec profilea 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 formatan optional
port
to use when connecting to the group's hostsan 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.
Example .kitchen.yml
verifier:
name: terraform
groups:
- name: arbitrary
attributes:
foo: bar
controls:
- biz
hostnames: hostnames_output
port: 123
username: test-user
Defaults
The default groups
collection is empty.
For each group:
the default
attributes
mapping consists of equivalently named attributes for each output variable; additional or overridden associations can be added.the default
controls
collection is emptythe default
hostnames
string is emptythe default
port
is obtained from the transportthe default
username
is obtained from the transport