Class: Kitchen::Verifier::Terraform

Inherits:
Base
  • Object
show all
Includes:
Terraform::ConfigAttribute::Color, Terraform::ConfigAttribute::FailFast, Terraform::ConfigAttribute::Systems, Terraform::Configurable
Defined in:
lib/kitchen/verifier/terraform.rb

Overview

The Terraform verifier utilizes InSpec to verify the behaviour and state of resources in the Terraform state.

Commands

The following command-line commands are provided by the verifier.

kitchen verify

A Kitchen instance is verified by iterating through the systems and executing the associated InSpec controls against the hosts of each system. The outputs of the Terraform state are retrieved and exposed as attributes to the InSpec controls.

Configuration Attributes

The configuration attributes of the verifier control the behaviour of the InSpec runner. Within the Test Kitchen configuration file, these attributes must be declared in the verifier mapping along with the plugin name.

verifier:
  name: terraform
  a_configuration_attribute: some value

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.

fail_fast

This attribute toggles fail fast behaviour when verifying systems.

If fail fast behaviour is enabled then Kitchen will halt on the first error raised by a system during verification; else errors raised by systems will be queued until all systems have attempted verification.

Type

Boolean

Required

False

Default

true

Example

fail_fast: false

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 / InSpec tests against a system in the Terraform state. The keys of a system mapping correlate to the arguments and the options of the inspec exec command-line interface subcomamand.

InSpec Profiles

All systems within the same Kitchen suite are by default tested using the same / 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 profile_locations key.

The values of any Terraform variables configured with the driver’s variables attribute and the values of any Terraform outputs which exist in the Terraform state are associated with equivalently named InSpec profile attributes, prefixed with input_ or output_, 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 attrs_outputs 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.

Example kitchen.yml

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 InSpec backend for connections to the system.

The scalar must match the name of one the available backends.

Example kitchen.yml

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 InSpec profile attributes files.

Example kitchen.yml

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 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.

Example kitchen.yml

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.

Example kitchen.yml

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 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.

Example kitchen.yml

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.

Example kitchen.yml

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.

Example kitchen.yml

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.

Example kitchen.yml

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 / 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.

Example kitchen.yml

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 backend: ssh.

Example kitchen.yml

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.

Example kitchen.yml

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.

Example kitchen.yml

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 Secure Shell (SSH) authentication with hosts in the Terraform state.

The key_files key must be used in combination with backend: ssh.

Example kitchen.yml

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.

Example kitchen.yml

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 backend: winrm.

Example kitchen.yml

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 backend: ssh.

If the port key is omitted then the value of the port key of the Test Kitchen transport will be used.

Example kitchen.yml

verifier:
  name: terraform
  systems:
    - name: a system
      backend: ssh
      port: 1234
profile_locations

The value of the profile_locations key is a sequence of scalars which is used to locate / InSpec profiles containing the controls to be executed against the system. This key corresponds to the LOCATIONS argument of inspec exec.

The default value contains a single scalar which assumes that a profile exists locally for the associated Kitchen suite at <KITCHEN ROOT>/test/integration/<KITCHEN SUITE NAME>.

Example kitchen.yml

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 backend: ssh.

Example kitchen.yml

verifier:
  name: terraform
  systems:
    - name: a system
      backend: ssh
      proxy_command: ssh [email protected] -W %h:%p
reporter

The value of the reporter key is a sequence of scalars which is used to select the InSpec reporters for reporting test output.

The scalars must match the names of the available reporters.

Example kitchen.yml

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 backend: winrm.

Example kitchen.yml

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.

Example kitchen.yml

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 shell: true.

Example kitchen.yml

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 shell: true.

Example kitchen.yml

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.

Example kitchen.yml

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 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 backend: winrm.

Example kitchen.yml

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 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.

Example kitchen.yml

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 sudo: true.

Example kitchen.yml

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 sudo: true.

Example kitchen.yml

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 sudo: true.

Example kitchen.yml

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.

Example kitchen.yml

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.

Example kitchen.yml

verifier:
  name: terraform
  systems:
    - name: a system
      backend: local
      vendor_cache: /opt/inspec-cache

Ruby Interface

This class implements the interface of Kitchen::Configurable which requires the following Reek suppressions: :reek:MissingSafeMethod { exclude: [ finalize_config!, load_needed_dependencies! ] }

Examples:

Describe the verify command

kitchen help verify

Verify a Test Kitchen instance

kitchen verify default-ubuntu

Version:

  • 2

Constant Summary collapse

UNSUPPORTED_BASE_ATTRIBUTES =

UNSUPPORTED_BASE_ATTRIBUTES is the list of attributes inherited from Kitchen::Verifier::Base which are not supported by Kitchen::Verifier::Terraform.

[
  :chef_omnibus_root,
  :command_prefix,
  :http_proxy,
  :https_proxy,
  :ftp_proxy,
  :root_path,
  :sudo,
  :sudo_command,
]

Instance Method Summary collapse

Methods included from Terraform::Configurable

#finalize_config!, included

Methods included from Terraform::ConfigAttribute::Systems

#doctor_config_systems

Constructor Details

#initialize(config = {}) ⇒ Kitchen::Verifier::Terraform

#initialize prepares a new instance of the class.

Parameters:

  • config (Hash) (defaults to: {}) —

    the verifier configuration.



138
139
140
141
142
143
144
 
# File 'lib/kitchen/verifier/terraform.rb', line 138

def initialize(config = {})
  init_config config
  self.action_failed = ::Kitchen::Terraform::Raise::ActionFailed.new logger: logger
  self.client_error = ::Kitchen::Terraform::Raise::ClientError.new logger: logger
  self.outputs = {}
  self.variables = {}
end

Instance Method Details

#call(state) ⇒ void

This method returns an undefined value.

The verifier enumerates through each host of each system and verifies the associated InSpec controls.

Examples:

`kitchen verify suite-name`

Parameters:

  • state (Hash) —

    the mutable instance and verifier state.

Raises:

  • (Kitchen::ActionFailed) —

    if the result of the action is a failure.



109
110
111
112
113
114
115
 
# File 'lib/kitchen/verifier/terraform.rb', line 109

def call(state)
  load_variables state: state
  load_outputs state: state
  verify_systems
rescue => error
  action_failed.call message: error.message
end

#doctor(_state) ⇒ Boolean

doctor checks the system and configuration for common errors.

Parameters:

  • _state (Hash) —

    the mutable Kitchen instance state.

Returns:

  • (Boolean) —

    true if any errors are found; false if no errors are found.



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/kitchen/verifier/terraform.rb', line 121

def doctor(_state)
  errors = false

  methods.each do |method|
    next if !method.match? /doctor_config_.*/

    error = send method
    errors = errors || error
  end

  errors
end