Create docs for using InSpec in Chef for newcomers

[jzohrab]

I've run through the example but am having some trouble getting this working in a toy Chef project. I'm not sure what Gems are really required, and what each does. I don't use Bundler much. There seems to be much to know to get this running, would be nice to have a short intro for people like me getting started out using it, so I can get up and running quickly. This example should include:

• what Gems are needed, if any (if they're not already included in the Chef DK)
• installation instructions if any
• running instructions for Test Kitchen
• a brief note on writing RSpec tests

I don't want to copy existing documentation, but there is so much out there that it is hard to determine what is good. eg, searching for "inspec expect example", to find the new (and apparently preferred) RSpec expect syntax, doesn't yield much.

I'm happy to take ownership of this and put in a PR when I get my head around it. If existing docs cover it already, I'll put in a PR to make them easier to follow.

[chris-rock]

Awesome idea @jzohrab Maybe the best way is to add a tutorial to our repo. Topics that come into my mind:

• Installation
  • standalone
  • with Chef DK
• cookbook tests with test-kitchen
  • create a new cookbook
  • add inspec tests
  • run test-kitchen
• use inspec cli
  • run commands
  • use inspec shell
• best practices
  • how to write tests
  • test and compliance controls
  • expect vs should syntax
• sharable tests
  • e.g. introduction to inspec profiles

I am looking forward to see your PR.

[jzohrab]

@chris-rock - I'm going to spend a bit of time looking at this today. I'm tracking this in a branch on my repo, https://github.com/jzohrab/inspec/tree/WIP_add_tutorial. I'll throw some points in there, and we can discuss it in this issue or in the branch itself. I'll rebase/squash the commits when we get close to completion - I usually commit a lot of "wip" commits.

I'll be writing this tutorial specifically for testing chef cookbooks, but there may be other tutorials that would be helpful. I don't think that this will be redundant documentation ... searching "chef inspec tutorial" on google actually returns this issue in the top 10 hits or so. But I'll keep it pretty tight and reference other docs.

[jzohrab]

Currently failing on my mac due to dependency issues. This was where I got to before and then stopped.

-----> Starting Kitchen (v1.5.0)
-----> Verifying <default-ubuntu-1404>...
>>>>>> ------Exception-------
>>>>>> Class: Kitchen::ActionFailed
>>>>>> Message: Failed to complete #verify action: [Unable to activate specinfra-2.43.9, because net-ssh-3.0.2 conflicts with net-ssh (~> 2.7)]
>>>>>> ----------------------
>>>>>> Please see .kitchen/logs/kitchen.log for more details
>>>>>> Also try running `kitchen diagnose --all` for configuration

I've opened https://github.com/chef/chef-dk/issues/668 in the Chef-DK, the problem may arise from there.

[jzohrab]

I've submitted a patch to serverspec, per the notes in the chef-dk issue 668.

I'm now getting a test failure error, even though the file actually exists!

rspec  # InSpecDemo::default File "/demo.txt" should exist

>>>>>> Verify failed on instance <default-ubuntu-1404>.
>>>>>> Please see .kitchen/logs/default-ubuntu-1404.log for more details
>>>>>> ------Exception-------
>>>>>> Class: Kitchen::ActionFailed
>>>>>> Message: Inspec Runner returns 1
>>>>>> ----------------------

pushed current readme content, with details on the failure, to repo. Ref "current status" heading at https://github.com/jzohrab/inspec/tree/WIP_add_tutorial/tutorial/chef_cookbooks

[jzohrab]

Looks like kitchen verify runs the InSpec examples against the local machine, and not against the created VM. If I run kitchen create; kitchen converge with my sample cookbook, the file /demo.txt is created on the VM, but running kitchen verify fails with error InSpecDemo::default File "/demo.txt" should exist, even though the file exists when I kitchen login to the VM. If I run touch /demo.txt on my machine (the host machine), kitchen verify succeeds!

Looking at the inspec chef example, it appears that this may be due to my missing some gems. Will try adding Gems to my system as given in the gemfile of the example, ref https://github.com/chef/inspec/blob/master/examples/kitchen-chef/Gemfile.

[jzohrab]

Still no good. Will check with @echohack about this. I've pushed details to my repo readme, https://github.com/jzohrab/inspec/tree/WIP_add_tutorial/tutorial/chef_cookbooks

[jzohrab]

Finally got the tests working by comparing with a working demo, https://github.com/fnichol/chef-inspec_example/blob/master/test/integration/default/default_spec.rb

My spec file was this:

require 'spec_helper'
describe 'InSpecDemo::default' do
  describe file('/demo.txt') do
    it { should exist }
  end
end

The above fails. The below works:

require 'spec_helper'
# describe 'InSpecDemo::default' do
  describe file('/demo.txt') do
    it { should exist }
  end
# end

I'm not sure why the outer "describe" block causes the tests to fail. This is a bit concerning as InSpec looks very similar to serverspec, and both serverspec and rspec support such nested "describe" blocks (a serverspec run produces results like the below):

InSpecDemo::default
  File "/demo.txt"
    should exist

This could cause some trouble for people migrating from ServerSpec to InSpec as many serverspec.

@chris-rock, is this removal of nested describe blocks intentional?

[chris-rock]

@jzohrab Could you share your tests? Normally, you need to remove the whole spec_helper, since inspec does not require it. Its also a challenge to load serverspec and inspec at the same time, since both register resources in rspec.

[jzohrab]

Thanks @chris-rock. The spec_helper is actually blank. I'll create a Vagrantfile, which I wanted as part of this demo, which should give you the detail you want. I'll push that up today and will ping you here.

[chris-rock]

I am confused because it shows Unable to activate specinfra-2.43.9. We do not need specinfra.

[jzohrab]

I'm running this with ChefDK v0.10.0 ... maybe it's automatically pulling in dependencies. I don't have any gemfile in my test. I'll set this up with a new Vagrant VM and fresh dk install with no gems, and will see where that takes me.

UPDATE: can't do this simply, b/c I'd need vagrant to spin up the new environment, and then would need to run test kitchen inside of there. There are workarounds but it starts to be a hassle.

[jzohrab]

@chris-rock - I actually still had a require 'server_spec'. Sorry for the confusion ... was getting lost in the files and gem issues. I'm boiling down a simple example and will be pushing it soon.

[pwelch]

Closing this issue because there has been no traction on it for a while or it is no longer relevant. If this issue is still relevant, please reopen. Thanks!