Default Cookbook Pattern

Without the Default Cookbook Pattern

The best way to explain the benefit of the default pattern is with a practical example.

For example, the OpsCode gems cookbook sets up a local gem server repository. The 'gems::mirror' recipe uses the built-in Chef 'cron' resource to set up a cron job that performs an rsync of gem directories every couple of hours. All Chef resources assume some basic pre-configured server state. (i.e. Any prerequisite requirements were resolved such as the successful installation and configuration of any required utilities.) For example, the 'cron' Chef resource assumes that the cron package is installed. Although the 'cron' package is typically installed on most distributions, there may be some instances where it's not included. So, how can we make sure that the 'cron' package is always installed to satisfy the 'cron' resource dependency?

One way to satisfy the requirement is to install the 'cron' package in the 'gems::mirror' recipe itself using the following code.

package "cron" 

But the problem with that method is that you would have to repeat the code above in every Chef recipe that uses the 'cron' resource. So if you have to update the cron package to satisfy a configuration change that affects platform X, you would have to grep all of the cookbooks for the above package and add the following code.

package "cron"

bash "cron tweak for platform X" do
  only_if do node[:platform] == "platform_x" end
   code <<-EOH
     sed -e "s,something/somthingelse/,,g" /etc/crontab
   EOH
end

Although the method above may seem like a minor fix, it becomes difficult to scale and manage over the lifetime of your codebase, especially if your software development team has several developers. To prevent maintenance nightmares and bugs associated with duplicated code, it's recommended that you follow a more modular and reusable design pattern that's easier to maintain and modify over time.

With the Default Cookbook Pattern

A better way to ensure that all Chef resource dependencies are properly installed is to use a reusable default pattern, where dependencies are resolved by a cookbook's default recipe (default.rb). Each cookbook should have a default.rb recipe that installs and configures all base packages, prerequisites and resources required to run other recipes in the cookbook.

For example, instead of installing the 'cron' package in every recipe that uses the 'cron' resource, you can create a reusable default pattern following the steps below.

1. Create a cookbook that describes the Chef resource. (e.g. cron) The cookbook will manage any 'cron' dependencies. 
2. In the cookbook's default recipe (e.g. 'cron::default.rb') add the code that's required to install and configure the 'cron' package. (cookbooks/cron/recipes/default.rb)

   • package "cron"
     
     # Add any other code to configure cron below 
     

3. For every other cookbook that contains a Chef resource (e.g. Chef recipe) that uses the 'cron' resource, add the 'depends' line of code (e.g. depends "cron") to the cookbook's metadata. For example, if 'cron' is used in a recipe of the 'gems' cookbook, you would add the following line of code to the 'gem' cookbook's 'metadata.rb' file (cookbooks/gems/metadata.rb) because one of its resources depends on cron being installed beforehand. Since the 'cron' cookbook implements the default pattern, when you explicitly define a cookbook dependency in a cookbook's metadata with a cookbook that implements the default pattern, the creators of a runlist/role must include 'cron::default' before any recipe from the gems cookbook to ensure that it can be successfully executed. In the example code below, the default recipes for the 'apache2' and 'cron' cookbooks should be executed before any of the 'gem' cookbook's recipes.

   • maintainer        "Company X"
     maintainer_email  "user@example.com"
     license           "Apache 2.0"
     description       "Sets up a local gem server repository"
     long_description  IO.read(File.join(File.dirname(__FILE__), 'README.rdoc'))
     version           "0.8"
     
     depends           "apache2"
     depends           "cron"
     
     recipe            "gems::server", "Sets up a local gem server repository"
     recipe            "gems::mirror", "Crons an rsync of rubyforge"

4. Use the cron resource in a recipe. (cookbooks/gems/recipes/mirror.rb)

   • #
     # Cookbook Name:: gems
     # Recipe:: mirror
     #
     ...
     
     cron "mirror_rubyforge" do
       command "rsync -av rsync://master.mirror.rubyforge.org/gems/ #{node[:gem_server][:rf_directory]}/gems && gem generate_index -d #{node[:gem_server][:rf_directory]}" 
       hour "2"
       minute "0"
     end

5. In the ServerTemplate's boot scripts list or Chef run list, make sure the 'cron::default' recipe is listed before the 'gems::mirror' recipe to ensure that the 'cron' package will be properly installed and configured before the 'gems::mirror' recipe (which uses the 'cron' resource) is executed.