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 such as Git and treat 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.
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.
certificates/- SSL certificates generated by
rake ssl_certlive here.
config/- Contains the Rake configuration file,
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.
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
The default task (
default) is run when executing
rake with no arguments. It will call the task
The following tasks are not directly replaced by knife sub-commands.
bundle_cookbook[cookbook]- Creates cookbook tarballs in the
ssl_cert- Create self-signed SSL certificates in
update- Update the repository from source control server, understands git and svn.
docs- Builds documentation
docs:publish- Publish docs to readthedocs.org
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[role_name]- 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[cookbook]- replaced by
knife cookbook test COOKBOOK.
upload_cookbooks- replaced by
knife cookbook upload -a.
upload_cookbook[cookbook]- replaced by
knife cookbook upload COOKBOOK.
The repository uses two configuration files.
config/rake.rb configures the Rakefile in two sections.
- Constants used in the
ssl_certtask 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 you're using the Opscode Platform, you can download one 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.
Setting up a development environment
Some things you'll need:
- this repo, cloned locally
- ruby 1.9
- the chef validator key
- a valid chef client key
Some things to consider:
- rbenv: https://github.com/sstephenson/rbenv (via rbenv installer https://github.com/fesplugas/rbenv-installer)
Some common steps:
$ gem install bundler # get our ruby dependencies # Create local binstubs and install the gems right here. $ bundle install --binstubs --path .gems # get our chef cookbook dependencies $ bundle exec berks install
We use berkshelf to manage our cookbooks and dependencies. Berkshelf is straight forward.
To get started with it, look here: http://berkshelf.com/
From the command line, it looks like this:
List all of our cookbooks
$ bundle exec berks list
Install all our 3rd party dependencies. Note that if you do not run berks update, a Lockfile will not be generated, and uploads will fail.
$ bundle exec berks install && bundle exec berks update
Upload a cookbook managed by berkshelf
$ bundle exec berks upload <cookbook>
Upload all cookbooks
$ bundle exec berks upload
Create a new cookbook
$ bundle exec berks cookbook <cookbook_name>
Testing chef server interactions
We have conveniently included the "chef-zero" gem in our bundle. It will act as a local chef server, allowing you to test things like uploads and other chef server interactions. We have also included a berkshelf config that will use the chef-zero server, as well as a fake key to test with.
I'd suggest using tmux or screen for this...
Here's how to use it:
In one terminal, fire up chef-zero:
$ bundle exec chef-zero
In another, run some berks stuff:
$ bundle exec berks upload -c .berkshelf-test-config.js
You can optionally add a --debug flag to the above command to see tons of extra output.
Read the README file in each of the subdirectories for more information about what goes in those directories.