Build Status Gem Version Coverage Gemnasium License

Write as a gem, release as a cookbook.

Quick Start

Create a gem as per normal and add a dependency on halite. Add require 'halite/rake_tasks' to your Rakefile. Run rake build and the converted cookbook will be written to pkg/.

All Ruby code in the gem will be converted in to libraries/ files. You can add cookbook-specific files by add them to a chef/ folder in the root of the gem.


Developing cookbooks as gems allows using the full Ruby development ecosystem and tooling more directly. This includes things like Simplecov for coverage testing, YARD for documentation, and Gemnasium for dependency monitoring. For a cookbook that is already mostly library files, this is a natural transition, with few cookbook-specific pieces to start with. This also allows using Bundler to manage versions instead of Berkshelf.

Cookbook Dependencies

To add cookbook dependencies either add them to the gem requirements or use the halite_dependencies metadata field:

Gem::Specification.new do |spec|
  spec.requirements = %w{apache2 mysql}
  # or
  spec.['halite_dependencies'] = 'php >= 2.0.0, chef-client'

Additionally if you gem depends on other Halite-based gems those will automatically converted to cookbook dependencies.

Cookbook Files

Any files under chef/ in the gem will be written as is in to the cookbook. For example you can add a recipe to your gem via chef/recipes/default.rb.

Rake Tasks

The halite/rake_tasks module provides quick defaults. Gem name will be auto-detected from the .gemspec file and the cookbook name will be based on the gem name.

rake build

The build command will convert the gem to a cookbook and write it to the pkg/ folder.

Advanced Usage

You can also pass custom arguments to the Rake tasks. All parameters are optional:

require 'halite/rake_helper'
  gem_name: 'name', # Name of the gem to convert
  base: File.basename(__FILE__), # Base folder for the gem

Berkshelf Extension

Halite includes a Berkshelf extension to pull in any gem-based cookbooks that are available on the system.

To activate it, include the extension in your Berksfile:

extension 'halite'

Spec Helper

Halite includes a set of helpers for RSpec tests. You can enable them in your spec_helper.rb:

require 'halite/spec_helper'

RSpec.configure do |config|
  config.include Halite::SpecHelper


Recipes to converge for the test can be defined inline on example groups:

describe 'cookbook recipe' do
  recipe 'myrecipe'
  it { is_expected.to create_file('/myfile') }

describe 'inline recipe' do
  recipe do
    file '/myfile' do
      content 'mycontent'
  it { is_expected.to create_file('/myfile') }


A resource can be added to the list to step in to via the step_into helper:

describe 'mycookbook' do
  recipe 'mycookbook::server'
  step_into :mycookbook_lwrp
  it { is_expected.to ... }

resource and provider

For testing mixin-based cookbooks, new resource and provider classes can be declared on an example group:

describe MyMixin do
  resource(:test_resource) do
    include MyMixin
    def foo(val=nil)
      set_or_return(:foo, val, {})
  provider(:test_resource) do
    def action_run
      # ...
  recipe do
    test_resource 'test' do
      foo 1
      action :run
  it { is_expected.to ... }

These helper resources and providers are only available within the scope of recipes defined on that example group or groups nested inside it. Helper resources are automatically step_into'd.


Copyright 2015, Noah Kantrowitz

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.