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 > RightScale Cookbook Design Conventions

RightScale Cookbook Design Conventions

Table of Contents


The following cookbook design conventions are used by the v12.11 and v13.5 LTS ServerTemplates published by RightScale.

Before you start to create or customize any of these Chef-based ServerTemplates, it's important to have a solid understanding of how RightScale architected its library of cookbooks and ServerTemplates, as well as understand the reasons why RightScale uses certain cookbook design patterns and conventions. It's strongly recommended that you follow these same design conventions in your own custom cookbooks and recipes if you want to use them in ServerTemplates.

Resuable Design Patterns

A reusable design pattern is a common coding convention that allows you to build more efficient and flexible code that's easier to share and manage. Instead of creating a single self-contained script that may include the same sections of code that are repeated in other scripts, you can define smaller pieces of code that are accessible and reusable across an entire codebase. 

Benefits of Reusable Design Patterns

The first step is to understand the problem that we're trying to solve by following certain design patterns. One of the great features of Chef is that it's an example of a loosely coupled configuration system, which allows for extensibility in software design because one design component can reference and use another design component even if it changes over time. However, when you increase flexibility you also potentially increase complexity. Therefore, it's important to establish a set of best practices by following certain design patterns to encourage code consistency and make your cookbooks easier to develop and troubleshoot.

Navigating RightScale's Cookbooks

In the RightScale cookbooks, resource calls in recipes can be calls to built-in resources, lightweight resources, or definitions.

  • Built-in Resources - Resources that are available for use if you are launching servers with RightImages (that include RightLink) are part of Chef . The built-in resources are documented in Chef Resources.
  • Lightweight Resources - They are often named the same as one of the cookbooks, but several are just prefixed with the cookbook name such as 'rightscale_server_collection'. Lightweight resources are defined in a cookbook's 'resources/' directory.  For example, the 'sys_firewall' resource is defined in the 'sys_firewall' cookbook's default resource. (cookbooks/sys_firewall/resources/default.rb) and the 'rightscale_server_collection' resource is defined in cookbooks/rightscale/resources/server_collection.rb. Lightweight resources have accompanying providers, which are located in the 'providers/' subdirectories of cookbooks and will either be in the same cookbook as the resource or, in the case of the Abstract Cookbook Pattern, in the each of the implementation cookbooks. 
  • Definitions - In the RightScale cookbooks, definitions are prefixed with the cookbook name and are located in a cookbook's 'definitions/' directory. For example, the 'rightscale_marker' definition is defined in cookbooks/rightscale/definitions/rightscale_marker.rb.

Dependency Resolution

Typically, cookbooks depend on other cookbooks for resources, providers, and definitions. If a dependency is not explicitly specified in a cookbook's metadata (metadata.rb), its recipes may load without the cookbooks they depend on and will fail to execute. In addition, there are also resources that are set up in default recipes from other cookbooks. When developing or customizing a ServerTemplate, it's important to list all of the boot scripts in the correct order to ensure that any cookbook dependencies are resolved before a recipe that depends on those other resources is executed.

There are two types of cookbook dependencies.

  • Default recipe of the same cookbook - A cookbook often contains a 'default.rb' recipe as well as other more functionally specific recipes (e.g. 'do_some_action.rb'). Since other recipes in a cookbook often depend on some configurations that are set by the cookbook's own default recipe, a cookbook's 'default.rb' recipe is always listed before any of its other scripts in a ServerTemplate's boot scripts list.
  • Default recipe of another cookbook - Similarly, since a recipe can access resources located in other cookbooks, the default recipe of another cookbook may need to be executed before a script can be successfully executed. Cookbook-cookbook dependencies should be clearly called out in a cookbook's metadata.


More information about resolving cookbook dependencies is described below.

Chef Cookbook Design Patterns

See Chef Cookbook Design Patterns.

RightScale Definitions

Definitions are often used for common sequences of resources in Chef recipes that are used in multiple recipes but do not warrant a separate recipe. For example, the 'db::do_primary_backup' and 'db::do_secondary_backup' recipes use the 'db_do_backup' definition that uses a set of resources from the 'db' and 'block_device' cookbooks to perform a database backup. 


Important! RightScale Definitions are used in RightScale's v12 and v13 ServerTemplate releases. See ServerTemplates.




In addition to housing reusable recipe snippets of code that are used within a cookbook, we also use definitions as external methods that other cookbooks can call. For example, the 'rightscale_logrotate_app' definition allows other cookbooks to add their logrotate configurations while deferring details of logrotate to the 'rightscale' cookbook.

Since definitions can be used in recipes located in different cookbooks, it's important to use a naming convention so you can easily locate a definition's code. In the RightScale cookbooks, the location of a definition can be determined by its name. The cookbook where the definition can be found is used as a prefix in its name. For example, the 'rightscale_marker' definition is defined in the 'rightscale' cookbook and the 'db_do_backup' definition is defined in the 'db' cookbook.



All of the recipes in the RightScale cookbooks begin and end with a call to the 'rightscale_marker' definition, which is defined in the 'rightscale' cookbook. It is used for better readability and debugging of the logs. When a Chef runlist is executed, check the audit entries. Recipes that use the 'rightscale_marker' definition print log messages with the cookbook and recipe name in the runlist.

If you want to use the 'rightscale_marker' definition in your own recipes, you must include the 'rightscale' cookbook as a dependency in your cookbook's metadata.


You must to post a comment.
Last modified
15:19, 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.