Note: Please go to docs.rightscale.com to access the current RightScale documentation set. Also, feel free to Chat with us!
Home > Guides > Chef Cookbooks Developer Guide > Developer > ServerTemplate Development > Customize a Chef-based ServerTemplate

Customize a Chef-based ServerTemplate

Table of Contents

Objective

To understand the best practices of how to customize an existing Chef-based ServerTemplate such as one from one of the LTS or Infinity releases.

 

Overview

This document explains how to customize an existing ServerTemplate by making one or more of the following changes.

  • Wrap one or more of the attached cookbooks with your own customizations. (e.g. Add or override a Chef attribute or template)
  • Attach an additional cookbook(s) to the ServerTemplate. (i.e. Add new functionality)

Although there are several different ways to customize a Chef-based ServerTemplate, this document will focus on some of the recommended best practices that you can follow and/or incorporate into your own design conventions for modifying existing ServerTemplates. 

 

Prerequisites

  • 'designer' and 'actor' user role privileges in the RightScale account
  • An existing ServerTemplate that you want to modify
  • Understanding of the Wrapper Cookbook Pattern

Steps

Clone the ServerTemplate

  1. Clone and rename the ServerTemplate that you want to modify. (e.g. ACME PHP App Server)

Wrap an Existing Cookbook

  1. Determine which of the ​cookbooks (that are attached to the cloned ServerTemplate) you want to "wrap" with your specific customizations. For example, let's say you want to modify the 'app_php' cookbook. 
  2. Create a new repository in your Source Control Management system (e.g. GitHub) that will store your customizations. It's recommended that you create a new repository for each cookbook instead of creating a single repository that contains multiple cookbooks. 
  3. Create a new cookbook in the repository. It's recommended that you use a custom prefix to create a unique cookbook name. Name the wrapper cookbook accordingly so that it references the library cookbook that it’s going to wrap. For example, if you want to modify the 'app_php' cookbook, you should create a cookbook called 'acme-app_php' in your repository.
  4. Source the cookbook that you want to modify. We will be using this cookbook as a reference for the wrapper cookbook.
  5. If the cookbook attributes are sufficiently parameterized, the wrapper cookbook will simply set these attributes to the desired values. (See Override a Chef Attribute) However, if the cookbook is not sufficiently parameterized, the wrapper cookbook will either set new attributes directly (See Make a Chef Attribute a RightScale Dashboard Input) or use 'chef-rewind' to wrap the library cookbook.  (See Change a Chef Template using Chef Rewind)
  6. If you want to make an existing Chef attribute (e.g. from a community cookbook), an input in the RightScale Dashboard, you will also do this in the wrapper cookbook by correctly defining the Chef attribute as an input in the wrapper cookbook's metadata. (See Make a Chef Attribute a RightScale Input)
  7. If you want to override a parameter defined in a cookbook's metadata file, you will need to fork the repository. For an example of how to make this type of change, see Increase the Number of Block Devices.
  8. Update the wrapper cookbook's metadata.rb file with your changes. (e.g. update version number, add input descriptions, etc.) See Chef Metadata
  9. Create a default recipe for the wrapper cookbook. This default recipe will be used to load all of the wrapper cookbook's configuration by adding the 'default' recipe to the cloned ServerTemplate's boot sequence.
  10. Test your changes. 

 

Example: Override a Chef Attribute

  1. To override a node attribute with the desired value, you will do this in the wrapper cookbook's (e.g. ‘acme-app_php’) ‘attributes/default.rb’ file. Reference the library cookbook to see if the Chef attribute is properly parameterized. Use ‘node.override’ to change the attribute to the desired value.
node.override[‘rails_app’][‘git_repo’] = ‘git@github.com:example_org/example.git’

Example: Make a Chef Attribute a RightScale Input

  1. Add a new Chef attribute to the wrapper cookbook's 'attributes/default.rb’ file or use an existing one.
  2. If you want the new attribute to be displayed as a user-definable input in the RightScale Dashboard (so that it's displayed under an Inputs tab), you must declare the attribute accordingly in the wrapper cookbook’s metadata. See example below.
attribute "ACME-app_php/new_attribute",
  :display_name => "Attribute Name",
  :description =>
    "This attribute..." +
    " Example: option1",
  :choice => ["option1", "option2"],
  :required => "optional",
  :default => "option1",
  :recipes => ["acme-app_php::default"],

Example: Change a Chef Template using Chef Rewind

If the Chef cookbook that you want to modify is NOT properly parameterized (i.e. the parameter that you want to change is not defined as a Chef attribute in the cookbook), you can use 'chef-rewind' to make the modification. 

  1. For example, let's say you want to use a different configuration file than what's defined in the library cookbook. 
template "/etc/php.conf" do
  source "php.conf.erb"
  ​mode "0755"
end
  1. In the wrapper cookbook's ('acme-app_php') 'recipes/default.rb' file, use 'chef-rewind' to specify the new configuration file that you want to use instead.
edit "template[/etc/php.conf]" do
  source "acme-php.conf.erb"
  ​mode "0755"
end

You must to post a comment.
Last modified
10:01, 2 Oct 2013

Tags

This page has no custom tags.

Classifications

This page has no classifications.

Announcements

None


© 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.