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.

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

Some members of the Chef Community have only shared their cookbooks on Github. Some repositories that are avaiable:

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

• http://github.com/opscode/cookbooks/network

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.

How do I upload cookbooks to my Chef Server?

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

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 vendor" 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. Workflow example.

Some time passes and the maintainer of COOKBOOK releases a new version.

This will merge the new version with your changes. If there are any conflicts, git will let you know, and you can resolve those and commit the changes.

Site Specific Cookbooks

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

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

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.