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=<lock> \
  -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=<lock> \
  -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=<lock> \
  -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

lock

This attribute toggles locking of the Terraform state file.

Type

Boolean

Required

False

Default

true

Example

lock: false

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

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

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

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Terraform::Configurable

#finalize_config!, included

Methods included from Terraform::ConfigAttribute::VariableFiles

#config_variable_files_default_value, included, to_sym

Methods included from Terraform::ConfigAttributeCacher

#define_cache, extended

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, included, to_sym

Class Method Details

.serial_actions(version: ::Kitchen::Terraform::Version.new) ⇒ ::Array<Symbol>

This method queries for the names of the action methods which must be run in serial via a shared mutex.

If the version satisfies the requirement of ~> 3.3 then no names are returned.

If the version satisfies the requirement of >= 4 then :create, :converge, :setup, and :destroy are returned.

Parameters:

Returns:

  • (::Array<Symbol>)

    the action method names.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
# File 'lib/kitchen/driver/terraform.rb', line 215

def self.serial_actions(version: ::Kitchen::Terraform::Version.new)
  version
    .if_satisfies requirement: ::Gem::Requirement.new("~> 3.3") do
      no_parallel_for
    end

  version
    .if_satisfies requirement: ::Gem::Requirement.new(">= 4") do
      super()
        .empty? and
        no_parallel_for(
          :create,
          :converge,
          :setup,
          :destroy
        )
    end

  super()
end

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:



242
243
244
245
246
247
248
249
250
251
252
253
# File 'lib/kitchen/driver/terraform.rb', line 242

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.

Parameters:

  • _state (::Hash)

    the mutable instance and driver state.

Raises:

  • (::Kitchen::ActionFailed)

    if the result of the action is a failure.



260
261
262
263
264
265
266
267
268
# File 'lib/kitchen/driver/terraform.rb', line 260

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.

Parameters:

  • _state (::Hash)

    the mutable instance and driver state.

Raises:

  • (::Kitchen::ActionFailed)

    if the result of the action is a failure.



276
277
278
279
280
281
282
283
284
285
286
287
# File 'lib/kitchen/driver/terraform.rb', line 276

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.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
# File 'lib/kitchen/driver/terraform.rb', line 293

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