Overview

Cookbooks are how things are distributed and shared in Chef. Most of your time building infrastructure in Chef will be spent writing Cookbooks; this page is a quick guide to writing and using Chef Cookbooks. It isn't comprehensive, but it will show how some basic components work and we'll explain some terms along the way. To learn more about Chef's terminology, check out the Chef Basics section. If you want more details about how Chef is structured architecturally, check out the Chef Architecture section.

At this point, you should have completed the installation process and have a working Chef server.

If you are using Hosted Chef, you can run these commands from the management workstation you've setup.

Get a Chef Repository

A Chef repository is just a directory structure where you keep your cookbooks and other files. If you haven't done so already, clone Opscode's Chef repository from github:

When you find a cookbook at the Community Site that you would like to use, you can use these steps to add it to the Chef Server/Hosted chef.

Downloading the Cookbook, Uploading it to the Chef Server/Hosted Chef

You can use this command to download a new cookbook, substitute COOKBOOK for the name of the cookbook you want to download:

Once this command completes, the cookbook will have been downloaded to the chef-repo directory, in the cookbooks folder. You can feel free to edit it if needed, then you can upload it to the Chef Server/Hosted Chef with this command:

Now this cookbook will be available to add to a node's run_list. If you want to make any changes to it, just edit it from you workstation and upload it again to Chef Server/Hosted Chef. If you'd like some quick information on how to add this to a node's run_list you can find this in Step 3 of the Client Bootstrap Fast Start Guide guide.

For more information on using cookbooks that are on the Community Site see the Cookbooks page.

You can also create your own cookbooks, and upload these into the Chef Server/Hosted chef. The steps below go over creating a new cookbook named fast_start and running it on a node.

What is a Recipe? (or a Resource, for that matter!) Recipes allow you to specify Resources to manage, in the order they should be managed. In this case, you are creating a recipe called "fast_start", which has a single template resource called template["/tmp/deep_thought.txt"]. All of this will be part of the cookbook, although a cookbook can contain multiple related recipes if needed.

Create a new Cookbook called "fast_start"

Change your working directory to the cookbooks/ directory of your Chef repository. If you cloned the repository into /tmp/sandbox/ as shown above:

Now create the cookbook with knife cookbook create:

This will create the cookbook's directory structure:

This cookbook is going to have a simple recipe that renders a simple text file using some Attributes we will define.

Add an attribute file called "fast_start.rb"

With your favorite text editor, create a file in cookbooks/fast_start/attributes called fast_start.rb, with the following contents.

What is an Attribute? Attributes in a Cookbook allow you create settings on a node, which you can then access from within a recipe. Attributes are persistent between Chef runs, and edit-able through the Chef Server web interface!

Add a template resource to the default recipe

Next, edit cookbooks/fast_start/recipes/default.rb and add the following:

Add the template file itself

In the template resource we defined above, we referenced a source parameter. This is the actual template file, and it is placed in cookbooks/fast_start/templates/default/deep_thought.txt.erb. Lets create it now:

What kind of Template is that? Chef uses Erubis, a fast version of ERB, to render templates. Read more about it in the Templates section.

Upload the Cookbook to the Server

You should be keeping your cookbooks in version control, and you should start getting in the habit now, so commit your work using your favorite version control system.

Now that your work is in version control, upload the cookbook to the server.

The output will look like the following, though your file checksums will be different:

Confirm that the server has the cookbook you just uploaded:

Register a node with chef-client

For this step, you'll need a new host to run chef-client. We recommend you use a virtual machine with snapshots for the maximum effectiveness when developing cookbooks. There is also a Client Bootstrap Fast Start Guide guide if you would prefer to set this up on a separate node.

If you'd like to set up a VM, simply create it with the base OS of your choice and install chef client on it. We also recommend you take a snapshot of the VM in this pristine state—if trouble strikes, you'll be able to roll back and try again.

Once you have chef-client installed on the host, you'll need to copy the validation key, /etc/chef/validation.pem, from your Chef server box to the same location on the chef-client box. The validation key is used by the chef-client as a temporary identity so it can register itself; after it registers it will have its own key in /etc/chef/client.pem ([read more about Chef's authentication system]). (If you don't have an /etc/chef/validation.pem or /etc/chef/client.rb generate them with knife configure client....)

With the validation key in place, run chef client:

Add the fast_start recipe to your new Node

From your management workstation (where you run knife from) run the knife node run_list add command. Use the name of the client machine for HOSTNAME (If you're not sure what to put here, check the output of knife node list).

You can see that your change was made on the server using knife node show:

Run chef-client again on your new Node.

This time, executing chef-client will cause /tmp/deep_thought.txt to appear!

If you run the command again, you'll notice that it does nothing at all, because the deep_thought.txt file has not changed, either on disk or on the Chef Server.

Congratulations!

You have just written your first Chef Cookbook! You'll be managing your entire infrastructure in no time!

Chef Basics

Learn some of the central concepts of configuration management benefits for your infrastructure.

1. We begin with an Architecture Introduction, covering the basic functions of the Chef Server, Nodes, and Chef Workstations and how these components communicate.
2. Then an overview of the Core Components, which introduces all of the aspects and components of modeling your infrastructure, Configuring Nodes and Managing Chef.
3. Onward to Cooking School and begin an Introduction to Cookbooks and More. Cookbooks are Chef's fundamental units of distribution, the way Chef users package up, distribute and share configuration information. Recipes, Resources, Attributes, Roles and more are also introduced.
4. The final basic section is an Introduction to Search and Data Bags, two of Chef's most powerful features allowing you to dynamically change the configuration of your infrastructure based on data.

Chef Architecture

With all that under your belt, it's time to tackle the dirty secrets of what's happening behind the scenes with Chef Architecture. We'll give you the scoop on Chef's Authentication and Authorization system and go over the Anatomy of a Chef Run, where we go in-depth with the process by which your systems get configured. From there we'll review all the executable parts of Chef - Chef Client, Chef Solo, Chef Server, Chef Indexer, and Server API and Cookbook Site API interaction.

Installation

Managing Chef