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 > Update Cookbook Metadata Files

Update Cookbook Metadata Files

Overview

RightScale depends on a cookbook's metadata to locate all of its contents so that the its resources can be used in the RightScale management system. Although, RightScale uses the metadata.json file to show a cookbook's contents in the RightScale dashboard, it's automatically generated for you (unless a metadata.json file is present) from the metadata.rb file, which is the more user-friendly metadata file. As a cookbook developer, you are only required to manually edit the metadata.rb file. You're responsible for properly updating and maintaining a cookbook's metadata.rb file to ensure that its related recipes and inputs can be used in the RightScale platform as expected. See Chef Metadata.

Anatomy of metadata.rb

Below is a screenshot of a properly formatted metadata.rb file.

diag-AnatomyMetadata-v2.png


For a detailed description of each field, see http://wiki.opscode.com/display/chef/Metadata#

Update the Metadata

Customize the Header

Basic information about the cookbook is defined in the header section of the metadata.rb file.

  • maintainer - The user/company responsible for maintaining the cookbook
  • maintainer_email -  The email address of the person/group who is responsible for maintaining it.
  • license - The license that the cookbook is distributed under.
  • description - A helpful description of the cookbook.
  • long_description - Detailed description that describes the purpose of the cookbook and how it's intended to be used. The 'README.rdoc' is located in the root of the cookbook and contains the information that is displayed in GitHub and the RightScale dashboard.
  • version - The version of the cookbook.

Declare Cookbook Dependencies

If a recipe in the cookbook depends on parameters that are set by the 'default.rb' recipe of a different cookbook, you need to declare them with a 'depends' statement in the cookbook's metadata. Only cookbooks (not recipes) are allowed to have dependencies. The 'depends' parameter is used for setting a cookbook dependency.

  • depends - Defines any cookbook dependencies that one of its resources (e.g. recipes) has on another cookbook. A common cookbook dependency for many RightScale's Chef-based ServerTemplates is the 'rightscale' cookbook. 


If a particular version of the cookbook is not specified, any version of an attached cookbook (to the ServerTemplate) will satisfy the cookbook dependency (as shown below).

depends "cookbook_name"

For example, if cookbook A's metadata has a dependency on cookbook B, as long as (any version of) cookbook B is attached to the ServerTemplate, the cookbook dependency will be satisfied.

 

If possible, it's recommended that you specify which version(s) of a cookbook satisfy a cookbook dependency (as shown below). 

depends "cookbook_name", "~> 13.5.0"

For example, if cookbook A's metadata has a dependency on cookbook B, where you must use a version greater than 1.0 (> 1.0), the cookbook dependency will only be satisfied if a version of cookbook B that's version 1.1.0 or greater is attached to the ServerTemplate.

Note: You can only attach a single version of a cookbook to a ServerTemplate. (i.e. You cannot attach v1.0 and v1.1, or v1.0 from repository A and v1.0 from repository B).

See About Versions for more information about valid options and proper syntax for specifying a cookbook's version requirements.

Add Chef Recipes

Each recipe must be clearly defined in its cookbook's metadata, otherwise you will not be able add the recipe to a ServerTemplate. Notice how you can use the plus character (+) to split up a long string to make it easier to read. If the recipe contains any inputs, make sure that the recipe is included in the recipes list. See the Declare Inputs section for details.

  • recipe - The name and description of a Chef recipe.
recipe "app_django::run_custom_django_commands",
  "Runs specific user defined commands. Commands will be executed" +
  "in the app directory."

Declare Inputs

attribute "app/backend_ip_type",
  :display_name => "Application IP Type Given to Load Balancer",
  :description =>
    "Specify the IP type where the application server is listening." +
    "You must specify whether it's a public or private IP." +
    " Example: private",
  :required => "recommended",
  :type => "string",
  :choice => ["public", "private"],
  :default => "private",
  :category => "ACME APP",
  :recipes => [
    "app::install_server",
    "app::uninstall_server"
    ]
  • attribute - The name and description of an attribute. These attributes are displayed as user-configurable inputs in the RightScale dashboard/API. These attributes are equivalent to RightScript inputs. By convention, the first element of the attribute name should match the cookbook name. By default, the first element of the attribute name is the Category under which the input is presented on the Inputs page for a ServerTemplate (can be overridden with the category attribute described below).
    • display_name - The name of the attribute (input) that is displayed in the RightScale dashboard under an Inputs tab.
    • description - The description of the attribute. The discription is displayed as a tooltip next to the attribute name in the dashboard.
    • required - Defines whether a value for this attribute is required in order for the script to be executed.
      • required - An input that must have a value specified. Required inputs typically do not have a default so that a user is forced to provide a value.
      • optional - (default if not specified) An input value is not required and can be left blank (unspecified). Optional inputs will appear hidden under the "Advanced" section of the Inputs tabs.
      • recommended - A recommended attribute will appear as an optional input, but it must have a default value predefined in the metadata. 
    • type - The type of value that must be specified. (e.g. string, array) 
    • choice - Defines a predefined set of options that can be selected and used for the attribute. Use this parameter to limit a user's options. (e.g. ["shared", "dedicated"])
    • default - Defines a default value for the input. (e.g. "dedicated") To improve usability of a script, it's strongly recommended that the publisher of the script provide a default value for an attribute that is both advanced and optional.
    • category - By default, an input's category matches its cookbook name. Use the 'category' parameter to override this behavior so that an input will be listed under a different category under the Inputs tabs.
    • recipes - The list of recipes within the current cookbook that use this attribute in the code. (e.g. [ "db::install_server", "db::setup_privileges_admin" ])

Generate the metadata.json file

After the 2013-10-01 Dashboard release, you are no longer required to manually generate the metadata.json file for each cookbook because RightScale will automatically generate the .json file (from the metadata.rb file) each time a cookbook is fetched or refetched. See Chef Metadata for more technical details.

Note: There is a size limit of 64KB on the metadata file that can be generated in cookbooks.

 

You must to post a comment.
Last modified
13:08, 21 Mar 2014

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.