Class: Kitchen::Verifier::Terraform
- Inherits:
-
Base
- Object
- Base
- Kitchen::Verifier::Terraform
- Includes:
- Terraform::ConfigAttribute::Color, Terraform::ConfigAttribute::FailFast, Terraform::ConfigAttribute::Systems, Terraform::Configurable
- Defined in:
- lib/kitchen/verifier/terraform.rb
Overview
The verifier utilizes the / InSpec infrastructure testing framework 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
- Required
-
False
- Default
-
If a terminal emulator is associated with the Test Kitchen process then
true
; elsefalse
. - 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
- Required
-
False
- Default
-
true
- Example
-
fail_fast: false
systems
The value of the systems
key must be a sequence of systems.
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
If the systems
key is omitted then no tests will be executed.
Ruby Interface
This class implements the interface of Kitchen::Configurable which requires the following Reek suppressions: :reek:MissingSafeMethod { exclude: [ finalize_config!, load_needed_dependencies! ] }
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
-
#call(state) ⇒ void
The verifier enumerates through each host of each system and verifies the associated InSpec controls.
-
#doctor(_state) ⇒ Boolean
doctor checks the system and configuration for common errors.
-
#initialize(config = {}) ⇒ Kitchen::Verifier::Terraform
constructor
#initialize prepares a new instance of the class.
Methods included from Terraform::Configurable
Constructor Details
#initialize(config = {}) ⇒ Kitchen::Verifier::Terraform
#initialize prepares a new instance of the class.
130 131 132 133 134 135 136 |
# File 'lib/kitchen/verifier/terraform.rb', line 130 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.
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. end |
#doctor(_state) ⇒ Boolean
doctor checks the system and configuration for common errors.
122 123 124 |
# File 'lib/kitchen/verifier/terraform.rb', line 122 def doctor(_state) false end |