Overview

Every Chef installation needs a Chef Repository. This is the place where cookbooks, roles, config files and other artifacts for managing systems with Chef will live.

We strongly recommend storing this repository in a version control system and treating it like source code.

While we prefer Git, and make this repository available via GitHub, you are welcome to download a tar or zip archive and use your favorite version control system to manage the code.

Chef Terms used on this page

We use some terms regarding the Chef Repository that have further explanation on their own pages.

• Knife - Chef's command-line API tool.
• Cookbooks - Unit of code distribution in Chef.
• Roles - Describe what a node should be / do.
• Data Bags - Arbitrary stores of data about the environment / infrastructure.

Getting the chef-repo

To create your own repository, start by cloning Opscode's chef-repo from GitHub. If you don't want to install Git, you can download a tarball.

Cloning Opscode's Chef Repo from GitHub

If you want to wipe out the existing history and start fresh, feel free to remove the .git directory after you clone. Then you can initialize a new git repository, or create a subversion (or mercurial, or bazaar) repository.

If you don't want Git...

You can grab the tarball directly off GitHub:

You'll need to extract the tarball, and move the directory it creates (by default, username-project-commit/) to chef-repo. The commit ID may be different than this.

We still strongly recommend you use some kind of version control tool to manage the source code in your chef-repo, so use your favorite tool to initialize the repository for tracking. If you do use Git, there is more info on Working with Git and Cookbooks.

Repository Directories

This repository contains several directories, and each directory contains a README file that describes what it is for in greater detail, and how to use it for managing your systems with Chef.

• config/ - Contains the Rake configuration file, rake.rb.
• cookbooks/ - Cookbooks you download or create.
• data_bags/ - Store data bags and items in .json in the repository.
• roles/ - Store roles in .rb or .json in the repository.
• certificates/ - SSL certificates generated by rake ssl_cert live here.

config

Contains the Rake config file. See Configuration below.

cookbooks

This directory contains the cookbooks used to configure systems in your infrastructure with Chef. Configure knife to use your preferred copyright holder, email contact and license by adding the following lines to ~/chef-repo/.chef/knife.rb:

Supported values for cookbook_license are "apachev2" or "none". These settings are used to prefill comments in the default recipe, and the corresponding values in the metadata.rb. You are free to change these in those files.

Create new cookbooks in this directory with Knife.

This will create all the cookbook directory components. You don't need to use them all, and can delete the ones you don't need. It also creates a README file, metadata.rb and default recipe.

You can also download cookbooks directly from the Opscode Community Cookbook Site. There are two subcommands to help with this depending on what your preference is. The first and recommended method is to use a vendor branch if you're using Git, this step is automatically handled with Knife.

This will:

• Download the cookbook tarball from cookbooks.opscode.com.
• Ensure its on the git master branch.
• Checks for an existing vendor branch, and creates if it doesn't.
• Checks out the vendor branch (chef-vendor-COOKBOOK).
• Removes the existing (old) version.
• Untars the cookbook tarball it downloaded in the first step.
• Adds the cookbook files to the git index and commits.
• Creates a tag for the version downloaded.
• Checks out the master branch again.
• Merges the cookbook into master.

The last step will ensure that any local changes or modifications you have made to the cookbook are preserved, so you can keep your changes through upstream updates.

If you're not using Git, use the site download subcommand to download the tarball.

This creates the COOKBOOK.tar.gz from in the current directory (e.g., ~/chef-repo). We recommend following a workflow similar to the above for your version control tool.

data_bags

This directory contains directories of the various data bags you create for your infrastructure. Each subdirectory corresponds to a data bag on the Chef Server, and contains JSON files of the items that go in the bag.

First, create a directory for the data bag.

Then create the JSON files for items that will go into that bag.

The JSON for the ITEM must contain a key named "id" with a value equal to "ITEM". For example,

Next, create the data bag on the Chef Server.

Then upload the items in the data bag's directory to the Chef Server.

roles

Create roles here, in either the Role Ruby DSL (.rb) or JSON (.json) files. To install roles on the server, use knife.

For example, create roles/base_example.rb:

Then upload it to the Chef Server:

certificates

Creating SSL certificates is a common task done in web application infrastructures, so a rake task is provided to generate certificates. These certificates are stored here by the ssl_cert task.

Configure the values used in the SSL certificate by modifying config/rake.rb. To generate a certificate set for a new monitoring server, for example:

Once the certificates are generated, copy them into the cookbook(s) where you want to use them.

In the recipe for that cookbook, create a cookbook_file resource to configure a resource that puts them in place on the destination server.

Rake Tasks

The repository contains a Rakefile that includes tasks that are installed with the Chef libraries. To view the tasks available with in the repository with a brief description, run rake -T.

The default task (default) is run when executing rake with no arguments. It will call the task test_cookbooks.

The following tasks are not directly replaced by knife sub-commands:

• bundle_cookbook - Creates cookbook tarballs in the pkgs/ dir.
• install - Calls update, roles and upload_cookbooks Rake tasks.
• ssl_cert - Create self-signed SSL certificates in certificates/ dir.
• update - Update the repository from source control server, understands git and svn.

The following tasks duplicate functionality from knife and may be removed in a future version of Chef:

• metadata - replaced by knife cookbook metadata -a.
• new_cookbook - replaced by knife cookbook create.
• role - replaced by knife role from file.
• roles - iterates over the roles and uploads with knife role from file.
• test_cookbooks - replaced by knife cookbook test -a.
• test_cookbook - replaced by knife cookbook test COOKBOOK.
• upload_cookbooks - replaced by knife cookbook upload -a.
• upload_cookbook - replaced by knife cookbook upload COOKBOOK.

Configuration

The repository uses two configuration files.

• config/rake.rb
• .chef/knife.rb (optional)

The first, config/rake.rb configures the Rakefile in two sections.

• Constants used in the ssl_cert task for creating the certificates.
• Constants that set the directory locations used in various tasks.

If you use the ssl_cert task, change the values in the config/rake.rb file appropriately. These values were also used in the new_cookbook task, but that task is replaced by the knife cookbook create command which can be configured below.

The second config file, .chef/knife.rb is a repository specific configuration file for knife. If it exists, it will override your primary knife configuration file (in ~/.chef/knife.rb). You do not need to have a knife.rb in your chef-repo if your primary knife configuration file is correct. If you're using the Opscode Platform, you can download a knife configuration for your organization from the management console. If you're using the Open Source Chef Server, you can generate a new one with knife configure. For more information about configuring Knife, see the Knife documentation.

Next Steps

Learn more about Chef Basics or get started on working with Cookbooks at the Cookbook Fast Start Guide. If you did proceed with Git, we have a guide on Working with Git and Cookbooks that you may want to review.

Cookbook Site Help

Data Bags