Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current ·  View Page History

Cookbooks are the fundamental units of distribution in Chef.

They encapsulate all the resources you need to automate your infrastructure and are easily sharable with other Chef users.

What's in a Cookbook?

Cookbooks contain:

Each of these components is a directory or file. An example cookbook directory after running the cookbook create knife command:

Cookbook Contents

You develop cookbooks on your local system in the Chef Repository, in the cookbooks/ sub-directory.

The Future of Opscode Cookbooks

Check out the Opscode Blog about what cookbooks Opscode includes in the Opscode github cookbooks repository, how that compares with the Opcode Community Cookbooks Site, and how those interrelate in the release, management, and support of cookbooks.

Nagios and Chef at Fotopedia

Fotopedia uses Chef in the management of their infrastructure. Among many other things, Chef generates the Nagios configuration for all their services. Their Fotopedia Labs blog entry: Nagios and Chef at Fotopedia includes extensive detail on the use of recipes, roles, ruby blocks, helpers and other Chef components - all within their Nagios Cookbook.

How do I work with cookbooks?

We recommend you develop cookbooks in the Chef Repository. You can create your own cookbooks, or you can download other people's shared cookbooks.

Then, you can upload your cookbooks to your Chef Server with knife.

How do I create a new Cookbook?

You can create a new cookbook in your Chef Repository cookbooks/ sub-directory with Knife.

Then start editing the various components, such as the default recipe, as needed.

Where can I find some Cookbooks?

Opscode maintains the Chef Community Cookbook Site as a location for finding and sharing Chef cookbooks. It includes dedicated listings for each cookbook, is easy to navigate and can be accessed via a RESTful API. Opscode publishes all our cookbooks there and encourages others to do the same. Cookbook Site Help includes access to help articles for the Chef Community Cookbook Site.

You can download cookbooks from the cookbooks site through the API using knife. This will retrieve a tar.gz of the cookbook that you can extract into the cookbooks/ directory of the Chef Repository.

If you are using Git, you can have cookbooks downloaded, then automatically extracted into cookbooks/ and tracked with their own branch using:

For more information about this command see Chef Repository#cookbooks.

Github Repositories

Opscode's cookbooks on the Chef Community site are considered "released", and the cookbooks repository on Github is considered "development." Opscode recommends that users download cookbooks from the Community site instead of using the Github repository, as changes may be incompatible with your version of Chef.

Beyond the Opscode development Github repository, some members of the Chef Community have only shared their cookbooks on Github. Some repositories that are available:




Recipes created by Opscode


37 Signals Repository

37 Signals

EY Cloud Recipes

Engine Yard

You can also discover other repositories on github with the network graph.

Cookbook Development Workflow

See Working with Git and Cookbooks for a development workflow for Chef cookbooks, using Git as the version control system.
If you are not using Git, you should be able to review these details and adapt your approach for the specifics of your version control system.

How do I upload cookbooks to my Chef Server?

Use knife cookbook upload sub-command. To upload a single named COOKBOOK:

To upload multiple cookbooks, as the command parses the name args as 1..n cookbook names:

To upload all cookbooks:

If you're using Chef Solo, you need to copy all the cookbooks necessary to the system that will be running Chef Solo. See the Chef Solo page for more information.

How do I customize existing cookbooks?

When you download cookbooks from the Community Site or Github repositories, you may wish to make changes. Using the "cookbook site install" knife command above makes this really easy.

Simply modify the cookbook as desired, and if you want to retrieve a new release of the cookbook, you can simply run the command again, and your changes will be preserved.

Then, as the maintainer of COOKBOOK releases a new version, you could merge the new version into your changes.

If there are any conflicts, git will let you know, and you can resolve those and commit the changes.

Changing the location of your cookbooks

You can specify the location of your cookbooks with this command:

This command is not needed if you have already setup your cookbook_path in your knife.rb.

Site Specific Cookbooks

You can also make your own site specific copies of cookbooks.

~/.chef/knife.rb or ~/chef-repo/.chef/knife.rb

Next, copy the entire contents of the cookbook, go forth and customize it, then upload the cookbook(s) to the server. When Chef runs, it will only use the cookbook from site-cookbooks, not the one in cookbooks.

For example, say you have:

When the cookbook is uploaded, Knife will use the cookbook in chef-repo/site-cookbooks/djbdns.

Customizing Templates and Files

If you would like to customize just the files or templates used by a cookbook, you can create just those as well, copying them over from the upstream version and making your local changes. For example, you're deploying OpenLDAP and want to customize the slapd.conf and add your own certificates.

Assuming you've followed along with the Chef Repository and have created the ldap certificate:

Make changes, update the repository and install the cookbooks, and when Chef runs, it will get the certificte and slapd.conf from the site-cookbooks, but otherwise use the rest of the openldap cookbook.

Other Site-specific Cookbooks

You can also use site-cookbooks for setting up other site-specific cookbooks


Then add "web_server" to recipes for the node in the webui, and it will apply the configuration. Prior to Chef 0.7.0, you might have a cookbook that merely includes several other recipes/cookbooks. Now you'll use Roles to define that.

Cookbook Dependencies

The Chef Server tries to only distribute the cookbooks that are needed to configure each individual Node. In order to do that, we take the list of Roles and Recipes that are assigned directly to that system, expand the list of dependencies for them, and then ship that set to the Node.

If there is a dependency on a particular cookbook being in place in order to complete a configuration, edit the template metadata.rb file to specify that dependency through the 'depends' field. Metadata has details on this field, and the other fields that are available to you in the metadata.rb file.

Whenever you include a recipe in a cookbook via "include_recipe" you need to add the included cookbook to the depends list.

Use Case Study

In our environment we don’t have only Windos / Ubuntu/Debian /RH servers. So my problem is that we want to create a maintenance role for updating these servers, but the server name doesn’t describe the function or the OS running on it. Is there a way to create “server-groups” which include only windows servers or something like this because with these groups we can easily put a the correct “maintenance-role” (cookbooks for maintenance) to them if they are needed?

Probably the best and most direct way to go about this is to have a single "Maintenance Cookbook" as part of every system, which will selectively include recipes based on platform. It'd look something like this:

  • None