kitchen-terraform 2.1.0 → 3.0.0

data/lib/kitchen/provisioner.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 provisioner 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::Provisioner
+end

data/lib/kitchen/provisioner/terraform.rb

@@ -14,36 +14,93 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "kitchen"
+require "kitchen/provisioner"
 require "kitchen/terraform/configurable"
 
-# The design of the provisioner is unconventional compared to other Test Kitchen provisioner plugins. Since Terraform
-# creates and provisions resources when applying an execution plan, managed by the driver, the provisioner simply
-# proxies the driver's create action to apply any changes to the existing Terraform state.
+# The provisioner utilizes the driver to apply changes to the Terraform state in order to reach the desired
+# configuration of the root module.
 #
-# === Configuration
+# === Commands
 #
-# ==== Example .kitchen.yml snippet
+# The following command-line actions are provided by the provisioner.
+#
+# ==== kitchen converge
+#
+# A Test Kitchen instance is converged through the following steps.
+#
+# ===== Selecting the Test Terraform Workspace
+#
+#   terraform workspace select kitchen-terraform-<instance>
+#
+# ===== Updating the Terraform Dependency Modules
+#
+#   terraform get -update <directory>
+#
+# ===== Validating the Terraform Root Module
+#
+#   terraform validate \
+#     -check-variables=true \
+#     [-no-color] \
+#     [-var=<variables.first>...] \
+#     [-var-file=<variable_files.first>...] \
+#     <directory>
+#
+# ===== Applying the Terraform State Changes
+#
+#   terraform apply\
+#     -lock=true \
+#     -lock-timeout=<lock_timeout>s \
+#     -input=false \
+#     -auto-approve=true \
+#     [-no-color] \
+#     -parallelism=<parallelism> \
+#     -refresh=true \
+#     [-var=<variables.first>...] \
+#     [-var-file=<variable_files.first>...] \
+#     <directory>
+#
+# ===== Retrieving the Terraform Output
+#
+#   terraform output -json
+#
+# === Configuration Attributes
+#
+# The provisioner has no configuration attributes, but the +provisioner+ mapping must be declared with the plugin name
+# within the {http://kitchen.ci/docs/getting-started/kitchen-yml Test Kitchen configuration file}.
 #
 #   provisioner:
 #     name: terraform
 #
-# @see ::Kitchen::Driver::Terraform
-# @see https://www.terraform.io/docs/commands/plan.html Terraform execution plan
-# @see https://www.terraform.io/docs/state/index.html Terraform state
+# @example Describe the converge command
+#   kitchen help converge
+# @example Converge a Test Kitchen instance
+#   kitchen converge default-ubuntu
 # @version 2
 class ::Kitchen::Provisioner::Terraform < ::Kitchen::Provisioner::Base
   kitchen_provisioner_api_version 2
 
   include ::Kitchen::Terraform::Configurable
 
-  # Proxies the driver's create action.
+  # Converges a Test Kitchen instance.
   #
-  # @example
-  #   `kitchen converge suite-name`
   # @param state [::Hash] the mutable instance and provisioner state.
   # @raise [::Kitchen::ActionFailed] if the result of the action is a failure.
   def call(state)
-    instance.driver.create state
+    instance
+      .driver
+      .apply
+      .fmap do |output|
+        state
+          .store(
+            :kitchen_terraform_output,
+            output
+          )
+      end
+      .or do |failure|
+        raise(
+          ::Kitchen::ActionFailed,
+          failure
+        )
+      end
   end
 end

data/lib/kitchen/terraform/client_version_verifier.rb

@@ -40,9 +40,9 @@ class ::Kitchen::Terraform::ClientVersionVerifier
         )
     ).bind do |version|
       if requirement.satisfied_by? version
-        Right "Terraform version #{version} is supported"
+        Right "Terraform v#{version} is supported"
       else
-        Left "Terraform version #{version} is not supported; upgrade to Terraform version ~> 0.10.2"
+        Left "Terraform v#{version} is not supported; install Terraform ~> v0.11.0"
       end
     end
   end
@@ -52,6 +52,11 @@ class ::Kitchen::Terraform::ClientVersionVerifier
   attr_reader :requirement
 
   def initialize
-    @requirement = ::Gem::Requirement.new "~> 0.10.2"
+    @requirement =
+      ::Gem::Requirement
+        .new(
+          ">= 0.10.2",
+          "< 0.12.0"
+        )
   end
 end

data/lib/kitchen/terraform/config_attribute.rb

@@ -20,9 +20,4 @@ require "kitchen/terraform"
 #
 # @abstract It defines the interface for configuration attributes to implement.
 module ::Kitchen::Terraform::ConfigAttribute
-  def self.default_value(_plugin:)
-  end
-
-  def self.to_sym
-  end
 end

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

@@ -19,16 +19,23 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/hash_of_symbols_and_strings"
 
-# The +:backend_configurations+ configuration attribute is an optional hash of symobls and strings comprising Terraform
-# backend configuration arguments to complete a partial backend.
+# This attribute comprises {https://www.terraform.io/docs/backends/config.html Terraform backend configuration}
+# arguments to complete a
+# {https://www.terraform.io/docs/backends/config.html#partial-configuration partial backend configuration}.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760142 Mapping of scalars to scalars}
+# Required:: False
+# Example::
+#   _
+#     backend_configurations:
+#       address: demo.consul.io
+#       path: example_app/terraform_state
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/backends/config.html#partial-configuration Terraform: Backend Configuration:
-#   Partial Configuration
 module ::Kitchen::Terraform::ConfigAttribute::BackendConfigurations
   # 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.
+  # @param plugin_class [::Kitchen::Configurable] a plugin class.
   # @return [void]
   def self.included(plugin_class)
     ::Kitchen::Terraform::ConfigAttributeDefiner
@@ -50,4 +57,13 @@ module ::Kitchen::Terraform::ConfigAttribute::BackendConfigurations
   def config_backend_configurations_default_value
     {}
   end
+
+  # @return [::String] the elements of the value converted to flags, joined by white space.
+  def config_backend_configurations_flags
+    config_backend_configurations
+      .map do |key, value|
+        "-backend-config='#{key}=#{value}'"
+      end
+      .join " "
+  end
 end

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

@@ -20,11 +20,18 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/boolean"
 
-# The +:color+ configuration attribute is an optional boolean which toggles colored output from the Terraform Client
-# commands.
+# This attribute toggles colored output from systems invoked by the plugin.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2803629 Boolean}
+# Required:: False
+# Default:: If a {https://en.wikipedia.org/wiki/Terminal_emulator terminal emulator} is associated with the Test Kitchen
+#           process then +true+; else +false+.
+# Example:: <code>color: false</code>
+# 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.
 #
 # @abstract It must be included by plugin class in order to be used.
-# @see ::Kitchen::Terraform::Client::Command
 module ::Kitchen::Terraform::ConfigAttribute::Color
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -49,8 +56,12 @@ module ::Kitchen::Terraform::ConfigAttribute::Color
   # The default value depends on the presence of a terminal device associated with the Test Kitchen process.
   #
   # @return [Boolean] if a terminal device is associated then +true+; else +false+.
-  # @see https://en.wikipedia.org/wiki/Terminal_emulator Terminal emulator
   def config_color_default_value
     ::Kitchen.tty?
   end
+
+  # @return [::String] the toggle converted to a flag.
+  def config_color_flag
+    config_color and "" or "-no-color"
+  end
 end

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

@@ -19,11 +19,14 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/integer"
 
-# The +:command_timeout+ configuration attribute is an optional integer which represents the number of seconds to wait
-# for the Terraform Client commands to finish.
+# This attribute controls the number of seconds that the plugin will wait for Terraform commands to finish running.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2803828 Integer}
+# Required:: False
+# Default:: +600+
+# Example:: <code>command_timeout: 1200</code>
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see ::Kitchen::Terraform::Client::Command
 module ::Kitchen::Terraform::ConfigAttribute::CommandTimeout
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -45,7 +48,7 @@ module ::Kitchen::Terraform::ConfigAttribute::CommandTimeout
 
   extend ::Kitchen::Terraform::ConfigAttributeCacher
 
-  # @return [::Integer] 600 seconds.
+  # @return [::Integer] 600.
   def config_command_timeout_default_value
     600
   end

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

@@ -19,62 +19,98 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/groups"
 
-# The +:groups+ configuration attribute is an optional array including hashes comprising properties to manage the
-# execution of InSpec profiles against different resources in the Terraform state.
+# This attribute is an optional array including hashes comprising properties to manage the execution of
+# {https://www.inspec.io/docs/reference/profiles/ InSpec profiles} against different resources in the Terraform state.
 #
-# === Hash Keys
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760193 Sequence of mappings}
+# Required:: False
+# Example::
+#   _
+#     groups:
+#       -
+#         name: a_group
+#
+# === Mapping Keys
+#
+# These keys must be declared in each of the mappings in the sequence.
 #
 # ==== name
 #
-# A required string which contains the name of the group.
+# This key contains the name of the group to be used for logging purposes.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: True
+# Example:: <code>name: a_group</code>
 #
 # ==== attributes
 #
-# An optional hash of symbols and strings which associates the names of InSpec profile attributes to the names of
-# Terraform outputs.
+# This key comprises associations of the names of
+# {https://www.inspec.io/docs/reference/profiles/#profile-attributes InSpec profile attributes} with the names of
+# {https://www.terraform.io/docs/configuration/outputs.html Terraform outputs}. The values of the outputs will be
+# exposed as attributes when InSpec executes.
 #
-# The attributes will be associated with the values of the outputs when InSpec runs.
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760142 Mapping of scalars to scalars}
+# Required:: False
+# Example::
+#   _
+#     attributes:
+#       an_attribute: an_output
+# Caveat:: As all Terraform outputs are associated with equivalently named InSpec profile attributes by default, this
+#          key is only necessary to provide alternative attribute names.
 #
 # ==== controls
 #
-# An optional array of strings which contain the names of controls to exclusively include from the InSpec profile of the
-# Test Kitchen suite.
+# This key comprises the names of {https://www.inspec.io/docs/reference/dsl_inspec/ InSpec controls} to exclusively
+# include from the InSpec profile of the Test Kitchen suite.
 #
-# ==== hostnames
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760118 Sequince of scalars}
+# Required:: False
+# Example::
+#   _
+#     controls:
+#       - first_control
+#       - third_control
 #
-# An optional string which contains the name of a Terraform output.
+# ==== hostnames
 #
-# The output must be of type String or Array and must contain one or more hostnames that will be the targets of the
-# InSpec profile of the Test Kitchen suite.
+# This key contains the name of a Terraform output.
 #
-# If this key is omitted then localhost will be the target of the profile.
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: False
+# Example:: <code>hostnames: an_output</code>
+# Caveat:: The output must be of type String or Array and must contain one or more hostnames that will be the targets of
+#          the InSpec profile of the Test Kitchen suite. If this key is omitted then +"localhost"+ will be the target of
+#          the profile.
 #
 # ==== port
 #
-# An optional integer which represents the port to use when connecting with Secure Shell (SSH) to the hosts of the
-# group.
+# This key contains the port to use when connecting with {https://en.wikipedia.org/wiki/Secure_Shell Secure Shell (SSH)}
+# to the hosts of the group.
 #
-# If this key is omitted then the port of the Test Kitchen SSH Transport will be used.
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2803828 Integer}
+# Required:: False
+# Example:: <code>port: 1234</code>
+# Caveat:: If this key is omitted then the port of the Test Kitchen SSH transport will be used.
 #
 # ==== ssh_key
 #
-# An optional string which contains the path to the private SSH key to use when connecting with SSH to the hosts of the
-# group.
+# This key contains the path to a private SSH key to use when connecting with SSH to the hosts of the group.
 #
-# If this key is omitted then the private SSH key of the Test Kitchen SSH Transport will be used.
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: False
+# Example:: <code>ssh_key: /path/to/an/ssh/key</code>
+# Caveat:: If this key is omitted then the private SSH key of the Test Kitchen SSH Transport will be used.
 #
 # ==== username
 #
-# An optional string which contains the username to use when connecting with SSH to the hosts of the group.
+# This key contains the username to use when connecting with SSH to the hosts of the group.
 #
-# If this key is omitted then the username of the Test Kitcen SSH Transport will be used.
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2760844 Scalar}
+# Required:: False
+# Example:: <code>ssh_key: /path/to/an/ssh/key</code>
+# Caveat:: If this key is omitted then the username of the Test Kitcen SSH Transport will be used.
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://github.com/test-kitchen/test-kitchen/blob/master/lib/kitchen/transport/ssh.rb Test Kitchen: SSH Transport
-# @see https://www.inspec.io/docs/reference/dsl_inspec/ InSpec: Controls
-# @see https://www.inspec.io/docs/reference/profiles/ InSpec: Profiles
-# @see https://www.terraform.io/docs/configuration/outputs.html Terraform: Output Variables
-# @see https://www.terraform.io/docs/state/index.html Terraform: State
 module ::Kitchen::Terraform::ConfigAttribute::Groups
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #

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

@@ -17,13 +17,17 @@
 require "kitchen/terraform/config_attribute"
 require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
-require "kitchen/terraform/config_schemas/string"
+require "kitchen/terraform/config_schemas/integer"
 
-# The +:lock_timeout+ configuration attribute is an optional string which contains the duration to wait for a lock on
-# the Terraform state to be obtained.
+# This attribute controls the number of seconds that Terraform will wait for a lock on the state to be obtained during
+# {https://www.terraform.io/docs/state/locking.html operations related to state}.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2803828 Integer}
+# Required:: False
+# Default:: +0+
+# Example:: <code>lock_timeout: 10</code>
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/apply.html#lock-timeout-0s Terraform: Command: apply: -lock-timeout
 module ::Kitchen::Terraform::ConfigAttribute::LockTimeout
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -33,7 +37,7 @@ module ::Kitchen::Terraform::ConfigAttribute::LockTimeout
     ::Kitchen::Terraform::ConfigAttributeDefiner
       .new(
         attribute: self,
-        schema: ::Kitchen::Terraform::ConfigSchemas::String
+        schema: ::Kitchen::Terraform::ConfigSchemas::Integer
       )
       .define plugin_class: plugin_class
   end
@@ -45,8 +49,13 @@ module ::Kitchen::Terraform::ConfigAttribute::LockTimeout
 
   extend ::Kitchen::Terraform::ConfigAttributeCacher
 
-  # @return [::String] 0 seconds.
+  # @return [::Integer] 0.
   def config_lock_timeout_default_value
-    "0s"
+    0
+  end
+
+  # @return [::String] the value converted to a flag.
+  def config_lock_timeout_flag
+    "-lock-timeout=#{config_lock_timeout}s"
   end
 end

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

@@ -19,12 +19,15 @@ require "kitchen/terraform/config_attribute_cacher"
 require "kitchen/terraform/config_attribute_definer"
 require "kitchen/terraform/config_schemas/integer"
 
-# The +:parallelism+ configuration attribute is an optional integer which represents the maximum number of concurrent
-# operations to allow while walking the resource graph for the Terraform Client apply command.
+# This attribute controls the number of concurrent operations to use while Terraform
+# {https://www.terraform.io/docs/internals/graph.html#walking-the-graph walks the resource graph}.
+#
+# Type:: {http://www.yaml.org/spec/1.2/spec.html#id2803828 Integer}
+# Required:: False
+# Default:: +10+
+# Example:: <code>parallelism: 50</code>
 #
 # @abstract It must be included by a plugin class in order to be used.
-# @see https://www.terraform.io/docs/commands/apply.html#parallelism-n Terraform: Command: apply: -parallelism
-# @see https://www.terraform.io/docs/internals/graph.html Terraform: Resource Graph
 module ::Kitchen::Terraform::ConfigAttribute::Parallelism
   # A callback to define the configuration attribute which is invoked when this module is included in a plugin class.
   #
@@ -50,4 +53,9 @@ module ::Kitchen::Terraform::ConfigAttribute::Parallelism
   def config_parallelism_default_value
     10
   end
+
+  # @return [::String] the value converted to a flag.
+  def config_parallelism_flag
+    "-parallelism=#{config_parallelism}"
+  end
 end