kitchen-terraform

kitchen-terraform is a set of Test Kitchen plugins for testing Terraform configuration.

Requirements

• Ruby (~> 2.3)

• Bundler (~> 1.12)

• Terraform (~> 0.6)

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'

gem 'kitchen-terraform', '~> 0.1'

Before running bundle, the author's public key must be added as a trusted certificate:

gem cert --add <(curl --location --silent \
https://raw.githubusercontent.com/newcontext/kitchen-terraform/master/certs/ncs-alane-public_cert.pem)

Then, install the bundle and verify all of the gems:

bundle install --trust-policy LowSecurity

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 the examples directory for a detailed example project.

Plugins

Driver

The driver is responsible for ensuring compatibility with Terraform and destroying existing Terraform state.

Actions

kitchen create

The driver validates the installed version of Terraform against the version supported by kitchen-terraform.

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 responsible for creating Terraform state.

Actions

kitchen converge

The provisioner applies 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.

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 responsible for verifying the behaviour of any server instances in the Terraform state.

Actions

kitchen verify

The verifier verifies the configured server instances in the Terraform state using Inspec profiles.

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 group mappings containing Inspec control and connection options for the different server instance groups in the Terraform configuration.

Each group consists of:

• a name to use for logging purposes

• a mapping of Inspec attribute names to Terraform output variable names to define for the suite's Inspec profile

• a collection of controls to include from the suite's Inspec profile

• a hostnames output variable name to use for extracting hostnames from the Terraform state; the output value is assumed to be in CSV format

• the port to use when connecting to the group's hosts

• the username to use when connecting to the group's hosts

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 is empty

• the default controls collection is empty

• the default port is obtained from the transport

• the default username is obtained from the transport