Module: Kitchen::Terraform::ConfigAttribute::Systems

Included in:: Verifier::Terraform

Defined in:: lib/kitchen/terraform/config_attribute/systems.rb

Overview

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

Instance Method Summary collapse

#doctor_config_systems ⇒ Boolean

#doctor_config_systems validates the systems configuration.

Instance Method Details

#doctor_config_systems ⇒ `Boolean`

#doctor_config_systems validates the systems configuration.

Returns:

(Boolean) —

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

# File 'lib/kitchen/terraform/config_attribute/systems.rb', line 586

def doctor_config_systems
  errors = false

  if config_systems.empty?
    errors = true
    logger.error "systems is empty"
  end

  errors
end

Module: Kitchen::Terraform::ConfigAttribute::Systems

Overview

InSpec Profiles

Required Keys

name

backend

Optional Keys

attrs

attrs_outputs

backend_cache

bastion_host

bastion_host_output

bastion_port

bastion_user

controls

enable_password

hosts

hosts_output

key_files

password

path

port

profile_locations

proxy_command

reporter

self_signed

shell

shell_command

shell_options

show_progress

ssl

sudo

sudo_command

sudo_options

sudo_password

user

vendor_cache

Instance Method Summary collapse

Instance Method Details

#doctor_config_systems ⇒ Boolean

#doctor_config_systems ⇒ `Boolean`