Class: Kitchen::Verifier::Pulumi

Inherits:
Object
  • Object
show all
Includes:
Configurable, Logging, Pulumi::ConfigAttribute::Color, Pulumi::ConfigAttribute::FailFast, Pulumi::ConfigAttribute::Systems, Pulumi::Configurable
Defined in:
lib/kitchen/verifier/pulumi.rb

Overview

The verifier utilizes the InSpec infrastructure testing framework to verify the behaviour and state of resources in the Pulumi 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 running the associated InSpec controls against the hosts of each system. The outputs of the Pulumi state are retrieved and exposed as attributes to the InSpec controls.

===== Retrieving the Pulumi Output

pulumi stack output -json

=== Configuration Attributes

The configuration attributes of the verifier control the behaviour of the InSpec runner. Within the .kitchen.yml, these attributes must be declared in the +verifier+ mapping along with the plugin name.

verifier: name: pulumi a_configuration_attribute: some value

==== color

Attribute to toggle colored output from systems invoked by the plugin

==== fail_fast

Attribute used to determine if Kitchen should halt on the first error during verification.

==== 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 Pulumi stack. 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 Pulumi stack config keys configured with the driver's config attribute and the values of any Pulumi stack outputs are associated with equivalently named InSpec profile attributes, prefixed with input_ or output_, respectively. The values of the output variables are also associated with equivalently named profile attributes without any prefixes for backward compatibility. Output variable associations can be overridden with the attrs_outputs key. For example, the value of an input variable named test will be associated with an attribute named input_test, and the value of an output variable 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: pulumi 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: pulumi 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: pulumi 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 Pulumi 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: pulumi 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: pulumi 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.

Example kitchen.yml verifier: name: pulumi systems: - name: a system backend: ssh bastion_host: bastion-host.domain

====== 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+ key.

Example kitchen.yml verifier: name: pulumi systems: - name: a system backend: ssh bastion_host: bastion-host.domain 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+ key.

Example kitchen.yml verifier: name: pulumi systems: - name: a system backend: ssh bastion_host: bastion-host.domain 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: pulumi 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: pulumi 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: pulumi 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 Pulumi 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: pulumi 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 Pulumi state.

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

Example kitchen.yml verifier: name: pulumi 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: pulumi 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: pulumi 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: pulumi 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 /test/integration/.

Example kitchen.yml verifier: name: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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: pulumi 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! ] }

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Pulumi::Configurable

#finalize_config!

Methods included from Pulumi::ConfigAttribute::Systems

#config_systems_default_value, to_sym

Methods included from Pulumi::ConfigAttributeCacher

#define_cache, extended

Methods included from Pulumi::ConfigAttribute::FailFast

#config_fail_fast_default_value, to_sym

Methods included from Pulumi::ConfigAttribute::Color

#config_color_default_value, to_sym

Constructor Details

#initialize(configuration = {}) ⇒ Pulumi

Returns a new instance of Pulumi.


77
78
79
80
81
82
83
# File 'lib/kitchen/verifier/pulumi.rb', line 77

def initialize(configuration = {})
  init_config configuration
  self.inspec_options_mapper = ::Kitchen::Pulumi::InSpecOptionsMapper.new
  self.error_messages = []
  self.inputs = {}
  self.outputs = {}
end

Instance Attribute Details

#inputsObject

Returns the value of attribute inputs


75
76
77
# File 'lib/kitchen/verifier/pulumi.rb', line 75

def inputs
  @inputs
end

#outputsObject

Returns the value of attribute outputs


75
76
77
# File 'lib/kitchen/verifier/pulumi.rb', line 75

def outputs
  @outputs
end

Instance Method Details

#call(_kitchen_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:

  • _kitchen_state (::Hash)

    the mutable instance and verifier state.

Raises:

  • (::Kitchen::ActionFailed)

    if result of the action is failure.


93
94
95
96
97
98
99
100
101
# File 'lib/kitchen/verifier/pulumi.rb', line 93

def call(_kitchen_state)
  load_variables
  verify_systems
  unless error_messages.empty?
    raise ::Kitchen::ActionFailed, error_messages.join("\n\n")
  end
rescue ::Kitchen::Pulumi::Error => e
  raise ::Kitchen::ActionFailed, e.message
end

#doctor(_kitchen_state) ⇒ Boolean

Checks the system and configuration for common errors.

Parameters:

  • _kitchen_state (::Hash)

    the mutable Kitchen instance state.

Returns:

  • (Boolean)

    false

See Also:


108
109
110
# File 'lib/kitchen/verifier/pulumi.rb', line 108

def doctor(_kitchen_state)
  false
end