Chef Metadata
Overview
Each Chef cookbook must contain two metadata files:
- metadata.rb - Contains a Ruby DSL that's used to build the metadata.json file. The metadata.rb file is a human readable version of the metadata.json file. When you create a new cookbook using knife, a metadata.rb will automatically be created for you.
- metadata.json - The actual meta-data file that's used by RightScale (which acts as the Chef Server) to understand the contents of the cookbook and how its components can be used. As of the 2013-10-01 Dashboard release, RightScale automatically generates the .json file (from the metadata.rb file) each time a cookbook is fetched or refetched into Repose.
How does RightScale use Chef Metadata?
The RightScale platform uses Chef metadata to determine what's inside of a Chef cookbook and how its recipes and attributes (inputs) should be used. If a recipe or attribute (input) is not properly defined in the cookbook's metadata.json file, it does not exist from RightScale's point of view. Therefore, it's extremely important that you properly configure your metadata.rb so that all of the cookbook's components are discoverable and usable as expected in the RightScale platform.
A common mistake for many Chef developers is forgetting to update the metadata.rb file with properly formatted information about a new recipe or attribute (input), so that the new script and input appear to be missing and are not displayed as expected in the dashboard.
RightScale relies on a cookbook's metadata to compute the given inputs for each recipe. The screenshot below shows how the content of a cookbook's metadata.rb is used to display the related input information in the dashboard (assuming that the metadata.json file matches the metadata.rb file). Click to enlarge.
Note: There is a size limit of 64KB on the metadata file that can be generated in cookbooks.
How do I update the metadata.rb file?
You must update the metadata correctly whenever you add a new recipe or attribute, otherwise the script and/or inputs will not be visible or usable within the RightScale platform. To learn how to properly construct a metadata.rb file, see Update Cookbook Metadata Files.
Example
Click the link below to view an example of a properly constructed metadata.rb file that follows RightScale's best practices.
Should I generate the metadata.json file?
No. 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 into Repose. However, RightScale still uses the metadata.json file to determine how a cookbook should be represented in the RightScale platform. For this reason, it's very important that each of your cookbooks has a properly formatted metadata.rb file. If there is a problem in a cookbook's metadata.rb file and RightScale is unable to generate the associated metadata.json file, you will have problems using the cookbook in the RightScale platform. As a result, you might not be able to see a recipe and/or add it to a ServerTemplate. Or perhaps an input is not being displayed as a user-configurable parameter under the Inputs tab. If there is an error scraping cookbooks from a repository and the metadata.json files cannot be generated, an error message will be displayed under the Repository object's Info tab.
Important! If cookbook contains a metadata.json file, it will be used as-is and RightScale will not generate a new metadata.json file or override/replace the existing one. It's perfectly acceptable you choose to keep existing metadata.json files in an existing cookbook, especially if you are not actively making changes to the cookbook. However, since RightScale now generates the metadata.json file for a cookbook, you might want to change your developer workflows accordingly to remove this unnecessary step.
- © Copyright 2015 RightScale Technical Support