» Chef Solo Provisioner

Provisioner name: chef_solo

The Vagrant Chef Solo provisioner allows you to provision the guest usingChef, specifically withChef Solo.

Chef Solo is ideal for people who are already experienced with Chef,already have Chef cookbooks, or are looking to learn Chef. Specifically,this documentation page will not go into how to use Chef or how to writeChef cookbooks, since Chef is a complete system that is beyond the scopeof a single page of documentation.

Warning: If you are not familiar with Chef and Vagrant already,it is recommended to start with the shellprovisioner. However, if you are comfortable with Vagrant already, Vagrantis the best way to learn Chef.

» Options

This section lists the complete set of available options for the Chef Soloprovisioner. More detailed examples of how to use the provisioner areavailable below this section.

  • cookbooks_path (string or array) - A list of paths to where cookbooksare stored. By default this is "cookbooks", expecting a cookbooks folderrelative to the Vagrantfile location.

  • data_bags_path (string or array) - A path where data bags are stored. Bydefault, no data bag path is set. Chef 12 or higher is required to use thearray option. Chef 11 and lower only accept a string value.

  • environments_path (string) - A path where environment definitions arelocated. By default, no environments folder is set.

  • nodes_path (string or array) - A list of paths where node objects (in JSON format) are stored. By default, nonodes path is set.

  • environment (string) - The environment you want the Chef run to bea part of. This requires Chef 11.6.0 or later, and that environments_pathis set.

  • recipe_url (string) - URL to an archive of cookbooks that Chef will downloadand use.

  • roles_path (string or array) - A list of paths where roles are defined.By default this is empty. Multiple role directories are only supported byChef 11.8.0 and later.

  • synced_folder_type (string) - The type of synced folders to use whensharing the data required for the provisioner to work properly. By defaultthis will use the default synced folder type. For example, you can set thisto "nfs" to use NFS synced folders.

In addition to all the options listed above, the Chef Solo provisioner supportsthe common options for all Chef provisioners.

» Specifying a Run List

The easiest way to get started with the Chef Solo provisioner is to justspecify a run list. This looks like:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.add_recipe "apache"
  4.   end
  5. end

This causes Vagrant to run Chef Solo with the "apache" cookbook. The cookbooksby default are looked for in the "cookbooks" directory relative to yourproject root. The directory structure ends up looking like this:

  1. $ tree
  2. .
  3. |-- Vagrantfile
  4. |-- cookbooks
  5. |   |-- apache
  6. |       |-- recipes
  7. |           |-- default.rb

The order of the calls to add_recipe will specify the order of the run list.Earlier recipes added with add_recipe are run before later recipes added.

» Custom Cookbooks Path

Instead of using the default "cookbooks" directory, a custom cookbookspath can also be set via the cookbooks_path configuration directive:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.cookbooks_path = "my_cookbooks"
  4.   end
  5. end

The path can be relative or absolute. If it is relative, it is relativeto the project root.

The configuration value can also be an array of paths:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.cookbooks_path = ["cookbooks", "my_cookbooks"]
  4.   end
  5. end

» Roles

Vagrant also supports provisioning with Chef roles.This is done by specifying a path to a roles folder where roles are definedand by adding roles to your run list:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.roles_path = "roles"
  4.     chef.add_role("web")
  5.   end
  6. end

Just like the cookbooks path, the roles path is relative to the projectroot if a relative path is given.

The configuration value can also be an array of paths on Chef 11.8.0 and newer.On older Chef versions only the first path is used.

Note: The name of the role file must be the same as the role name.For example the web role must be in the roles_path as web.json or web.rb.This is required by Chef itself, and is not a limitation imposed byVagrant.

» Data Bags

Data bags are alsosupported by the Chef Solo provisioner. This is done by specifyinga path to your data bags directory:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.data_bags_path = "data_bags"
  4.   end
  5. end

» Custom JSON Data

Additional configuration data for Chef attributes can be passed into Chef Solo. This is done by setting the json property with a Rubyhash (dictionary-like object), which is converted to JSON and passedin to Chef:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     # ...
  5.     chef.json = {
  6.       "apache" => {
  7.         "listen_address" => "0.0.0.0"
  8.       }
  9.     }
  10.   end
  11. end

Hashes, arrays, etc. can be used with the JSON configuration object. Basically,anything that can be turned cleanly into JSON works.

» Custom Node Name

You can specify a custom node name by setting the node_name property. Thisis useful for cookbooks that may depend on this being set to some sortof value. Example:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.provision "chef_solo" do |chef|
  3.     chef.node_name = "foo"
  4.   end
  5. end