What's in a Cookbook?

Cookbooks contain:

• Attributes that are values on Node to set default values used elsewhere in the cookbook.
• Definitions that allow you to create reusable collections of one or more Resources.
• File Distribution that are transferred to your Chef-administered machines via Cookbook File resource.
• Libraries that extend Chef or provide helpers with Ruby code.
• Recipes that specify Resources to manage, in the order they should be managed.
• Lightweight Resources and Providers (LWRP) that allow you to create your own custom resources and providers.
• 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, version constraints, supported platforms and more.

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

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

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:

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.

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

Fotopedia uses Chef in the management of their infrastructure for building a photo encyclopedia that lets photographers and photo enthusiasts collaborate and enrich images: collaborating for building an encyclopedia of images and a distribution network. 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.