kitchen-terraform 2.1.0 → 3.0.0

data/lib/kitchen/terraform/config_attribute/plugin_directory.rb

@@ -19,12 +19,16 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_schemas/optional_string"
 require "kitchen/terraform/file_path_config_attribute_definer"
 
-# The +:plugin_directory+ configuration attribute is an optional string which contains the path to the directory
-# containing customized Terraform provider plugins to install in place of the official Terraform provider plugins.
+# This attribute contains the path to the directory which contains
+# {https://www.terraform.io/docs/commands/init.html#plugin-installation customized Terraform provider plugins} to
+# install in place of the official Terraform provider plugins.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: False
+# Default:: There is no default value because any value will disable the normal Terraform plugin retrieval process.
+# Example:: <code>plugin_directory: /path/to/terraform/plugins</code>
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/init.html#plugin-installation Terraform: Command: init: Plugin
-#   Installation
 module ::Kitchen::Terraform::ConfigAttribute::PluginDirectory
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -46,10 +50,13 @@ module ::Kitchen::Terraform::ConfigAttribute::PluginDirectory
 
   extend ::Kitchen::Terraform::ConfigAttributeCacher
 
-  # There is no default value because any value will disable the normal Terraform plugin retrieval process.
-  #
   # @return [nil]
   def config_plugin_directory_default_value
     nil
   end
+
+  # @return [::String] the value converted to a flag.
+  def config_plugin_directory_flag
+    config_plugin_directory.nil? and "" or "-plugin-dir=#{config_plugin_directory}"
+  end
 end

data/lib/kitchen/terraform/config_attribute/{directory.rb → root_module_directory.rb}

@@ -19,14 +19,15 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_schemas/string"
 require "kitchen/terraform/file_path_config_attribute_definer"
 
-# The +:directory+ configuration attribute is an optional string which contains the path to the directory containing the
-# root Terraform module to be tested.
+# This attribute contains the path to the directory which contains the root Terraform module to be tested.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: False
+# Default:: The {https://en.wikipedia.org/wiki/Working_directory working directory} of the Test Kitchen process.
+# Example:: <code>root_module_directory: /path/to/terraform/root/module/directory</code>
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/init.html#copy-a-source-module Terraform: Command: init: Copy a Source
-#   Module
-# @see https://en.wikipedia.org/wiki/Working_directory Working directory
-module ::Kitchen::Terraform::ConfigAttribute::Directory
+module ::Kitchen::Terraform::ConfigAttribute::RootModuleDirectory
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
   # @param plugin_class [::Kitchen::Configurable] A plugin class.
@@ -42,13 +43,13 @@ module ::Kitchen::Terraform::ConfigAttribute::Directory
 
   # @return [::Symbol] the symbol corresponding to the attribute.
   def self.to_sym
-    :directory
+    :root_module_directory
   end
 
   extend ::Kitchen::Terraform::ConfigAttributeCacher
 
   # @return [::String] the working directory of the Test Kitchen process.
-  def config_directory_default_value
+  def config_root_module_directory_default_value
     "."
   end
 end

data/lib/kitchen/terraform/config_attribute/variable_files.rb

@@ -19,10 +19,18 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_schemas/array_of_strings"
 require "kitchen/terraform/file_path_config_attribute_definer"
 
-# The +:variable_files+ configuration attribute is an optional array of string which represent file paths.
+# This attribute comprises paths to
+# {https://www.terraform.io/docs/configuration/variables.html#variable-files Terraform variable files}.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760118 Sequince of scalars}
+# Required:: False
+# Example::
+#   _
+#     variable_files:
+#       - /path/to/first/variable/file
+#       - /path/to/second/variable/file
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/apply.html#var-file-foo Terraform: Command: apply: -var-file
 module ::Kitchen::Terraform::ConfigAttribute::VariableFiles
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -48,4 +56,13 @@ module ::Kitchen::Terraform::ConfigAttribute::VariableFiles
   def config_variable_files_default_value
     []
   end
+
+  # @return [::String] the elements of the value converted to flags, joined by white space.
+  def config_variable_files_flags
+    config_variable_files
+      .map do |path|
+        "-var-file=#{path}"
+      end
+      .join " "
+  end
 end

data/lib/kitchen/terraform/config_attribute/variables.rb

@@ -19,12 +19,17 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/hash_of_symbols_and_strings"
 
-# The +:variables+ configuration attribute is an optional hash of symbols and strings comprising Terraform variables to
-# be overridden during the application of Terraform state changes.
+# This attribute comprises {https://www.terraform.io/docs/configuration/variables.html Terraform variables}.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760142 Mapping of scalars to scalars}
+# Required:: False
+# Example::
+#   _
+#     variables:
+#       image: image-1234
+#       zone: zone-5
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/apply.html#var-39-foo-bar-39- Terraform: Command: apply: -var
-# @see https://www.terraform.io/docs/configuration/variables.html Terraform: Variables
 module ::Kitchen::Terraform::ConfigAttribute::Variables
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -50,4 +55,13 @@ module ::Kitchen::Terraform::ConfigAttribute::Variables
   def config_variables_default_value
     {}
   end
+
+  # @return [::String] the elements of the value converted to flags, joined by whitespace.
+  def config_variables_flags
+    config_variables
+      .map do |key, value|
+        "-var='#{key}=#{value}'"
+      end
+      .join " "
+  end
 end

data/lib/kitchen/terraform/configurable.rb

@@ -29,11 +29,6 @@ module ::Kitchen::Terraform::Configurable
     configurable_class.plugin_version ::Kitchen::Terraform::VERSION
   end
 
-  # @return [::Kitchen::Driver::Terraform] the driver which will manage the lifecycle actions of the instance.
-  def driver
-    instance.driver
-  end
-
   # Alternative implementation of Kitchen::Configurable#finalize_config! which validates the configuration before
   # attempting to expand paths.
   #
@@ -58,18 +53,4 @@ module ::Kitchen::Terraform::Configurable
 
     self
   end
-
-  # Constructs a pathname under the Test Kitchen instance directory.
-  #
-  # @return [::String] +"<kitchen-root>/.kitchen/kitchen-terraform/<suite-platform>/<filename>"+.
-  def instance_pathname(filename:)
-    ::File
-      .join(
-        config.fetch(:kitchen_root),
-        ".kitchen",
-        "kitchen-terraform",
-        instance.name,
-        filename
-      )
-  end
 end

data/lib/kitchen/terraform/shell_out.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Copyright 2016 New Context Services, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "dry/monads"
+require "kitchen/terraform"
+require "kitchen/terraform"
+require "mixlib/shellout"
+
+# Terraform commands are run by shelling out and using the
+# {https://www.terraform.io/docs/commands/index.html command-line interface}, which is assumed to be present in the
+# {https://en.wikipedia.org/wiki/PATH_(variable) PATH} of the user. The shell out environment includes the
+# TF_IN_AUTOMATION environment variable as specified by the
+# {https://www.terraform.io/guides/running-terraform-in-automation.html#controlling-terraform-output-in-automation Running Terraform in Automation guide}.
+module ::Kitchen::Terraform::ShellOut
+  extend ::Dry::Monads::Either::Mixin
+  extend ::Dry::Monads::Try::Mixin
+
+  # Runs a Terraform command.
+  #
+  # @param command [::String] the command to run.
+  # @param duration [::Integer] the maximum duration in seconds to run the command.
+  # @param logger [::Kitchen::Logger] a Test Kitchen logger to capture the output from running the command.
+  # @return [::Dry::Monads::Either] the result of running the command.
+  # @see https://rubygems.org/gems/mixlib-shellout mixlib-shellout
+  def self.run(command:, duration: ::Mixlib::ShellOut::DEFAULT_READ_TIMEOUT, logger:)
+    Try ::Mixlib::ShellOut::InvalidCommandOption do
+      ::Mixlib::ShellOut
+        .new(
+          "terraform #{command}",
+          environment: {"TF_IN_AUTOMATION" => "true"},
+          live_stream: logger,
+          timeout: duration
+        )
+    end
+      .bind do |shell_out|
+        Try(
+          ::Errno::EACCES,
+          ::Errno::ENOENT,
+          ::Mixlib::ShellOut::CommandTimeout,
+          ::Mixlib::ShellOut::ShellCommandFailed
+        ) do
+          logger.warn "Running command `#{shell_out.command}`"
+          shell_out.run_command
+          shell_out.error!
+          shell_out.stdout
+        end
+      end
+      .to_either
+      .or do |error|
+        Left "Running command resulted in failure: #{error}"
+      end
+  end
+end

data/lib/kitchen/terraform/version.rb

@@ -17,4 +17,4 @@
 require "kitchen/terraform"
 
 # The version of the kitchen-terraform gem.
-::Kitchen::Terraform::VERSION = "2.1.0".freeze
+::Kitchen::Terraform::VERSION = "3.0.0".freeze

data/lib/kitchen/verifier.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2016 New Context Services, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "kitchen"
+
+# This is the namespace for Test Kitchen verifier plugins. This namespace is already defined in Test Kitchen but YARD
+# requires it to be redefined here in order to include documenation from the Kitchen::Terraform namespace.
+module Kitchen::Verifier
+end

data/lib/kitchen/verifier/terraform.rb

@@ -15,61 +15,66 @@
 # limitations under the License.
 
 require "dry/monads"
-require "kitchen"
+require "kitchen/verifier"
 require "kitchen/terraform/config_attribute/color"
 require "kitchen/terraform/config_attribute/groups"
 require "kitchen/terraform/configurable"
 require "kitchen/verifier/inspec"
 
-# The kitchen-terraform verifier utilizes the InSpec infrastructure testing framework to verify the behaviour and state
-# of resources in the Terraform state.
+# The verifier utilizes the {https://www.inspec.io/ InSpec infrastructure testing framework} to verify the behaviour and
+# state of resources in the Terraform state.
 #
-# It is a subclass of the kitchen-inspec verifier.
+# === Commands
 #
-# === Test Kitchen Configuration
+# The following command-line commands are provided by the verifier.
 #
-# The configuration of the verifier is used to control the behaviour of the InSpec runner.
+# ==== kitchen verify
 #
-# More information about the available configuration attributes is located with the respective modules.
+# A Test Kitchen instance is verified by iterating through the groups and executing the associated InSpec controls in a
+# manner similar to the following command-line command.
 #
-# Test Kitchen configuration is defined in +.kitchen.yml+ and optionally overridden in +.kitchen.local.yml+.
+#   inspec exec \
+#     [--attrs=<terraform_outputs>] \
+#     --backend=<ssh|local> \
+#     [--no-color] \
+#     [--controls=<group.controls>] \
+#     --host=<group.hostnames.current|localhost> \
+#     [--password=<group.password>] \
+#     [--port=<group.port>] \
+#     --profiles-path=test/integration/<suite> \
+#     [--user=<group.username>] \
 #
-# ==== Example
+# === InSpec Profiles
+#
+# The {https://www.inspec.io/docs/reference/profiles/ InSpec profile} for a Test Kitchen suite must be defined under
+# +./test/integration/<suite>/+.
+#
+# === Configuration Attributes
+#
+# The configuration attributes of the verifier control the behaviour of the InSpec runner. Within the
+# {http://kitchen.ci/docs/getting-started/kitchen-yml Test Kitchen configuration file}, these attributes must be
+# declared in the +verifier+ mapping along with the plugin name.
 #
 #   verifier:
-#     name: "terraform"
-#     color: false
-#     groups:
-#       -
-#         name: "group_one"
-#         attributes:
-#           foo: "bar"
-#         controls:
-#           - "biz"
-#         hostnames: "hostnames_output"
-#         port: "123"
-#         username: "test-user"
-#       -
-#         name: "group_two"
+#     name: terraform
+#     a_configuration_attribute: some value
 #
-# === InSpec Profiles
+# ==== color
+#
+# {include:Kitchen::Terraform::ConfigAttribute::Color}
 #
-# The InSpec profile for a Test Kitchen suite exists under +./test/integration/<Test Kitchen suite name>/+.
+# ==== groups
+#
+# {include:Kitchen::Terraform::ConfigAttribute::Groups}
 #
-# @see ::Kitchen::Terraform::ConfigAttribute::Color
-# @see ::Kitchen::Terraform::ConfigAttribute::Groups
-# @see https://en.wikipedia.org/wiki/Secure_Shell Secure Shell
-# @see https://github.com/chef/kitchen-inspec/ kitchen-inspec
-# @see https://github.com/chef/kitchen-inspec/blob/master/lib/kitchen/verifier/inspec.rb kitchen-inspec: Verifier
-# @see https://www.inspec.io/ InSpec
-# @see https://www.inspec.io/docs/reference/profiles/ InSpec: Profiles
-# @see https://www.terraform.io/docs/state/index.html Terraform: State
 # @version 2
 class ::Kitchen::Verifier::Terraform < ::Kitchen::Verifier::Inspec
   kitchen_verifier_api_version 2
 
   include ::Dry::Monads::Either::Mixin
 
+  include ::Dry::Monads::Maybe::Mixin
+
   include ::Kitchen::Terraform::ConfigAttribute::Color
 
   include ::Kitchen::Terraform::ConfigAttribute::Groups
@@ -84,16 +89,39 @@ class ::Kitchen::Verifier::Terraform < ::Kitchen::Verifier::Inspec
   # @raise [::Kitchen::ActionFailed] if the result of the action is a failure.
   # @return [::Dry::Monads::Either] the result of the action.
   def call(state)
-    self.class::EnumerateGroupsAndHostnames.call driver: driver, groups: config_groups do |group:, hostname:|
-      state.store :group, group
-      state.store :hostname, hostname
-      info "Verifying host '#{hostname}' of group '#{group.fetch :name}'"
-      super state
-    end.bind do |success|
-      Right logger.debug success
-    end.or do |failure|
-      raise ::Kitchen::ActionFailed, failure
-    end
+    Maybe(state[:kitchen_terraform_output])
+      .or do
+        Left(
+          "The Test Kitchen state does not include :kitchen_terraform_output; this implies that the " \
+            "kitchen-terraform provisioner has not successfully converged"
+        )
+      end
+      .bind do |output|
+        ::Kitchen::Verifier::Terraform::EnumerateGroupsAndHostnames
+          .call(
+            groups: config_groups,
+            output: ::Kitchen::Util.stringified_hash(output)
+          ) do |group:, hostname:|
+            state
+              .store(
+                :kitchen_terraform_group,
+                group
+              )
+            state
+              .store(
+                :kitchen_terraform_hostname,
+                hostname
+              )
+            info "Verifying host '#{hostname}' of group '#{group.fetch :name}'"
+            super state
+          end
+      end
+      .or do |failure|
+        raise(
+          ::Kitchen::ActionFailed,
+          failure
+        )
+      end
   end
 
   private
@@ -105,23 +133,51 @@ class ::Kitchen::Verifier::Terraform < ::Kitchen::Verifier::Inspec
   # @return [::Hash] Inspec Runner options.
   # @see https://github.com/chef/inspec/blob/master/lib/inspec/runner.rb ::Inspec::Runner
   def runner_options(transport, state = {}, platform = nil, suite = nil)
-    super(transport, state, platform, suite).tap do |options|
-      self.class::ConfigureInspecRunnerBackend.call hostname: state.fetch(:hostname), options: options
-      self.class::ConfigureInspecRunnerHost.call hostname: state.fetch(:hostname), options: options
-      self.class::ConfigureInspecRunnerPort.call group: state.fetch(:group), options: options
-      self
-        .class::ConfigureInspecRunnerSSHKey
-        .call(
-          group: state.fetch(:group),
-          options: options
-        )
-      self.class::ConfigureInspecRunnerUser.call group: state.fetch(:group), options: options
-      self.class::ConfigureInspecRunnerAttributes
-        .call(driver: driver, group: state.fetch(:group), terraform_state: driver[:state]).bind do |attributes|
-          config.store :attributes, attributes
-        end
-      self.class::ConfigureInspecRunnerControls.call group: state.fetch(:group), options: options
-    end
+    super(transport, state, platform, suite)
+      .tap do |options|
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerBackend
+          .call(
+            hostname: state.fetch(:kitchen_terraform_hostname),
+            options: options
+          )
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerHost
+          .call(
+            hostname: state.fetch(:kitchen_terraform_hostname),
+            options: options
+          )
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerPort
+          .call(
+            group: state.fetch(:kitchen_terraform_group),
+            options: options
+          )
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerSSHKey
+          .call(
+            group: state.fetch(:kitchen_terraform_group),
+            options: options
+          )
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerUser
+          .call(
+            group: state.fetch(:kitchen_terraform_group),
+            options: options
+          )
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerAttributes
+          .call(
+            group: state.fetch(:kitchen_terraform_group),
+            output: ::Kitchen::Util.stringified_hash(state.fetch(:kitchen_terraform_output))
+          )
+          .bind do |attributes|
+            options
+              .store(
+                :attributes,
+                attributes
+              )
+          end
+        ::Kitchen::Verifier::Terraform::ConfigureInspecRunnerControls
+          .call(
+            group: state.fetch(:kitchen_terraform_group),
+            options: options
+          )
+      end
   end
 end