RightScale Cookbook Design Conventions

Overview

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. 

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.