inspec/docs/migration.md

title
InSpec Migration Guide

Migrate from Serverspec to InSpec

How is InSpec different from Serverspec

We've written a complete blog post about that topic: The Road to InSpec

Is InSpec suitable for infrastructure testing?

InSpec is a framework that allows you to run infrastructure testing as well as compliance testing. The compliance features are always optional and provide customers a way to use InSpec for both use-cases. To ensure we build the best infrastructure testing, we migrate our cookbooks chef-cookbooks to InSpec.

Which Serverspec resources are available in InSpec?

The following resources are available in InSpec:

Serverspec	InSpec
bond	bond
bridge	bridge
command	command
cron	crontab
docker_container	docker_container
docker_image	docker_image
file	file
group	group
host	host
interface	interface
iis_website	iis_website
iis_app_pool	iis_website
iptables	iptables
kernel_module	kernel_module
linux_kernel_parameter	kernel_parameter
mysql_config	mysql_conf
package	package
port	port
ppa	apt
process	processes
service	service
user	user
windows_feature	windows_feature
windows_registry_key	registry_key
x509_certificate	x509_certificate
yumrepo	yum
zfs	zfs_pool

Some Serverspec resources are not available yet. We implement those resources based on user feedback. If you need a resource that is not available in InSpec, please open an Github issue. The list of resources that are not available in InSpec:

• cgroup
• default_gateway
• ip6tables
• ipfilter
• ipnat
• linux_audit_system
• lxc
• mail_alias
• php_config
• routing_table
• selinux
• selinux_module
• x509_private_key

In addition InSpec provides additional resources that are not available in Serverspec:

• apache_conf
• apt
• audit_policy
• auditd_conf
• bash
• csv
• etc_shadow
• gem
• grub_conf
• inetd_conf
• ini
• json
• npm
• ntp_conf
• oneget
• pip
• powershell
• security_policy
• ssh_config
• sshd_config
• sys_info

How do I migrate my Serverspec tests to InSpec

For most cases, the migration to InSpec is pretty straight forward. First, replace the current verifier in kitchen.yml configuration with:

verifier:
  name: inspec

Second, rename the directory test/integration/default/serverspec to test/integration/default/inspec

Third, remove the Serverspec-specific code from the test files.

require 'serverspec'

# Required by serverspec
set :backend, :exec

InSpec is now configured with Test-Kitchen:

kitchen verify package-install-centos-72
-----> Starting Kitchen (v1.14.2)
-----> Verifying <package-install-centos-72>...
       Detected alternative framework tests for `inspec`
       Loaded

Target:  ssh://vagrant@127.0.0.1:2200


  PHP has
     ✔  php
     ✔  the pear.php.net channel
     ✔  the pecl.php.net channel

Test Summary: 3 successful, 0 failures, 0 skipped
       Finished verifying <package-install-centos-72> (0m0.40s).
-----> Kitchen is finished. (0m3.31s)

Some real-world migrations are available:

• docker
• nginx
• mysql
• php

Some general recommendations:

• use test-kitchen 1.14+
• in case of errors, increase the log level kitchen verify package-install-centos-72 -l debug

Do I still need the backend configuration?

InSpec does not attach backend information to test files. All tests are defined independently of any backend. Therefore a Serverspec test file:

require 'serverspec'

# Required by serverspec
set :backend, :exec

describe 'PHP' do
  it 'has php' do
    expect(command('php -v').exit_status).to eq(0)
  end

  it 'has the pear.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pear.php.net')
  end

  it 'has the pecl.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pecl.php.net')
  end
end

will become the following InSpec test file:

describe 'PHP' do
  it 'has php' do
    expect(command('php -v').exit_status).to eq(0)
  end

  it 'has the pear.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pear.php.net')
  end

  it 'has the pecl.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pecl.php.net')
  end
end

As you can see, the InSpec test files just focuses on tests and tries to avoid all clutter.

Nested describe blocks

Serverspec and RSpec allow you to define nested describe blocks. We did a survey and found out that most users use nested describe blocks only to improve their output report. We believe the code structure should not change to improve the output of a report. Nevertheless we understand that nested describe blocks help you to structure test code. A sample code block looks like:

describe 'chef-server-directories' do
  describe file('/etc/opscode') do
    it { should be_directory }
    it { should be_owned_by 'root' }
  end

  describe file('/etc/opscode-analytics') do
    it { should be_directory }
    it { should be_owned_by 'opscode' }
    it { should be_grouped_into 'opscode' }
  end

  describe file('/var/log/opscode') do
    it { should be_directory }
    it { should be_owned_by 'opscode' }
    it { should be_grouped_into 'opscode' }
  end

  describe file('/var/opt/opscode') do
    it { should be_directory }
    it { should be_owned_by 'root' }
  end
end

In InSpec you would split up groups into files.

tests
├── server-directories.rb
├── other-tests.rb
└── further-tests.rb

Each file can have a top-level description of its content:

title "Chef Server Directories"

describe file('/etc/opscode') do
  it { should be_directory }
  it { should be_owned_by 'root' }
end

describe file('/etc/opscode-analytics') do
  it { should be_directory }
  it { should be_owned_by 'opscode' }
  it { should be_grouped_into 'opscode' }
end

describe file('/var/log/opscode') do
  it { should be_directory }
  it { should be_owned_by 'opscode' }
  it { should be_grouped_into 'opscode' }
end

describe file('/var/opt/opscode') do
  it { should be_directory }
  it { should be_owned_by 'root' }
end

Are you supporting the expect syntax?

Of course. We still prefer the should syntax for UX reasons. We did surveys with various types of customers like devops engineers, auditors, managers. All participants who prefered the expect syntax have been Ruby experts. All non-Ruby developers found it easier to understand the should syntax.

should syntax with InSpec

describe command('php -v') do
  its('exit_status') { should eq 0 }
end

describe command('pear list-channels') do
  its('stdout') { should include('pear.php.net')}
end

describe command('pear list-channels') do
  its('stdout') { should include('pecl.php.net')}
end

expect syntax with InSpec

describe 'PHP' do
  it 'has php' do
    expect(command('php -v').exit_status).to eq(0)
  end

  it 'has the pear.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pear.php.net')
  end

  it 'has the pecl.php.net channel' do
    expect(command('pear list-channels').stdout).to include('pecl.php.net')
  end
end