Chef Solo Provisioning

Provisioner key: :chef_solo

Chef Solo allows you to provision your virtual machine with Chef Cookbooks without requiring a Chef Server. At a very basic level, Chef is an open source systems integration framework which automates tasks through programmable “cookbooks.” This page will not go into the details of creating custom chef cookbooks, since that is covered in detail around the web, but a good place to start is the opscode-cookbooks organization which contains cookbooks for most of the popular server software already made. Note that sometimes these cookbooks may not work directly “out of the box,” and proper Chef support channels should be used if this occurs, since they are more knowledgable in general on that topic.

Setting the Cookbooks Path

First, Vagrant needs to know where the cookbooks are located. By default, Vagrant will look in the “cookbooks” directory relative to the root of the project directory (where a project’s Vagrantfile is). The cookbooks directory should have a structure similar to the following:

$ ls cookbooks/
apache2/
passenger_apache2/
rails/
sqlite/

Basically, the cookbooks directory should immediately contain all the folders of the various cookbooks.

To tell Vagrant what the cookbook path is, set it up in your Vagrantfile, like so:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    # This path will be expanded relative to the project directory
    chef.cookbooks_path = "cookbooks"
  end
end

You can also specify multiple cookbook paths by making the configuration an array of file paths. Note that the working directory while running Vagrant will always be the directory which contains the Vagrantfile, therefore file paths will always be expanded relative to that working directory.

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.cookbooks_path = ["cookbooks", "~/company/cookbooks"]
  end
end

And finally, somewhat of an advanced feature, but also sometimes needed: If the virtual machine already has cookbooks somewhere inside of it, you may specific folders within the virtual machine which contain cookbooks using a special syntax:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.cookbooks_path = ["cookbooks", [:vm, "/usr/local/cookbooks"]]
  end
end

The above tells Vagrant that there are cookbooks in the “cookbooks” folder relative to the project root as well as the “/usr/local/cookbooks” directory on the virtual machine itself.

Specifying the Run List

By default, Vagrant has an empty run list, or the list of recipes or roles for Chef to run. You need to explicitly specify the run list for Vagrant using some basic configuration:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.add_recipe("apache")
    chef.add_recipe("php")
  end
end

JSON Configuration

Every chef cookbook has access to the node variable which is a hash containing server-specific configuration options which can be used to control provisioning. By default, Vagrant JSON configuration looks like the following:

{
  :instance_role => "vagrant",
  :vagrant => {
    :config => { ... }, # Full Vagrant config
  }
}

This JSON configuration is specifically thought out such that the instance_role key could be used so that cookbooks could be shared between production and development, possibly tweaking paths or configuration based on the instance_role.

But sometimes, cookbooks need additional, custom JSON configuration. For this you can specify additional JSON data in the Vagrantfile:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.json = {
      :load_limit => 42,
      :chunky_bacon => true
    }
  end
end

Roles

Chef solo supports roles, which are specified via JSON files within a roles directory. Similar to the cookbooks path, a roles path can be specified to a directory containing these role files, and these roles can then be used by the chef solo run list. An example of configuring roles is shown below:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    # The roles path will be expanded relative to the project directory
    chef.roles_path = "roles"
    chef.add_role("web")
  end
end

Data Bags

Chef solo also supports data bags, which are arbitrary JSON documents that can be searched and loaded by Chef recipes. Vagrant exposes this functionality completely as well through similar configuration:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.data_bags_path = "data_bags"
  end
end

The data bags directory is expected to be the proper layout that Chef expects and documents.

Downloading Packaged Cookbooks

Chef solo supports using cookbooks which are downloaded from a URL. You can also do this with Vagrant:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.recipe_url = "http://files.mycompany.com/cookbooks.tar.gz"
  end
end

Configuring the Temporary Path

In order to run chef, Vagrant has to mount the specified cookbooks directory as a shared folder on the virtual machine. By default, this is set to be /tmp/vagrant-chef, and this should be fine for most users. But in the case that you need to customize the location, you can do so in the Vagrantfile:

Vagrant::Config.run do |config|
  config.vm.provision :chef_solo do |chef|
    chef.provisioning_path = "/tmp/vagrant-chef"
  end
end

This folder is created for provisioning purposes and destroyed once provisioning is complete.