Nodes configuration

The "nodespec" metadata

In order to qualify your RSpec example group as a nodespec test you must define a nodespec metadata key. The content of the metadata value will be used to identify the minimal configuration information necessary in order for serverspec and nodespec to be able to connect to the server under test. This information, or set of options, is used to configure a communication adapter in nodespec.

The nodespec metadata can be:

• a Hash. In this case you're inlining the configuration in your spec file.
• a String. In this case the string value identifies the options into a yaml configuration file.
• any object (typically you would set it to true). In this case you're not defining any specific configuration, but you're still setting a metadata value for :nodespec, that is necessary to run your tests.

Configuring nodespec through a Hash

This is the most straightforward way of configuring your communication to the target host, and makes the test very explicit about the connection details. Most of the examples throughout this page will use a hash to demonstrate the different options for each adapter.

IMPORTANT: at the moment nodespec expects no difference between values coming from a yaml file or an inline Hash, and there are no automatic conversion of keys into symbols. Therefore remember to always use strings or symbols to refer to the configuration keys according to how you write your yaml config file.

Configuring nodespec through a YAML file

Using a configuration file could be more effective if you plan to share configuration options between different nodes, because you can centralise your configuration values in one place. By default nodespec will try and find a nodespec_config.yml file in the root of your project directory. Alternatively you can use a different file by passing its path to the environment variable NODESPEC_CONFIG.

Example configuration file

vagrant-vm2:
  adapter: vagrant
  vm_name: nodespec_vm_2
dbserver1:
  adapter: ssh
  host: 10.2.123.80
  user: root
  keys: /path/to/keyfile
iis-server:
  os: Windows
  adapter: winrm
  host: test.web.local
  user: testadmin
  pass: <somepassword>
  transport: ssl
  basic_auth_only: true

And this is how you could write a test for your database server in RSpec:

describe 'database host', nodespec: 'dbserver1' do
... # your tests here
end

The example group description: the example group description (the string that comes after the describe in RSpec) could also be used to identify the target hostname in your test, so you wouldn't have to code it in your configuration. For instance the previous test could also have been written like this:

describe '10.2.123.80', nodespec: 'dbserver1' do
... # your tests here
end

See the details on how to configure the different adapters for more information.

Communication adapters

Currently nodespec support the following ways to communicate to a target node:

• native: local, you run specs against your own host (i.e. no configuration required)
• ssh: for typical access to UN*X like hosts
• winrm: for typical access to Windows based servers
• aws_ec2: to access Amazon EC2 instances.
• vagrant: to access any vagrant vm running on your host

The os option

The operating system of the machine you're testing is the only option that is common to each adapter. Usually you would only have to define it if you're connecting to a Windows machine, otherwise by default the underlying framework (specinfra) will assume a UN*X like system and try to detect the particular unix flavour. Of course you can always directly set it as a specific os (e.g. 'RedHat' or 'Ubuntu'). See the Serverspec documentation for more details.

Native adapter

This adapter normally does not require any configuration. Basically you're testing the same host where you're running the specs. The only option you may have to set is the operating system of choice, i.e. you have to explicitly set it to "Windows" if you're running on that OS.

Example:

describe 'my laptop', nodespec: true do
... # your tests here
end

On a Windows host:

describe 'my laptop', nodespec: {'os' => 'Windows'} do
... # your tests here
end

Ssh adapter

Use this adapter when you want to connect to your server through ssh. At a minimum you will need to specify a hostname to connect to (relying on your OpenSSH config for the rest).

The example group description can be used to define the target host. Alternatively you must set the 'host' option in the node adapter configuration. Other useful options you can include are 'port', 'user', 'password', 'keys', and more in general any of the options documented in net-ssh.

Example:

describe "demo.server1.local", nodespec: {
  'adapter'  => 'ssh',
  'user'     => 'someuser',
  'password' => 'somepassword'
} do
... # your tests here
end

Winrm adapter

The Winrm adapter allows you to connect to Windows machines running Windows Remote Management.

This component requires the WinRb/WinRM ('winrm') gem, so you need to make sure you have it installed with your ruby.

As for the ssh adapter, you must specify the target host through the example group description or directly via a 'host' option. The 'port' option defaults to 5985, but you can override it if you wish.

Important: Remember to set the 'os' option to 'Windows', as Windows & Winrm is the only os/adapter supported combination.

Any other option you define will be used to configure the winrm connection. Refer to the winrm gem documentation for more information.

Example:

describe "demo.server1.local", nodespec: {
  'os'              => 'Windows',
  'adapter'         => 'winrm',
  'port'            => 55985,
  'user'            => 'someuser',
  'pass'            => 'somepassword',
  'transport'       => 'ssl',
  'basic_auth_only' => true
} do
... # your tests here
end

Vagrant adapter

With the Vagrant adapter you define a connection to a vagrant vm running on your host. The only required parameter for this adapter is the 'vm_name', which specifies the vagrant virtual machine you want to connect. You can specify the vm_name through the example group description or through the adapter options, for example:

describe "vm_1", nodespec: { 'adapter'  => 'vagrant' } do
... # your tests here
end

or, alternatively:

describe "my vagrant vm", nodespec: { 'adapter'  => 'vagrant', 'vm_name' => 'vm_1' } do
... # your tests here
end

In order to run the vagrant adapter you must have a Vagrantfile in the root of your project where the virtual machine name(s) are defined.

AWS EC2 adapter

As the name suggests, this adapter lets you define a connection to an EC2 instance in the Amazon cloud. The adapter requires to know the id of the EC2 instance in order to retrieve the instance details from AWS and determine its hostname. Again, the instance id can be specified through the example description or through the 'instance' option of the adapter.

The specific connection type will then fall back to be ssh (the default) or winrm, with their respective options set through a nested hash.

Example (Amazon ubuntu instance):

describe "i-8f4b71b0", nodespec: {
  'adapter' => 'aws_ec2',
  'ssh'     => {
     'port' => 7001,
     'user' => 'ubuntu',
     'keys' => 'path/to/mykey'
  }
} do
... # your tests here
end

Or a Windows instance:

describe "my aws instance", nodespec: {
  'adapter'  => 'aws_ec2',
  'instance' => 'i-9jd312b4',
  'os'       => 'Windows',
  'winrm'     => {
     'transport'    => 'plaintext',
     'user'         => 'myuser',
     'pass'         => 'mypass',
     'disable_sspi' => true
  }
} do
... # your tests here
end