Note: Please go to to access the current RightScale documentation set. Also, feel free to Chat with us!
Home > Guides > Chef Cookbooks Developer Guide > Developer > Cookbook Development Resources > Chef Cookbook Design Patterns > Wrapper Cookbook Pattern

Wrapper Cookbook Pattern

Table of Contents



What is the Wrapper Cookbook Pattern?

The Chef Cookbook Wrapper Pattern is based upon a design convention where you customize an existing "library" cookbook by using a separate "wrapper" cookbook, which "wraps" the original cookbook with any related configuration changes.

  • Library Cookbook - An existing cookbook, typically an open-source contribution from a user in the Chef community, designed for server configuration purposes.
  • Wrapper Cookbook - A cookbook that "wraps" the original library cookbook with custom modifications or additions such as overriding a Chef attribute, changing a Chef template, converting a Chef attribute to a user-definable input, etc. 




Why should I use the Wrapper Cookbook Pattern?

As the Chef community continues to grow, both in the number of active Chef developers and the range of available applications, finding an existing community cookbook that you want to leverage will become more of the norm than the exception. Therefore, it will be easier to find an existing cookbook that you can either use as-is or slightly modify for your own purposes. When possible, it's best to leverage an existing cookbook (assuming that it's actively being maintained) than trying to create your own custom cookbook from scratch or forking a cookbook repository. 

Although forking a repository may initially seem like the easiest way to modify an existing cookbook, it will likely cause you more headaches over time as you try to maintain and upgrade your codebase over time. Therefore, it's recommended that you spend the extra time and effort to integrate a Wrapper Cookbook Pattern into your development routine because you will have a more manageable upgrade path for integrating future bug fixes and new functionality. 

There are several design advantages and overall benefits to using the Wrapper Cookbook Pattern instead of other methods for making customizations.

  1. Easier Upgrade Path - It's easier to upgrade a library cookbook's version if you use the Wrapper Cookbook Pattern because all of your changes will be isolated in a separate (wrapper) cookbook, as opposed to forking and modifying the original cookbook where you will have to manually merge any changes from a newer version of the library cookbook. If you fork a repository for customization purposes, it will be difficult to merge any future bug fixes or feature enhancements. 
  2. Share Wrapper Cookbooks - Give back to the community by sharing your wrapper cookbook.
  3. Leverage Community Cookbooks - Why recreate the wheel? It's best to leverage existing a library cookbook, especially if there is one that's publicly available and actively maintained, which gives you the benefit of incorporating future contributions (i.e. pull requests for bug fixes or new features) to that cookbook.
  4. Easier to Test Modifications - If a newer version of a library cookbook becomes available, which may include critical bug fixes or feature enhancements, you can easily attach a newer version of the library cookbook to a ServerTemplate and test the changes without having to worry about performing differentials of the code and/or merging selective changes to a forked version of the cookbook. In an ideal situation, you could use a newer version of a library cookbook without having to modify its related wrapper cookbook.


There are several types of customizations that are ideal for using the Wrapper Cookbook Pattern.

  • Override a Chef Attribute
  • Make a Chef Attributed a RightScale Input
  • Change a Chef Template using Chef Rewind

See Customize a Chef-based ServerTemplate.

Change a Chef Template using Chef Rewind

The example below demonstrates how to use 'chef-rewind' to use a wrapper cookbook to override a default configuration in a library cookbook.




You must to post a comment.
Last modified
15:05, 23 Sep 2013


This page has no custom tags.


This page has no classifications.



© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.