kitchen-terraform 5.7.1 → 6.1.0

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,21 +15,569 @@
 # limitations under the License.
 
 require "kitchen/terraform/config_attribute"
-require "kitchen/terraform/config_schemas/systems"
+require "kitchen/terraform/config_attribute_contract/systems"
 
 module Kitchen
   module Terraform
     class ConfigAttribute
-      # {include:Kitchen::Terraform::ConfigSchemas::Systems}
+      # The value of the +systems+ key must be a sequence of systems.
       #
       # If the +systems+ key is omitted then no tests will be executed.
+      #
+      # A system is a mapping which is used to configure the execution of {https://www.inspec.io/docs/ InSpec tests}
+      # against a system in the Terraform state. The keys of a system mapping correlate to the arguments and the
+      # options of the {https://www.inspec.io/docs/reference/cli/#exec +inspec exec+} command-line interface
+      # subcomamand.
+      #
+      # ===== InSpec Profiles
+      #
+      # All systems within the same {https://kitchen.ci/docs/getting-started/adding-suite Kitchen suite} are by default
+      # tested using the same {https://www.inspec.io/docs/reference/profiles/ InSpec profile}. The profile must be
+      # implemented in the directory located at `<Kitchen root>/test/integration/<suite name>`. This behaviour can be
+      # overridden with the <code>profile_locations</code> key.
+      #
+      # The values of any {https://www.terraform.io/docs/configuration/variables.html Terraform variables} configured
+      # with the driver's <code>variables</code> attribute and the values of any
+      # {https://www.terraform.io/docs/configuration/outputs.html Terraform outputs} which exist in the Terraform state
+      # are associated with equivalently named
+      # {https://www.inspec.io/docs/reference/profiles/#profile-attributes InSpec profile attributes}, prefixed with
+      # <code>input_</code> or <code>output_</code>, respectively. The values of the outputs are also associated with
+      # equivalently named profile attributes without any prefixes for backward compatibility. Output associations can
+      # be overridden with the <code>attrs_outputs</code> key. For example, the value of a variable named `test` will
+      # be associated with an attribute named `input_test`, and the value of an output named `test` will be associated
+      # with an attribute named `output_test` as well as an attribute named `test`.
+      #
+      # ===== Required Keys
+      #
+      # The following keys must be included by every system.
+      #
+      # ====== name
+      #
+      # The value of the +name+ key is a scalar which is used to refer to the system for logging purposes.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #
+      # ====== backend
+      #
+      # The value of the +backend+ key is a scalar which is used to select the
+      # {https://www.inspec.io/docs/reference/cli/#exec InSpec backend} for connections to the system.
+      #
+      # The scalar must match the name of one the available backends.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: docker
+      #
+      # ===== Optional Keys
+      #
+      # The following keys may be included by any system to alter the behaviour of InSpec. Any key which is omitted
+      # will be associated with a default value as defined by InSpec except where otherwise noted.
+      #
+      # ====== attrs
+      #
+      # The value of the +attrs+ key is a sequence of scalars which is used to locate any
+      # {https://www.inspec.io/docs/reference/profiles/#profile-attributes InSpec profile attributes} files.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         attrs:
+      #           - /path/to/first_attributes.yml
+      #           - /path/to/second_attributes.yml
+      #
+      # ====== attrs_outputs
+      #
+      # The value of the +attrs_outputs+ key is a mapping of scalars to scalars which is used to define
+      # {https://www.inspec.io/docs/reference/profiles/#profile-attributes InSpec profile attributes} with the values
+      # of Terraform outputs.
+      #
+      # The use of the +attrs_outputs+ key is only necessary to override the default definitions of profile attributes
+      # with names and values equivalent to the outputs.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         attrs_outputs:
+      #           an_attribute_name: an_output_name
+      #
+      # ====== backend_cache
+      #
+      # The value of the +backend_cache+ key is a boolean which is used to toggle the caching of InSpec backend command
+      # output.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         backend_cache: false
+      #
+      # ====== bastion_host
+      #
+      # The value of the +bastion_host+ key is a scalar which is used as the hostname of a
+      # {https://en.wikipedia.org/wiki/Bastion_host bastion host} to connect to before connecting to hosts in the
+      # system.
+      #
+      # The +bastion_host+ key must be used in combination with a backend which supports remote connections.
+      #
+      # The +bastion_host_output+ key will take priority over the +bastion_host+ key.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         bastion_host: bastion-host.domain
+      #
+      # ====== bastion_host_output
+      #
+      # The value of the +bastion_host_output+ key is a scalar which is used to obtain the address of a bastion host in
+      # the system from a Terraform output.
+      #
+      # The scalar must match the name of an output with a value which is a string.
+      #
+      # The +bastion_host_output+ key must be used in combination with a backend which enables remote connections.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         bastion_host_output: an_output
+      #
+      # ====== bastion_port
+      #
+      # The value of the +bastion_port+ key is an integer which is used as the port number to connect to on the bastion
+      # host.
+      #
+      # The +bastion_port+ key must be used in combination with the +bastion_host_output+ key or the +bastion_host+ key.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         bastion_host_output: an_output
+      #         bastion_port: 1234
+      #
+      # ====== bastion_user
+      #
+      # The value of the +bastion_user+ key is a scalar which is used as the username for authentication with the
+      # bastion host.
+      #
+      # The +bastion_user+ key must be used in combination with the +bastion_host_output+ key or the +bastion_host+ key.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         bastion_host_output: an_output
+      #         bastion_user: bastion-user
+      #
+      # ====== controls
+      #
+      # The value of the +controls+ key is a sequence of scalars which is used to select for execution against the
+      # system a subset of the {https://www.inspec.io/docs/reference/dsl_inspec/ InSpec controls} of the profile.
+      #
+      # The use of the +controls+ key is only necessary if the system should not be tested with all of the controls of # the profile.
+      #
+      # The scalars must match the names of the controls, not the names of the control files.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: first system
+      #         backend: local
+      #         controls:
+      #           - first control
+      #           - third control
+      #       - name: second system
+      #         backend: local
+      #         controls:
+      #           - second control
+      #           - fourth control
+      #
+      # ====== enable_password
+      #
+      # The value of the +enable_password+ key is a scalar which is used as the password for authentication with a
+      # Cisco IOS device in enable mode.
+      #
+      # The +enable_password+ key must be used in combination with <tt>backend: ssh</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         enable_password: Cisc0!
+      #
+      # ====== hosts
+      #
+      # The value of the +hosts+ key is a sequence of scalars which is used as addresses of hosts in the system.
+      #
+      # The +hosts+ key must be used in combination with a backend which enables remote connections.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts:
+      #           - hostname.domainname
+      #
+      # ====== hosts_output
+      #
+      # The value of the +hosts_output+ key is a scalar which is used to obtain the addresses of hosts in the system
+      # from a Terraform output.
+      #
+      # The scalar must match the name of an output with a value which is a string or an array of strings.
+      #
+      # The +hosts_output+ key must be used in combination with a backend which enables remote connections.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #
+      # ====== key_files
+      #
+      # The value of the +key_files+ key is a sequence of scalars which is used to locate key files (also known as
+      # identity files) for {https://linux.die.net/man/1/ssh Secure Shell (SSH) authentication} with hosts in the
+      # Terraform state.
+      #
+      # The +key_files+ key must be used in combination with <tt>backend: ssh</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         key_files:
+      #           - /path/to/first/key/file
+      #           - /path/to/second/key/file
+      #
+      # ====== password
+      #
+      # The value of the +password+ key is a scalar which is used as the password for authentication with hosts in the
+      # system.
+      #
+      # The +password+ key must be used in combination with a backend which supports password authentication.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         password: Th3P455I5Th3W0rd
+      #
+      # ====== path
+      #
+      # The value of the +path+ key is a scalar which is used as the login path when connecting to a host in the system.
+      #
+      # The +path+ key must be used in combination with <tt>backend: winrm</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: winrm
+      #         path: /login
+      #
+      # ====== port
+      #
+      # The value of the +port+ key is an integer which is used as the port number when connecting via SSH to the hosts
+      # of the system.
+      #
+      # The +port+ key must be used in combination with <tt>backend: ssh</tt>.
+      #
+      # If the +port+ key is omitted then the value of the +port+ key of the Test Kitchen transport will be used.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         port: 1234
+      #
+      # ====== profile_locations
+      #
+      # The value of the <code>profile_locations</code> key is a sequence of scalars which is used to locate
+      # {https://www.inspec.io/docs/reference/profiles/ InSpec profiles} containing the controls to be executed against
+      # the system. This key corresponds to the LOCATIONS argument of <code>inspec exec</code>.
+      #
+      # The default value contains a single scalar which assumes that a profile exists locally for the associated
+      # {https://kitchen.ci/docs/getting-started/adding-suite Kitchen suite} at
+      # <code><KITCHEN ROOT>/test/integration/<KITCHEN SUITE NAME></code>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         profile_locations:
+      #           - supermarket://username/linux-baseline
+      #           - /path/to/profile
+      #           - /path/to/a_test.rb
+      #
+      # ====== proxy_command
+      #
+      # The value of the +proxy_command+ key is a scalar which is used as a proxy command when connecting to a host via
+      # SSH.
+      #
+      # The +proxy_command+ key must be used in combination with <tt>backend: ssh</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         proxy_command: ssh root@127.0.0.1 -W %h:%p
+      #
+      # ====== reporter
+      #
+      # The value of the +reporter+ key is a sequence of scalars which is used to select the
+      # {https://www.inspec.io/docs/reference/reporters/#supported-reporters InSpec reporters}
+      # for reporting test output.
+      #
+      # The scalars must match the names of the available reporters.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         reporter:
+      #           - cli
+      #           - documentation
+      #
+      # ====== self_signed
+      #
+      # The value of the +self_signed+ key is a boolean which is used to toggle permission for self-signed certificates
+      # during testing of Windows hosts.
+      #
+      # The +self_signed+ key must be used in combination with <tt>backend: winrm</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: winrm
+      #         self_signed: true
+      #
+      # ====== shell
+      #
+      # The value of the +shell+ key is a boolean which is used to toggle the use of a subshell when executing tests on
+      # hosts in the system.
+      #
+      # The +shell+ key is only effective for a system which has Unix-like hosts.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         shell: true
+      #
+      # ====== shell_command
+      #
+      # The value of the +shell_command+ key is a scalar which is used to override the default shell command used to
+      # instantiate a subshell.
+      #
+      # The +shell_command+ key must be used in combination with <tt>shell: true</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         shell: true
+      #         shell_command: /bin/ksh
+      #
+      # ====== shell_options
+      #
+      # The value of the +shell_options+ key is a scalar which is used to provide options to the subshell.
+      #
+      # The +shell_options+ key must be used in combination with <tt>shell: true</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         shell: true
+      #         shell_options: -v
+      #
+      # ====== show_progress
+      #
+      # The value of the +show_progress+ key is a boolean which is used to toggle the display of progress while tests
+      # are executing.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         show_progress: false
+      #
+      # ====== ssl
+      #
+      # The value of the +ssl+ key is a boolean which is used to toggle the use of
+      # {https://en.wikipedia.org/wiki/Transport_Layer_Security Transport Layer Security (TLS)} when connecting to
+      # hosts in the system. InSpec's reference to Secure Socket Layer (SSL) is a misnomer as that protocol has been
+      # deprecated in favour of TLS.
+      #
+      # The +ssl+ key must be used in combination with <tt>backend: winrm</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: winrm
+      #         ssl: true
+      #
+      # ====== sudo
+      #
+      # The value of the +sudo+ key is a boolean which is used to toggle the use of
+      # {https://en.wikipedia.org/wiki/Sudo sudo} for obtaining superuser permissions when executing tests on hosts in
+      # the system.
+      #
+      # The +sudo+ key is only effective for a system which has Unix-like hosts.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         sudo: true
+      #
+      # ====== sudo_command
+      #
+      # The value of the +sudo_command+ key is a scalar which is used to override the default command used to
+      # invoke sudo.
+      #
+      # The +sudo_command+ key must be used in combination with <tt>sudo: true</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         sudo: true
+      #         sudo_command: /bin/sudo
+      #
+      # ====== sudo_options
+      #
+      # The value of the +sudo_options+ key is a scalar which is used to provide options to the sudo command.
+      #
+      # The +sudo_options+ key must be used in combination with <tt>sudo: true</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         sudo: true
+      #         sudo_options: -u admin
+      #
+      # ====== sudo_password
+      #
+      # The value of the +sudo_password+ key is a scalar which is used as the password for authentication with the sudo
+      # command.
+      #
+      # The +sudo_password+ key must be used in combination with <tt>sudo: true</tt>.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         hosts_output: an_output
+      #         sudo: true
+      #         sudo_password: Th3P455I5Th3W0rd
+      #
+      # ====== user
+      #
+      # The value of the +user+ key is a scalar which is used as the username for authentication with hosts in the
+      # system.
+      #
+      # The +user+ key must be used in combination with a backend which supports user authentication.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: ssh
+      #         user: tester
+      #
+      # ====== vendor_cache
+      #
+      # The value of the +vendor_cache+ key is a scalar which is used as the pathname of the directory in which InSpec
+      # will cache dependencies of the profile.
+      #
+      # <em>Example kitchen.yml</em>
+      #   verifier:
+      #     name: terraform
+      #     systems:
+      #       - name: a system
+      #         backend: local
+      #         vendor_cache: /opt/inspec-cache
       module Systems
         ::Kitchen::Terraform::ConfigAttribute.new(
           attribute: :systems,
           default_value: lambda do
             []
           end,
-          schema: ::Kitchen::Terraform::ConfigSchemas::Systems,
+          schema: ::Kitchen::Terraform::ConfigAttributeContract::Systems.new,
         ).apply config_attribute: self
       end
     end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
 
 require "kitchen/terraform/config_attribute"
 require "kitchen/terraform/config_attribute_cacher"
-require "kitchen/terraform/config_schemas/array_of_strings"
+require "kitchen/terraform/config_attribute_contract/array_of_strings"
 require "kitchen/terraform/file_path_config_attribute_definer"
 
 module Kitchen
@@ -42,7 +42,7 @@ module Kitchen
           def included(plugin_class)
             ::Kitchen::Terraform::FilePathConfigAttributeDefiner.new(
               attribute: self,
-              schema: ::Kitchen::Terraform::ConfigSchemas::ArrayOfStrings,
+              schema: ::Kitchen::Terraform::ConfigAttributeContract::ArrayOfStrings.new,
             ).define plugin_class: plugin_class
           end
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
 
 require "kitchen"
 require "kitchen/terraform/config_attribute"
-require "kitchen/terraform/config_schemas/boolean"
+require "kitchen/terraform/config_attribute_contract/boolean"
 
 module Kitchen
   module Terraform
@@ -34,7 +34,7 @@ module Kitchen
           default_value: lambda do
             true
           end,
-          schema: ::Kitchen::Terraform::ConfigSchemas::Boolean,
+          schema: ::Kitchen::Terraform::ConfigAttributeContract::Boolean.new,
         ).apply config_attribute: self
       end
     end

data/lib/kitchen/terraform/config_attribute.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/kitchen/terraform/config_attribute_cacher.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2016-2019 New Context, Inc.
+# Copyright 2016-2021 Copado NCS LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/kitchen/terraform/config_attribute_contract/array_of_strings.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Copyright 2016-2021 Copado NCS LLC
+#
+# 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/validation"
+
+module Kitchen
+  module Terraform
+    module ConfigAttributeContract
+      # ArrayOfStrings is the class of objects that provide a configuration attribute contract for an array of strings.
+      class ArrayOfStrings < ::Dry::Validation::Contract
+        schema do
+          required(:value).array :filled?, :str?
+        end
+      end
+    end
+  end
+end