The Chef repository is the location in which the following data objects are stored:
The Chef repository is located on a workstation and should be synchronized with a version control system, such as git. All of the data in the Chef repository should be treated like source code.
Knife is used to upload data to the Chef Server from the Chef repository. Once uploaded, that data is used by Chef to manage all of the nodes that are registered with the Chef Server and to ensure that the correct cookbooks, environments, roles, and other settings are applied to nodes correctly.
The chef-repo contains several directories, each with a README file that describes what it is for and how to use that directory when managing systems with Chef.
Note
This document describes the default directory that is present in most Chef repositories.
The sub-directories in the Chef repository are:
The certificates/ directory is used to store the SSL certificates that are generated by the Rake task ssl_cert. The values that are used in the SSL certificates can be modified in the config/rake.rb file.
To generate a certificate for a monitoring server:
Run the following command:
$ rake ssl_cert FQDN=monitoring.example.com
Once the certificates are generated, copy them into each cookbook that will use them. For example:
$ cp certificates/monitoring.example.com* cookbooks/COOKBOOK_NAME/files/default
where COOKBOOK_NAME is the name of the cookbook that will use the certificate.
And then in the recipe for each cookbook, create a cookbook_file resource to configure a resource that puts them in place on the destination server:
cookbook_file '/etc/apache2/ssl/monitoring.example.com.pem'
owner 'root'
group 'root'
mode 0600
end
The .chef/ directory is a hidden directory that is used to store .pem validation that are provided by the Chef Server and a knife.rb file. These files are required for interaction with a Chef Server.
The config/ directory is used to store the rake.rb file, which is the configuration file for Rake. Rake is a Ruby application (and a third-party build management tool) that is used by Chef to help manage the installation of various components, including Chef itself, cookbooks, and so on.
The Chef repository uses two configuration files: rake.rb (required) and knife.rb (optional).
The rake.rb file is used to store the configuration details used by Rake, which is a third-party build management tool that is used by Chef to help manage the installation of various components. The config/rake.rb file is also used to generate SSL certificates based on the configuration settings for SSL certificates and the Rake task ssl_cert.
Rake includes tasks that are installed with the Chef libraries. To view the tasks that are available, run rake -T. For more information about Rake, see http://en.wikipedia.org/wiki/Rake_(software).
The following Rake commands are not replaced by Knife sub-commands:
| Command | Description |
|---|---|
| bundle_cookbook | Creates cookbook tar.gz files in the pkgs/ directory. |
| install | Calls the following Rake commands: update, roles, and upload_cookbooks. |
| ssl_cert | Creates self-signed SSL certificates in the certificates/ directory. |
| update | Updates the repository from version control server; understands git and Subversion. |
The following Rake commands duplicate functionality in Chef and may be removed from future updates to the Chef libraries:
| Command | Description |
|---|---|
| metadata | Replaced by: knife cookbook metadata -a. |
| new_cookbook | Replaced by: knife cookbook create. |
| role | Replaced by: knife role from file. |
| roles | Replaced by: knife role from file; iterates over roles and then uploads them. |
| test_cookbooks | Replaced by: knife cookbook test -a. |
| test_cookbook | Replaced by: knife cookbook test COOKBOOK_NAME. |
| upload_cookbooks | Replaced by: knife cookbook upload -a. |
| upload_cookbook | Replaced by: knife cookbook upload COOKBOOK_NAME. |
A knife.rb file is used to specify the repository-specific configuration details for Knife. This file is the default configuration file and is loaded every time this executable is run. The Knife executable cannot be run as a daemon. The configuration file is located at: ~/.chef/knife.rb. If a knife.rb file is present in the .chef/knife.rb directory in the Chef repository, the settings contained within that file will override the default configuration settings.
The cookbooks/ directory is used to store the cookbooks that are used by Chef when configuring the various systems in the organization. This directory contains the cookbooks that are used to configure systems in the infrastructure with Chef. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.
The data_bags/ directory is used to store all of the data bags that exist for a Chef organization. Each sub-directory corresponds to a single data bag on the Chef Server and contains a JSON file for each data bag item. If a sub-directory does not exist, then create it using SSL commands. After a data bag item is created, it can then be uploaded to the Chef Server.
The environments/ directory is used to store the files that define the environments that are available to the Chef Server. The environments files can be Ruby DSL files (.rb) or they can be JSON files (.json). Use Knife to install environment files to the Chef Server.
The roles/ directory is used to store the files that define the roles that are available to the Chef Server. The roles files can be Ruby DSL files (.rb) or they can be JSON files (.json). Use Knife to install role files to the Chef Server.
The chefignore file is used to tell Knife which cookbook files in the Chef repository should be ignored when uploading data to the Chef Server. The type of data that should be ignored includes swap files, version control data, build output data, and so on. The chefignore file uses the File.fnmatch Ruby syntax to define the ignore patterns using *, **, and ? wildcards.
The chefignore file is located at the root of the /cookbooks subdirectory in the Chef repository. It should contain sections similar to the following:
# section
*ignore_pattern
# section
ignore_pattern*
# section
**ignore_pattern
# section
ignore_pattern**
# section
?ignore_pattern
# section
ignore_pattern?
The following examples show how to add entries to the chefignore file.
Ignore editor swap files
Many text editors leave files behind. To prevent these files from being uploaded to the Chef Server, add an entry to the chefignore file. For Emacs, do something like:
*~
and for vim, do something like:
*.sw[a-z]
Ignore top-level Subversion data
If Subversion is being used as the version source control application, it is important not to upload certain files that Subversion uses to maintain the version history of each file. This is because Chef will never use it while configuring nodes, plus the amount of data in an upload that includes top-level Subversion data could be significant.
To prevent the upload of top-level Subversion data, add something like the following to the chefignore file:
*/.svn/*
To verify that the top-level Subversion data is not being uploaded to the Chef Server, use Knife and run a command similar to:
$ knife cookbook show name_of_cookbook cookbook_version | grep .svn
Ignore all files in a directory
The chefignore file can be used to ignore all of the files in a directory. For example:
files/default/subdirectory/*
or:
files/default/subdirectory/**
It is possible for multiple users to access the Chef Server using the same knife.rb file. (A user can even access multiple organizations if, for example, each Chef repository contained the same copy of the knife.rb file.) This can be done by adding the knife.rb file to the Chef repository, and then using environment variables to handle the user-specific credential details and/or sensitive values. For example:
current_dir = File.dirname(__FILE__)
user = ENV['OPSCODE_USER'] || ENV['USER']
node_name user
client_key "#{ENV['HOME']}/.chef/#{user}.pem"
validation_client_name "#{ENV['ORGNAME']}-validator"
validation_key "#{ENV['HOME']}/.chef/#{ENV['ORGNAME']}-validator.pem"
chef_server_url "https://api.opscode.com/organizations/#{ENV['ORGNAME']}"
cache_type 'BasicFile'
cache_options( :path => "#{ENV['HOME']}/.chef/checksums" )
cookbook_path ["#{current_dir}/../cookbooks"]
cookbook_copyright "Your Company, Inc."
cookbook_license "apachev2"
cookbook_email "cookbooks@yourcompany.com"
# all your credentials are belong to us
# Amazon AWS
knife[:aws_access_key_id] = "#{ENV['AWS_ACCESS_KEY_ID']}"
knife[:aws_secret_access_key] = "#{ENV['AWS_SECRET_ACCESS_KEY']}"
# Rackspace Cloud
knife[:rackspace_api_username] = "#{ENV['RACKSPACE_USERNAME']}"
knife[:rackspace_api_key] = "#{ENV['RACKSPACE_API_KEY']}"
There are two ways to create a Chef repository when using the Opscode boilerplate repository as a base:
Note
Opscode strongly recommends using some type of version control tool to manage the source code in the Chef repository. Opscode uses git for everything, including for cookbooks. If another version source control system is preferred over git (such as Subversion, Mercurial, or Bazaar) that is just fine.
The Chef repository is available on github: https://github.com/opscode/chef-repo.
To clone the Chef repository from github:
Download and install git.
Run the following command:
$ git clone git://github.com/opscode/chef-repo.git
(Optional) After the repository is cloned, the history of that repository can be wiped out by removing the ”.git” directory, which allows the initialization of a new repository or to move the Chef repository into another version source control system, such as Subversion, Mercurial, or Bazaar.
Instead of cloning the Chef repository from github, a tar.gz file can be downloaded from github directly (http://github.com/opscode/chef-repo/tarball/master) or through the command shell using GNU Wget (or a similar application).
To download the Chef repository:
Run the following command:
$ wget http://github.com/opscode/chef-repo/tarball/master
Extract the tar.gz file into a directory. For example:
$ tar -zxf master
Move the extracted file to the Chef repository. For example:
$ mv opscode-chef-repo-a3bec38 chef-repo