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:

Attributes that are values on Node like IP Addresses or the list of recipes.
Definitions that allow you to create new Resources composed of existing Resources.
Files that are transferred to your Chef-administered machines via Cookbook File.
Libraries that extend the Chef language with arbitrary Ruby code.
Recipes that specify Resources to manage, in the order they should be managed.
Templates that are rendered on Chef-configured machines with your dynamically substituted values. Think config files on steroids, then read ERB templates.
Metadata that tells Chef about your recipes, including dependencies, supported platforms and more.

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

Cookbook Contents

Table of Contents

What's in a Cookbook?
How do I create a new Cookbook?
Where can I find some Cookbooks?

Tell me more about Opscode's cookbooks

How Do I Customize existing Cookbooks for my site?

Customizing Templates and Files
Other Site-specific Cookbooks

How do I create a new Cookbook?

You can create a new cookbook with Knife.

Where can I find some Cookbooks?

In October 2009, we released cookbooks.opscode.com, which is the best destination 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. We publish all of our cookbooks there and encourage others to do the same.

Repository	Description	Maintainer
http://cookbooks.opscode.com/	Recipes created by members of the Chef community	Opscode, community
http://github.com/opscode/cookbooks	Recipes created by Opscode	Opscode
http://github.com/37signals/37s_cookbooks	37 Signals Repository	37 Signals
http://github.com/engineyard/ey-cloud-recipes	EY Cloud Recipes	Engine Yard

Note on the Opscode Github Repository: While people can fork the Opscode GitHub project and make their own changes, not everything gets merged back into the Opscode repository. If you're feeling adventurous, try the github network graph which shows these repositories at http://github.com/opscode/cookbooks/network. Some people may be interested in the use of Headless Branches for Cookbook Repositories.

Tell me more about Opscode's cookbooks

We provide a default set of cookbooks on GitHub for people to get started. The set is considered "feature complete". You can deploy a number of services without having to write cookbooks from scratch. These cookbooks are used for installing Chef (we drink our koolaid!), and building a complete Rails application stack.

(by default if you're using the Chef Repository, the cookbooks directory will exist but has no cookbooks. You can safely delete it.)

If you would also like to contribute changes, or new features to our cookbooks, read more about setting up a git repository to do so.

How Do I Customize existing Cookbooks for my site?

That's pretty simple, actually! Create a site-cookbooks directory in Chef Repository. Make sure /etc/chef/server.rb cookbooks_path is correct.

In Chef versions before 0.8, the cookbook_path order is reversed, meaning /srv/chef/site-cookbooks would be listed first. See Breaking Changes from 0.7.x to 0.8.x for more.

/etc/chef/server.rb, knife.rb

Next, copy the entire contents of the cookbook, go forth and customize it. When Chef runs, it will only use the cookbook from site-cookbooks, not the one in cookbooks. For example, say you have:

When Chef runs, it will cache /srv/chef/site-cookbooks/djbdns and apply that configuration.

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

/srv/chef/site-cookbooks/web_server/recipes/default.rb

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.