kitchen-terraform 0.7.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1b74665cdd2f600d9baab71615afcc2f514e2e2
-  data.tar.gz: 1f473db97e5328bdc08d380e0ea31dc2fd1ee3da
+  metadata.gz: a7c30b59401be69f125e4b9ac0d57b91d2152c5c
+  data.tar.gz: 7f46bce8b7f4bfaec2c82f1ae1f522ddf9ba3baa
 SHA512:
-  metadata.gz: 852b9d8ee05805080905138c2fd1936b4827d5dbfe41c291e90b7abcbff86a183fdd9eac0fc03f1e432e2db366413fc1c3b722f8ad9bc8c746b0408b5452931e
-  data.tar.gz: 64748a06ccf9b202a100bb6a9a651884e60e4a3a723aeb91f2ff0c5c30f6b1d0eb6e54f0ff8ef236dc13d3aed1dc0d87f45f13b9d0692fba866bde04fa25ef15
+  metadata.gz: 7c235d1d29893628ee848e48b6ad087b01358cea304b004a9c56b90fb5b23cc5d5ad0ecace68e76feec8206a7202fca61500e8d07408c6068b7a13ec88e51546
+  data.tar.gz: fada5a0befd2b5be3de085dd7a22be9b2b80185ceae98f32ca1f8e03036f1e81faa48c89f590be220ceef327bf1c69c8adecd0414ec5c4787abd0553b4d92bc1

data.tar.gz.sig

@@ -1 +1,3 @@
-<�ON`|��%;A�
��܎��텣���=��=��.���ci��&!KYd)!e��B����P�#X��}��kN��(���(�K���9d4����ʋ]����[�����I,\����o���-��)�6״V��*���iA��Շ��XIf��v�lLD�5���'HW�l�ԅ���!��No�ݲ⃵����{��{�h��X����HɭTa�=�������VH�O�\ϛ���w�t���83�����
+e��J�	�].�0��!���@�eD^E��	%�O4�
+�kIH�WaX��S)���:��6^
+�o�<v��-���l�����1b�1�p6'�X�HBL<k����Ӵm$;0��̄d[_�f�ˆ�d���u�~���G�yPZ��z�{�3�����/\Td�w�C�[P�v
���ާR�r�1j���RQ�~:��R &޳M�S�LO���zj׬�ą���}NUػ�U�0B<B�Ml܍�y�j���

data/README.md

@@ -9,23 +9,13 @@
 kitchen-terraform is a set of [Test Kitchen] plugins for testing
 [Terraform configuration].
 
-[Test Kitchen]: http://kitchen.ci/index.html
-
-[Terraform configuration]: https://www.terraform.io/docs/configuration/index.html
-
 ## Requirements
 
 - [Ruby] **(~> 2.1)**
 
 - [Bundler] **(~> 1.12)**
 
-- [Terraform] **(>= 0.6, < 0.10)**
-
-[Ruby]: https://www.ruby-lang.org/en/index.html
-
-[Bundler]: https://bundler.io/index.html
-
-[Terraform]: https://www.terraform.io/index.html
+- [Terraform] **(>= 0.7, < 0.10)**
 
 ## Installation
 
@@ -34,11 +24,12 @@ 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:
+Once Bundler is installed, add kitchen-terraform to the project's
+Gemfile:
 
 ```rb
-source 'https://rubygems.org/' do
-  gem 'kitchen-terraform', '~> 0.7'
+source "https://rubygems.org/" do
+  gem "kitchen-terraform", "~> 1.0"
 end
 ```
 
@@ -48,358 +39,41 @@ Then, use Bundler to install the gems:
 bundle install
 ```
 
-[Ruby Gem]: http://guides.rubygems.org/what-is-a-gem/index.html
-
-[installed with Bundler]: https://bundler.io/index.html#getting-started
-
 ## Usage
 
-The provided plugins must all be used together in the
-[Test Kitchen configuration] in order to successfully test the provided
-Terraform configuration.
-
-[Test Kitchen configuration]: https://docs.chef.io/config_yml_kitchen.html
-
-Refer to [Getting Started Readme](examples/aws_provider/getting_started.md) for a detailed walkthrough of setting up and using kitchen-terraform.
-
-Refer to the [examples directory] for a detailed example project.
+kitchen-terraform provides three Test Kitchen plugins which must be used
+together in the [Test Kitchen configuration] in order to successfully
+test Terraform configuration:
 
-[examples directory]: examples/
+- a [driver] that creates and destroys [Terraform state];
 
-## Plugins
+- a [provisioner] that applies changes to existing Terraform state;
 
-### Driver
+- a [verifier] that verifies the state and behaviour of resources in the
+  Terraform state.
 
-The [driver] is a wrapper around the [Terraform command-line interface].
-It is responsible for enforcing Terraform version support and works with
-the provisioner to manage the [Terraform state].
+Refer to the [gem documentation] for more information about
+kitchen-terraform's design and behaviour.
 
-[driver]: lib/kitchen/driver/terraform.rb
+Refer to the [Getting Started README] for a detailed walkthrough of
+setting up and using kitchen-terraform.
 
-[Terraform command-line interface]: https://www.terraform.io/docs/commands/index.html
+Refer to the [examples directory] for example Terraform projects using
+various [Terraform providers].
 
+[Bundler]: https://bundler.io/index.html
+[Getting Started README]: https://github.com/newcontext-oss/kitchen-terraform/examples/aws_provider/getting_started.md
+[Ruby Gem]: http://guides.rubygems.org/what-is-a-gem/index.html
+[Ruby]: https://www.ruby-lang.org/en/index.html
+[Terraform configuration]: https://www.terraform.io/docs/configuration/index.html
+[Terraform providers]: https://www.terraform.io/docs/configuration/providers.html
 [Terraform state]: https://www.terraform.io/docs/state/index.html
-
-#### Actions
-
-##### kitchen create
-
-The driver ensures that the parent directories of the plan and state
-files exist.
-
-##### kitchen destroy
-
-The driver applies a destructive [Terraform plan] to the
-Terraform state based on the Terraform configuration provided to the
-provisioner.
-
-[Terraform plan]: https://www.terraform.io/docs/commands/plan.html
-
-#### Configuration
-
-##### cli
-
-The pathname of the Terraform command-line interface (CLI) executable or
-an executable that implements an equivalent interface.
-
-[command-line interface]: https://www.terraform.io/docs/commands/index.html
-
-###### Example .kitchen.yml
-
-```yaml
----
-driver:
-  name: terraform
-  cli: /usr/local/bin/terraform
-```
-
-###### Default
-
-The default `cli` is `'terraform'`, and is assumed to exist in the
-user's [PATH].
-
-[PATH]: http://www.linfo.org/path_env_var.html
-
-### Provisioner
-
-The [provisioner] is the bridge between Terraform and Test Kitchen. It
-is responsible for managing the Test Kitchen configuration options related to
-the Terraform configuration and works with the driver to manage the
-Terraform state.
-
-[provisioner]: lib/kitchen/provisioner/terraform.rb
-
-#### Actions
-
-##### kitchen converge
-
-The provisioner uses the driver to apply 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
-
-```yaml
----
-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
-
-```yaml
----
-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.
-
-[directory specified]: https://www.terraform.io/docs/configuration/load.html
-
-###### Example .kitchen.yml
-
-```yaml
----
-provisioner:
-  name: terraform
-  directory: directory/containing/terraform/configuration
-```
-
-###### Default
-
-The default `directory` is the current working directory of Test Kitchen.
-
-##### parallelism
-
-The number of concurrent operations to allow for the Terraform `apply` and
-`plan` commands.
-
-###### Example .kitchen.yml
-
-```yaml
-provisioner:
-  name: terraform
-  parallelism: 2
-```
-
-###### Default
-
-The default `parallelism` is 10.
-
-##### plan
-
-The pathname of the [execution plan] that Terraform will generate and
-apply.
-
-[execution plan]: https://www.terraform.io/docs/commands/plan.html#_out_path
-
-###### Example .kitchen.yml
-
-```yaml
----
-provisioner:
-  name: terraform
-  plan: /terraform/plan
-```
-
-###### Default
-
-The default `plan` is under the current working directory of Test
-Kitchen at `.kitchen/kitchen-terraform/<suite_name>/terraform.tfplan`.
-
-##### state
-
-The pathname of the [state file] that Terraform will generate.
-
-[state file]: https://www.terraform.io/docs/commands/apply.html#_state_out_path
-
-###### Example .kitchen.yml
-
-```yaml
----
-provisioner:
-  name: terraform
-  state: /terraform/state
-```
-
-###### Default
-
-The default `state` is under the current working directory of Test
-Kitchen at `.kitchen/kitchen-terraform/<suite_name>/terraform.tfstate`.
-
-##### variable_files
-
-A collection of pathnames of [Terraform variable files] to be evaluated
-for the configuration.
-
-[Terraform variable files]: https://www.terraform.io/docs/configuration/variables.html#variable-files
-
-###### Example .kitchen.yml
-
-```yaml
----
-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.
-
-[Terraform variables]: https://www.terraform.io/docs/configuration/variables.html
-
-###### Example .kitchen.yml
-
-```yaml
----
-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 a wrapper around [InSpec]. It is responsible for
-verifying the behaviour of any server instances in the Terraform state.
-
-[verifier]: lib/kitchen/verifier/terraform.rb
-
-[InSpec]: http://inspec.io
-
-#### Actions
-
-##### kitchen verify
-
-The verifier verifies the test suite's configured groups of server
-instances in the Terraform state using an [InSpec profiles] located in
-`<Test Kitchen working directory>/test/integration/<suite name>`.
-
-[InSpec profiles]: http://inspec.io/docs/reference/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`.
-
-[kitchen-inspec]: https://github.com/chef/kitchen-inspec/
-
-##### groups
-
-A collection of mappings that define how to test different resources in the
-Terraform configuration.
-
-Each group consists of:
-
-- a `name` to use for logging purposes
-
-- an optional `attributes` mapping of InSpec profile attribute names to
-  Terraform output variable names to define for the suite's InSpec profile
-
-- a `controls` collection of [InSpec controls] to include from the suite's
-  InSpec profile
-
-- a mapping of InSpec profile attribute names to Terraform output variable
-  names; the attributes will be with the resolved output values
-
-- an optional `hostnames` output variable name to use for extracting hostnames
-  from the Terraform state; the resolved output value is assumed to be a
-  list of strings or a string in CSV format
-
-- an optional `port` to use when connecting to the group's hosts
-
-- an optional `username` to use when connecting to the group's hosts
-
-If `hostnames` is empty then the group's `controls` will be executed
-locally; this enables testing of a provider's API to verify non-server
-resources.
-
-[InSpec controls]: http://inspec.io/docs/reference/dsl_inspec/
-
-###### Example .kitchen.yml
-
-```yaml
-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 consists of equivalently named
-  attributes for each output variable as well as a "terraform_state"
-  attribute containing the pathname of the state file; additional or
-  overridden associations can be added.
-
-- the default `controls` collection is empty
-
-- the default `hostnames` string is empty
-
-- the default `port` is obtained from the transport
-
-- the default `username` is obtained from the transport
+[Terraform]: https://www.terraform.io/index.html
+[Test Kitchen configuration]: https://docs.chef.io/config_yml_kitchen.html
+[Test Kitchen]: http://kitchen.ci/index.html
+[driver]: http://www.rubydoc.info/gems/kitchen-terraform/Kitchen/Driver/Terraform
+[examples directory]: https://github.com/newcontext-oss/kitchen-terraform/examples/
+[gem documentation]: http://www.rubydoc.info/gems/kitchen-terraform/index
+[installed with Bundler]: https://bundler.io/index.html#getting-started
+[provisioner]: http://www.rubydoc.info/gems/kitchen-terraform/Kitchen/Provisioner/Terraform
+[verifier]: http://www.rubydoc.info/gems/kitchen-terraform/Kitchen/Verifier/Terraform

data/lib/kitchen/driver/terraform.rb

@@ -14,63 +14,279 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen'
-require 'terraform/cli_config'
-require 'terraform/configurable'
-require 'terraform/version'
-
-module Kitchen
-  module Driver
-    # Terraform state lifecycle activities manager
-    class Terraform < ::Kitchen::Driver::Base
-      extend ::Terraform::CLIConfig
-
-      include ::Terraform::Configurable
-
-      kitchen_driver_api_version 2
-
-      no_parallel_for
-
-      def create(_state = nil); end
-
-      def destroy(_state = nil)
-        load_state { client.apply_destructively }
-      rescue ::Kitchen::StandardError, ::SystemCallError => error
-        raise ::Kitchen::ActionFailed, error.message
-      end
-
-      def verify_dependencies
-        verify_supported_version
-        check_deprecated_version
-      end
-
-      private
-
-      def check_deprecated_version
-        version.if_deprecated do
-          log_deprecation aspect: version.to_s,
-                          remediation: "Install #{::Terraform::Version.latest}"
-        end
-      end
-
-      def load_state(&block)
-        silent_client.load_state(&block)
-      rescue ::Errno::ENOENT => error
-        debug error.message
-      end
-
-      def verify_supported_version
-        version.if_not_supported do
-          raise ::Kitchen::UserError,
-                "#{version} is not supported\nInstall " \
-                  "#{::Terraform::Version.latest}"
-        end
-      end
-
-      def version
-        @version ||=
-          ::Terraform::Client.new(config: self, logger: debug_logger).version
-      end
+require "dry/monads"
+require "kitchen"
+require "kitchen/terraform/client/output"
+require "kitchen/terraform/client/plan"
+require "kitchen/terraform/client/version"
+require "kitchen/terraform/define_config_attribute"
+require "kitchen/terraform/define_integer_config_attribute"
+require "kitchen/terraform/define_string_config_attribute"
+require "terraform/configurable"
+
+# The kitchen-terraform driver is the bridge between Test Kitchen and Terraform. It manages the state of the configured
+# root Terraform module by invoking its workflow in a constructive or destructive manner.
+#
+# === Configuration
+#
+# ==== Example .kitchen.yml snippet
+#
+#   driver:
+#     name: terraform
+#     command_timeout: 1000
+#     cli: /usr/local/bin/terraform
+#     color: false
+#     directory: /directory/containing/terraform/configuration
+#     parallelism: 2
+#     plan: /terraform/plan
+#     state: /terraform/state
+#     variable_files:
+#       - /first/terraform/variable/file
+#       - /second/terraform/variable/file
+#     variables:
+#       variable_name: variable_value
+#
+# ==== Attributes
+#
+# ===== cli
+#
+# Description:: The path of the Terraform CLI to use for command execution.
+#
+# Type:: String
+#
+# Status:: Optional
+#
+# Default:: +"terraform"+
+#
+# ===== color
+#
+# Description:: Toggle to enable or disable colored output from the Terraform CLI commands.
+#
+# Type:: Boolean
+#
+# Status:: Optional
+#
+# Default:: +true+ if the Test Kitchen process is associated with a terminal device (tty); +false+ if it is not.
+#
+# ===== command_timeout
+#
+# Description:: The number of seconds to wait for the Terraform CLI commands to finish.
+#
+# Type:: Integer
+#
+# Status:: Optional
+#
+# Default:: +600+
+#
+# ===== directory
+#
+# Description:: The path of the directory containing the root Terraform module to be tested.
+#
+# Type:: String
+#
+# Status:: Optional
+#
+# Default:: The working directory of the Test Kitchen process.
+#
+# ===== parallelism
+#
+# Description:: The maximum number of concurrent operations to allow while walking the resource graph for the Terraform
+#               CLI apply and plan commands.
+# Type:: Integer
+#
+# Status:: Optional
+#
+# Default:: +10+
+#
+# ===== plan
+#
+# Description:: The path of the Terraform execution plan that will be generated and applied.
+#
+# Type:: String
+#
+# Status:: Optional
+#
+# Default:: A descendant of the working directory of the Test Kitchen process:
+#           +".kitchen/kitchen-terraform/<suite_name>/terraform.tfplan"+
+#
+# ===== state
+#
+# Description:: The path of the Terraform state that will be generated and managed.
+#
+# Type:: String
+#
+# Status:: Optional
+#
+# Default:: A descendant of the working directory of the Test Kitchen process:i
+#           +".kitchen/kitchen-terraform/<suite_name>/terraform.tfstate"+.
+#
+# ===== variable_files
+#
+# Description:: A collection of paths of Terraform variable files to be evaluated during the creation of the Terraform
+#               execution plan.
+#
+# Type:: Array
+#
+# Status:: Optional
+#
+# Default:: +[]+
+#
+# ===== variables
+#
+# Description:: A mapping of Terraform variable names and values to be overridden during the creation of the Terraform
+#               execution plan.
+#
+# Type:: Hash
+#
+# Status:: Optional
+#
+# Default:: +{}+
+#
+# @see ::Kitchen::Driver::Terraform::Workflow
+# @see https://en.wikipedia.org/wiki/Working_directory Working directory
+# @see https://www.terraform.io/docs/commands/plan.html Terraform execution plan
+# @see https://www.terraform.io/docs/configuration/variables.html Terraform variables
+# @see https://www.terraform.io/docs/internals/graph.html Terraform resource graph
+# @see https://www.terraform.io/docs/state/index.html Terraform state
+# @version 2
+class ::Kitchen::Driver::Terraform < ::Kitchen::Driver::Base
+  kitchen_driver_api_version 2
+
+  no_parallel_for
+
+  ::Kitchen::Terraform::DefineStringConfigAttribute.call attribute: :cli,
+                                                         plugin_class: self do
+    "terraform"
+  end
+
+  ::Kitchen::Terraform::DefineIntegerConfigAttribute.call attribute: :command_timeout,
+                                                          plugin_class: self do
+    600
+  end
+
+  ::Kitchen::Terraform::DefineConfigAttribute.call(
+    attribute: :color,
+    initialize_default_value: lambda do |_plugin|
+      ::Kitchen.tty?
+    end,
+    plugin_class: self,
+    schema: lambda do
+      required(:value).filled :bool?
+    end
+  )
+
+  ::Kitchen::Terraform::DefineStringConfigAttribute.call attribute: :directory,
+                                                         plugin_class: self do |plugin|
+    plugin[:kitchen_root]
+  end
+
+  ::Kitchen::Terraform::DefineIntegerConfigAttribute.call attribute: :parallelism,
+                                                          plugin_class: self do
+    10
+  end
+
+  ::Kitchen::Terraform::DefineStringConfigAttribute.call attribute: :plan,
+                                                         plugin_class: self do |plugin|
+    plugin.instance_pathname filename: "terraform.tfplan"
+  end
+
+  ::Kitchen::Terraform::DefineStringConfigAttribute.call attribute: :state,
+                                                         plugin_class: self do |plugin|
+    plugin.instance_pathname filename: "terraform.tfstate"
+  end
+
+  ::Kitchen::Terraform::DefineConfigAttribute.call(
+    attribute: :variable_files,
+    initialize_default_value: lambda do |_plugin|
+      []
+    end,
+    plugin_class: self,
+    schema: lambda do
+      required(:value).each :filled?, :str?
+    end
+  )
+
+  ::Kitchen::Terraform::DefineConfigAttribute.call(
+    attribute: :variables,
+    initialize_default_value: lambda do |_plugin|
+      {}
+    end,
+    plugin_class: self,
+    schema: lambda do
+      required(:value).value :hash?
+    end
+  )
+
+  include ::Terraform::Configurable
+
+  # The driver invokes its workflow in a constructive manner.
+  #
+  # @example
+  #   `kitchen create suite-name`
+  # @note The user must ensure that different suites utilize separate Terraform plan and state files if they are to run
+  #       the create action concurrently.
+  # @param _state [::Hash] the mutable instance and driver state; this parameter is ignored.
+  # @raise [::Kitchen::ActionFailed] if the result of the action is a failure.
+  # @return [::Dry::Monads::Either] the result of the workflow function.
+  # @see ::Kitchen::Driver::Terraform::Workflow
+  def create(_state)
+    self.class::Workflow.call(
+      config: config,
+      logger: logger
+    ).or do |failure|
+      raise ::Kitchen::ActionFailed, failure
+    end
+  end
+
+  # The driver invokes its workflow in a destructive manner.
+  #
+  # @example
+  #   `kitchen destroy suite-name`
+  # @note The user must ensure that different suites utilize separate Terraform plan and state files if they are to run
+  #       the destroy action concurrently.
+  # @param _state [::Hash] the mutable instance and driver state; this parameter is ignored.
+  # @raise [::Kitchen::ActionFailed] if the result of the action is a failure.
+  # @return [::Dry::Monads::Either] the result of the action.
+  # @see ::Kitchen::Driver::Terraform::Workflow
+  def destroy(_state)
+    self.class::Workflow.call(
+      config: config,
+      destroy: true,
+      logger: logger
+    ).or do |failure|
+      raise ::Kitchen::ActionFailed, failure
+    end
+  end
+
+  # The driver proxies the client output function.
+  #
+  # @return [::Dry::Monads::Either] the result of the Terraform Client Output function.
+  # @see ::Kitchen::Terraform::Client::Output
+  def output
+    ::Kitchen::Terraform::Client::Output.call cli: config.fetch(:cli), logger: debug_logger,
+                                              options: {color: config.fetch(:color), state: config.fetch(:state)},
+                                              timeout: config.fetch(:command_timeout)
+  end
+
+  # The driver verifies that the client version is supported.
+  #
+  # @raise [::Kitchen::UserError] if the version is not supported.
+  # @return [::Dry::Monads::Either] the result of the client version verification function.
+  # @see ::Kitchen::Driver::Terraform::VerifyClientVersion
+  # @see ::Kitchen::Terraform::Client::Version
+  def verify_dependencies
+    ::Kitchen::Terraform::Client::Version.call(
+      cli: config.fetch(:cli), logger: debug_logger, timeout: config.fetch(:command_timeout)
+    ).bind do |version|
+      self.class::VerifyClientVersion.call version: version
+    end.fmap do |verified_client_version|
+      logger.warn verified_client_version
+      verified_client_version
+    end.or do |failure|
+      raise ::Kitchen::UserError, failure
     end
   end
 end
+
+require "kitchen/driver/terraform/workflow"
+require "kitchen/driver/terraform/verify_client_version"