Chef Repository Structure

In the repository, you'll find:

• certificates/ - This directory contains SSL certificates generated with the rake ssl_cert task which you can put in cookbooks where needed.
• config/ - Top-level directory for general config files to configure the repository or support your own local environment. For example, openldap.ldif to bootstrap an LDAP directory or information from Data Bags.
  • config/client.rb.example - Sample Chef client config file. If you use the Opscode cookbooks, you should use the Chef cookbook to manage the Chef client itself.
  • config/knife.rb.example - Sample knife config file. You should use knife configure to generate a configuration file.
  • config/rake.rb - Configuration file used by the Rake tasks. See Configuring Rake Tasks below for details.
  • config/server.rb.example - Sample Chef server config file. As with client, only use this if you're not going to configure your Chef server with the Opscode cookbooks.
  • config/solo.rb.example - Example solo file. Uncommon, but we don't manage the solo.rb in the Opscode Chef cookbook.
• cookbooks/ - Upstream and/or shared cookbooks.
• Rakefile - Sets up the rake tasks for managing the repository. Gets tasks from chef_repo.rake provided with the Chef gem (as of v0.7.0). Running Rake Tasks for more information.
• roles/ - Define node roles here. We recommend storing your roles in this directory and sending them to the server with Knife so they are maintained under version control.
• site-cookbooks/ - Your local site's cookbooks. Modify parts of upstream cookbooks (like overriding templates), or add cookbooks specific to your organization.

For more about client.rb, server.rb and solo.rb, see the Configuring Chef page.

Configuring Rake Tasks

The Rake Tasks are configured with config/rake.rb.

There are some other options, but they aren't commonly changed, and they have comments.

Running Rake Tasks

The included Rakefile loads tasks from the installed Chef library. We will discuss each task in detail below.

• bundle_cookbook[cookbook]
• default
• install
• metadata
• new_cookbook
• role[role_name]
• roles
• ssl_cert
• update
• upload_cookbook[cookbook]
• upload_cookbooks

bundle_cookbook[cookbook]

This task generates a .tar.gz archive of the specified cookbook in the pkgs directory under the configured TOPDIR

default

The default task is test, which calls test_recipes and test_templates.

Since Chef recipes are Ruby, we can verify they are syntactically valid by running this task. This will also check for syntax errors in ERB templates (Ruby syntax only). This also caches the mtime of the files so it will only check recipe and template files that changed.

install

This task runs the update, roles, and upload_cookbooks tasks.

metadata

This task generates the JSON metadata and uploads it to the Chef Server using Knife.

new_cookbook

This task will create a new cookbook directory structure for you. It takes two environment parameters.

• COOKBOOK: required, name of the cookbook.
• CB_PREFIX: optional, whether to put it in a specific 'cookbooks' directory. See example.

For example, to create a new cookbook titled 'apache', from the top of the repository:

The cookbook will be complete with default recipe file (containing a license preamble), a README.rdoc and a default Metadata file.

roles or role[role_name]

Create roles for your nodes in the roles/ directory, and use these tasks to upload them to the Chef Server using Knife.

This task is automatically run by the install task. You can read more about how to create roles on the Roles page.

ssl_cert

Because you need them all the time, the Chef Repo Rakefile knows how to create self-signed certificates for SSL. Just give it an fully qualified domain name via FQDN, and it will drop off all the SSL artifacts in the certificates directory.

You can distribute these via recipes, and put them in your Cookbooks.

update

Assuming you are collaborating with an upstream repository (say, SVN or Git), the Rakefile can update it for you automatically. (This is handy when you want to install the latest Cookbooks on your Chef Server).

If you don't want this to run, comment out the lines setting $vcs in the Rakefile.

upload_cookbooks or upload_cookbook[cookbook]

These tasks upload cookbooks to the Chef Server using Knife. They are a shortcut to the knife cookbook upload sub-commands. upload_cookbooks uploads all cookbooks, and upload_cookbook[cookbook] uploads the named cookbook.

Repository Workflow

As you work with Chef, your workflow will include using the Rake tasks listed above, and using the Knife program to access the Chef Server REST API. Let's walk through an example with a node named client.example.com. This assumes the node has already registered with the server and is ready to be configured.

Add Some Cookbooks

Opscode publishes dozens of cookbooks and makes them available via the Chef Cookbook Site, and on GitHub. You can download the tarballs from the Cookbook site, or clone the Git Repository in your new Chef Repo. Here we have downloaded a few cookbooks:

Upload the Cookbooks

Now that we have some cookbooks, upload them.

This will upload the cookbooks listed above.

You can also modify the cookbooks, either directly, or override the default recipes or templates included by creating the cookbook in site-cookbooks and modifying what you want to change. Once your changes are done, you can upload that cookbook by itself. For example, if you modified the zsh cookbook:

Create a Role

We'll use a Role to manage the recipes on the example client node, and we'll use a Ruby DSL file in the roles/ directory of the chef-repo.

Upload the Role

Since we only have one role, use rake roles to upload it to the server:

This is rendered as JSON on the server:

Check Run List

Use Knife to show the node's run list.

Add Role to Node's Run List

We'll use knife's node run_list sub-command to add the role to the run list.

We'll get this same output again if we run the node show command from above.

Commit Changes to Repository

Since your repository is under source control, you probably want to commit your changes. For example, if you're using git:

Run Chef On Node

Now run chef-client on the node, and it will apply the recipes specified. In this example, the zsh, screen and git packages will be applied from the cookbook recipes.

Next Steps

If you are following the Installation walk through we recommend the Cookbook Quick Start section next to create an example cookbook with recipes and applying it to a client.