What is a chef wrapper cookbook?

 

Simply put, a wrapper cookbook is just a regular cookbook that includes recipes from other cookbooks. Common use cases for wrapper cookbooks include:

• Modifying the behavior of a community cookbook from the Chef Supermarket
• Bundling several base cookbooks into a single cookbook
• Version controlling a node’s run list and attribute definitions

Writing a Wrapper Cookbook

To include another cookbook in your wrapper cookbook you must do a minimum of two things:

• Add dependencies to your wrapper cookbook’s metadata.rb
• Add an include_recipe line to your wrapper cookbook’s recipes/default.rb

Including Dependencies

Including dependencies is a simple as adding the following to your metadata.rb:

depends 'public_cookbook'

You can also optionally perform version pinning like so:

depends 'public_cookbook', '= 1.4.5'

For more information about version pinning see the metadata.rb page on the Chef Docs site.

Setting Attributes

Setting attributes in your wrapper cookbook is a common way to modify the behavior of the cookbook you are wrapping. Well written community cookbooks support modifying their behavior in this manner and will document its attributes within their README.md.
These attributes can be added in your wrapper cookbook’s attributes/default.rb and/or in your default recipe before your include_recipe line.

I decide where to place the attributes as follows: If the attributes are computed using other attributes or set via logic (e.g case, if, unless) place them in recipes/default.rb otherwise place them in attributes/default.rb

Completing the Wrap

In order to add the functionality from your wrapped cookbook, you will need to include that cookbook in your wrapper cookbook’s default recipe. This is usually done with the help of the include_recipe method, like so:

include_recipe 'public_cookbook::default'

Once you have completed this your cookbook is ready for use.

Sample Use Cases

For the examples below let’s assume we want to use the IIS cookbook from the Chef Supermarket

Creating the wrapper

By running the following chef command we can generate our wrapper cookbook:

chef generate cookbook my_company_iis 

From here we add the following to our metadata.rb

depends 'iis' 

Then we can add the necessary include_recipe line to our recipes/default.rb

include_recipe 'iis::default'

Doing the actions above will create a wrapper cookbook that will use the IIS cookbook to:

• Install IIS
• Ensure the w3svc is enabled and started
• Serve the Default Web Site

Modifying Public Cookbook Behavior

The above example is great, but let’s assume that your company hosts its websites on D: instead of C:. We can change this by modifying the attributes that the IIS cookbook consumes.

To host websites out of D: add the following to your wrapper cookbook’s attributes/default.rb

default['iis']['pubroot']    = 'D:\\inetpub'

default['iis']['docroot']    = 'D:\\inetpub\\wwwroot'

default['iis']['log_dir']    = 'D:\\inetpub\\logs\\LogFiles'

default['iis']['cache_dir']  = 'D:\\inetpub\\temp'  

Adding this to your wrapper cookbook’s attributes file will modify the behavior of the IIS cookbook.

Application Cookbooks

By completing the above you have now created a base cookbook that will install IIS in the fashion that your company desires. Now we can expand on this by utilizing an additional wrapper cookbook.
Let’s say we did the same as above but also created a my_company_app cookbook and included our my_company_iis cookbook with a hard version pinning. By doing this we can give the developer of my_company_app the freedom to have IIS installed to company specifications, but without worrying about how things work behind the scenes.
This allows one team to focus on coding the logic that deploys their web application without also having to code the logic for installing IIS to company specifications.

Modifying the Resource Collection

Take for example, a cookbook that lays down a file on the file system via a template, but that cookbook’s template doesn’t suit your needs.
In your recipe you can use the edit_resource helper method provided by Chef’s Recipe DSLto modify their template resource to point to a template in your wrapper cookbook instead.
In practice it looks like this:

include_recipe 'bad_cookbook::default' 

edit_resource(:template, 'C:\\important\\template\\path.ini') do

  source 'my_beautiful_template.erb'

  cookbook 'my_awesome_wrapper'

end  

Adding this to your wrapper cookbook’s default recipe would allow you to use their cookbook as intended with the exception that your template will be used and not theirs.