Class: Kitchen::Driver::Terraform

Overview

The driver is the bridge between Test Kitchen and Terraform. It manages the state of the Terraform root module by shelling out and running Terraform commands.

Commands

The following command-line commands are provided by the driver.

kitchen create

A Test Kitchen instance is created through the following steps.

Initializing the Terraform Working Directory
terraform init \
  -input=false \
  -lock=true \
  -lock-timeout=<lock_timeout>s \
  [-no-color] \
  -upgrade \
  -force-copy \
  -backend=true \
  [-backend-config=<backend_configurations.first> ...] \
  -get=true \
  -get-plugins=true \
  [-plugin-dir=<plugin_directory>] \
  -verify-plugins=true \
  <root_module_directory>
Creating a Test Terraform Workspace
terraform workspace <new|select> kitchen-terraform-<instance>

kitchen destroy

A Test Kitchen instance is destroyed through the following steps.

Initializing the Terraform Working Directory
terraform init \
  -input=false \
  -lock=true \
  -lock-timeout=<lock_timeout>s \
  [-no-color] \
  -force-copy \
  -backend=true \
  [-backend-config=<backend_configurations.first>...] \
  -get=true \
  -get-plugins=true \
  [-plugin-dir=<plugin_directory>] \
  -verify-plugins=true \
  <root_module_directory>
Selecting the Test Terraform Workspace
terraform workspace <select|new> kitchen-terraform-<instance>
Destroying the Terraform State
terraform destroy \
  -force \
  -lock=true \
  -lock-timeout=<lock_timeout>s \
  -input=false \
  [-no-color] \
  -parallelism=<parallelism> \
  -refresh=true \
  [-var=<variables.first>...] \
  [-var-file=<variable_files.first>...] \
  <root_module_directory>
Selecting the Default Terraform Workspace
terraform workspace select default
Deleting the Test Terraform Workspace
terraform workspace delete kitchen-terraform-<instance>

Shelling Out

Terraform commands are run by shelling out and using the command-line interface, which is assumed to be present in the PATH of the user. The shell out environment includes the TF_IN_AUTOMATION environment variable as specified by the Running Terraform in Automation guide.

Configuration Attributes

The configuration attributes of the driver control the behaviour of the Terraform commands that are run. Within the Test Kitchen configuration file, these attributes must be declared in the driver mapping along with the plugin name.

driver:
  name: terraform
  a_configuration_attribute: some value

backend_configurations

This attribute comprises Terraform backend configuration arguments to complete a partial backend configuration.

Type

Mapping of scalars to scalars

Required

False

Example

_

backend_configurations:
  address: demo.consul.io
  path: example_app/terraform_state

color

This attribute toggles colored output from systems invoked by the plugin.

Type

Boolean

Required

False

Default

If a terminal emulator is associated with the Test Kitchen process then true; else false.

Example

color: false

Caveat

This attribute does not toggle colored output from the Test Kitchen core, though it does use the same default logic. To toggle colored output from the core, the --color and --no-color command-line flags must be used.

command_timeout

This attribute controls the number of seconds that the plugin will wait for Terraform commands to finish running.

Type

Integer

Required

False

Default

600

Example

command_timeout: 1200

root_module_directory

This attribute contains the path to the directory which contains the root Terraform module to be tested.

Type

Scalar

Required

False

Default

The working directory of the Test Kitchen process.

Example

root_module_directory: /path/to/terraform/root/module/directory

lock_timeout

This attribute controls the number of seconds that Terraform will wait for a lock on the state to be obtained during operations related to state.

Type

Integer

Required

False

Default

0

Example

lock_timeout: 10

parallelism

This attribute controls the number of concurrent operations to use while Terraform walks the resource graph.

Type

Integer

Required

False

Default

10

Example

parallelism: 50

plugin_directory

This attribute contains the path to the directory which contains customized Terraform provider plugins to install in place of the official Terraform provider plugins.

Type

Scalar

Required

False

Default

There is no default value because any value will disable the normal Terraform plugin retrieval process.

Example

plugin_directory: /path/to/terraform/plugins

variable_files

This attribute comprises paths to Terraform variable files.

Type

Sequince of scalars

Required

False

Example

_

variable_files:
  - /path/to/first/variable/file
  - /path/to/second/variable/file

variables

This attribute comprises Terraform variables.

Type

Mapping of scalars to scalars

Required

False

Example

_

variables:
  image: image-1234
  zone: zone-5

Examples:

Describe the create command

kitchen help create

Create a Test Kitchen instance

kitchen create default-ubuntu

Describe the destroy command

kitchen help destroy

Destroy a Test Kitchen instance

kitchen destroy default-ubuntu

Version:

  • 2

Instance Method Summary collapse

Methods included from Terraform::Configurable

#finalize_config!, included

Methods included from Terraform::ConfigAttribute::Variables

#config_variables_default_value, #config_variables_flags, included, to_sym

Methods included from Terraform::ConfigAttributeCacher

#define_cache, extended

Methods included from Terraform::ConfigAttribute::VariableFiles

#config_variable_files_default_value, #config_variable_files_flags, included, to_sym

Methods included from Terraform::ConfigAttribute::RootModuleDirectory

#config_root_module_directory_default_value, included, to_sym

Methods included from Terraform::ConfigAttribute::PluginDirectory

#config_plugin_directory_default_value, #config_plugin_directory_flag, included, to_sym

Methods included from Terraform::ConfigAttribute::Parallelism

#config_parallelism_default_value, #config_parallelism_flag, included, to_sym

Methods included from Terraform::ConfigAttribute::LockTimeout

#config_lock_timeout_default_value, #config_lock_timeout_flag, included, to_sym

Methods included from Terraform::ConfigAttribute::CommandTimeout

#config_command_timeout_default_value, included, to_sym

Methods included from Terraform::ConfigAttribute::Color

#config_color_default_value, #config_color_flag, included, to_sym

Methods included from Terraform::ConfigAttribute::BackendConfigurations

#config_backend_configurations_default_value, #config_backend_configurations_flags, included, to_sym

Instance Method Details

#apply {|output| ... } ⇒ void

This method returns an undefined value.

Applies changes to the state by selecting the test workspace, updating the dependency modules, validating the root module, applying the state changes, and retrieving the state output.

Yield Parameters:

  • output (::String)

    the state output.

Raises:



202
203
204
205
206
207
208
209
210
211
212
213
# File 'lib/kitchen/driver/terraform.rb', line 202

def apply(&block)
  run_workspace_select_instance
  apply_run_get
  apply_run_validate
  apply_run_apply
  ::Kitchen::Terraform::Command::Output
    .run(
      duration: config_command_timeout,
      logger: logger,
      &block
    )
end

#create(_state) ⇒ void

This method returns an undefined value.

Creates a Test Kitchen instance by initializing the working directory and creating a test workspace.

Raises:

  • (::Kitchen::ActionFailed)

    if the result of the action is a failure.



220
221
222
223
224
225
226
227
228
# File 'lib/kitchen/driver/terraform.rb', line 220

def create(_state)
  create_run_init
  run_workspace_select_instance
rescue ::Kitchen::Terraform::Error => error
  raise(
    ::Kitchen::ActionFailed,
    error.message
  )
end

#destroy(_state) ⇒ void

This method returns an undefined value.

Destroys a Test Kitchen instance by initializing the working directory, selecting the test workspace, deleting the state, selecting the default workspace, and deleting the test workspace.

Raises:

  • (::Kitchen::ActionFailed)

    if the result of the action is a failure.



236
237
238
239
240
241
242
243
244
245
246
247
# File 'lib/kitchen/driver/terraform.rb', line 236

def destroy(_state)
  destroy_run_init
  run_workspace_select_instance
  destroy_run_destroy
  destroy_run_workspace_select_default
  destroy_run_workspace_delete_instance
rescue ::Kitchen::Terraform::Error => error
  raise(
    ::Kitchen::ActionFailed,
    error.message
  )
end

#verify_dependenciesvoid

This method returns an undefined value.

Verifies that the Terraform version available to the driver is supported.

Raises:

  • (::Kitchen::UserError)

    if the version is not supported.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
# File 'lib/kitchen/driver/terraform.rb', line 253

def verify_dependencies
  logger
    .warn(
      ::Kitchen::Terraform::ClientVersionVerifier
        .new
        .verify(
          version_output:
            ::Kitchen::Terraform::ShellOut
              .run(
                command: "version",
                duration: 600,
                logger: logger
              )
        )
    )
rescue ::Kitchen::Terraform::Error => error
  raise(
    ::Kitchen::UserError,
    error.message
  )
end