Every cookbook requires a small amount of metadata. Metadata is stored in a file called metadata.rb that lives at the top of each cookbook’s directory. The contents of the metadata.rb file provides hints to the Chef Server so that cookbooks are deployed to each node correctly.
The Chef Server will only try to distribute the cookbooks that are needed to configure an individual node. This is determined by identifying the roles and recipes that are assigned directly to that system, and then to expand the list of dependencies, and then to deliver that entire set to the node. In some cases, if the dependency is not specified in the cookbook’s metadata, the Chef Server may not treat that dependency as a requirement, which will result in an error message. If an error message is received from the Chef Server about cookbook distribution, verify the depends entries in the metadata.rb file, and then try again.
Every cookbook requires a small amount of metadata. Metadata is stored in a file called metadata.rb that lives at the top of each cookbook’s directory. The contents of the metadata.rb file provides hints to the Chef Server so that cookbooks are deployed to each node correctly.
A metadata.rb file is never interpreted directly. Rather, the metadata.rb file provides a simple location to store and edit data that is then compiled by the Chef Server and stored as JSON data. Metadata is compiled whenever the following happens: a cookbook is uploaded to the Chef Server and the knife cookbook metadata sub-command is run. When Knife is used to create a cookbook, a metadata.rb file is created automatically. In general, editing metadata should only be done using the metadata.rb file and then either uploading the cookbook to the Chef Server or by asking the Chef Server to recompile the metadata into JSON data.
Note
A metadata.json file can be edited directly, should temporary changes be required. Any subsequent upload or action that generates metadata will cause the existing metadata.json file to be overwritten with the newly generated metadata. Therefore, any permanent change to metadata that is required should only be made in the metadata.rb file.
This configuration file has the following settings:
| Setting | Description |
|---|---|
| attribute | The list of attributes that are required to configure a cookbook. An attribute name is required, followed by any of these options: display_name (the name that appears in the user interface), description (a short description), choice (an array of choices that are presented to a user), calculated (indicates if the default value is calculated by the recipe), type (the type of value, either string or array), required (the level of user input, either required,``recommended``, or optional), recipes (an array of recipes), or default (the attribute’s default value). For example: attribute 'pets/cat/name',
:display_name => "Cat Name",
:description => "The name of your cat",
:choice => \[
'kitty kitty',
'peanut',
'einstein',
'honey' \],
:type => "string",
:required => "recommended",
:recipes => \[ 'cats::eat' \],
:default => "kitty kitty"
|
| conflicts | Indicates that a cookbook conflicts with another cookbook or cookbook version. Use a version constraint to define constraints for cookbook versions: < (less than), <= (less than or equal to), = (equal to), >= (greater than or equal to), ~> (approximately greater than), or > (greater than). This field requires that a cookbook with a matching name and version exist on the Chef Server. When the match exists, the Chef Server will ensure that any conflicted cookbooks are not included with the set of cookbooks that are sent to the node when the chef-client runs. For example, if a cookbook conflicts with another cookbook named “docs”: conflicts "dogs"
Or if the cookbook conflicted with a cookbook named “dogs” and greater than version 1.0: conflicts "dogs", "> 1.0"
|
| depends | Indicates that a cookbook has a dependency on another cookbook. Use a version constraint to define dependencies for cookbook versions: < (less than), <= (less than or equal to), = (equal to), >= (greater than or equal to), ~> (approximately greater than), or > (greater than). This field requires that a cookbook with a matching name and version exists on the Chef Server. When the match exists, the Chef Server will include the dependency as part of the set of cookbooks that are sent to the node when the chef-client runs. It is very important that the depends field contain accurate data. If a dependency statement is inaccurate, Chef may not be able to complete the configuration of the system. For example, to set a dependency a cookbook named “cats”: depends "cats"
Or, to set a dependency on the same cookbook, but only when the version is less than 1.0: depends "cats", "< 1.0"
|
| description | A short description of a cookbook and its functionality. For example: description 'A fancy cookbook that manages a herd of cats!'
|
| grouping | Adds a title and description to a group of attributes within a namespace. Takes a name (along with the / notation that defines a nested grouping), a title, and a short description. For example: grouping 'pets/cat',
:title => "Cat Options",
:description => "Describe your cat using the options below"
|
| licensing | The type of license under which a cookbook is distributed: apachev2, gplv2, gplv3, mit, or none (default). This option will place the appropriate license notice in the pre-created files. Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe. For example: license 'Apache v2.0'
or: license 'GPL v3'
or: license 'MIT'
or: license 'Proprietary - All Rights Reserved'
|
| long_description | A longer description that ideally contains full instructions on the proper use of a cookbook, including definitions, libraries, dependencies, and so on. There are two ways to use this field: with the contents embedded in the field itself or with the contents pulled from a file at a specified path, such as a README.rdoc located at the top of a cookbook directory. For example, to embed the long description within the field itself: long_description <<-EOH
= DESCRIPTION:
Complete Debian/Ubuntu style Apache2 configuration.
= REQUIREMENTS:
Debian or Ubuntu preferred.
Red Hat/CentOS and Fedora can be used but will be converted to
a Debian/Ubuntu style Apache as it's far easier to manage
with Chef.
= ATTRIBUTES:
The file attributes/apache.rb contains the following attribute
types:
* platform specific locations and settings.
* general settings
* pre-fork attributes
* worker attributes
General settings and pre-fork/worker attributes are tunable.
EOH
Or to read the contents from a specified file: long_description IO.read(File.join
(File.dirname(__FILE__), 'README.rdoc')
)
|
| maintainer | The name of the person responsible for maintaining a cookbook, either an individual or an organization. For example: maintainer 'Adam Jacob'
|
| maintainer_email | The email address for the person responsible for maintaining a cookbook. Only one email can be listed here, so if this needs to be forwarded to multiple people consider using an email address that is already setup for mail forwarding. For example: maintainer_email 'adam@example.com'
|
| name | The name of a cookbook. This field is inferred unless specified. For example: name 'cats'
|
| provides | Adds a recipe, definition, or resource that is provided by this cookbook, should the auto-populated list be insufficient. For example, for recipes: provides "cats::sleep"
provides "cats::eat"
For definitions: provides "here(:kitty, :time_to_eat)"
And for resources: provides "service[snuggle]"
|
| recipe | A description for a recipe, mostly for cosmetic value within the Chef Server user interface. For example: recipe "cats::sleep", "For a crazy 20 hours a day."
Or: recipe "cats::eat", "When they are not sleeping."
|
| recommends | Adds a dependency on another cookbook that is recommended, but not required. A cookbook will still work even if recommended dependencies are not available. For example: recommends "dogs"
Or, to recommend a cookbook named “dogs” and for version 1.0 (or higher): recommends "dogs", "> 1.0"
|
| replaces | Indicates that this cookbook should replace another (and can be used in-place of that cookbook). For example, to replace a cookbook named “dogs” with this cookbook: replaces "dogs"
Or to replace a cookbook named dogs, but only for versions prior to 4.0: replaces "dogs", "< 4.0"
|
| suggests | Adds a dependency on another cookbook that is suggested, but not required. This field is weaker than recommends; a cookbook will still work even when suggested dependencies are not available. For example: suggests "cats"
Or, to suggest a cookbook named “cats”, but only for versions 1.0 and higher. suggests "cats", "> 1.0"
|
| supports | Indicates that a cookbook has a supported platform. Use a version constraint to define dependencies for platform versions: < (less than), <= (less than or equal to), = (equal to), >= (greater than or equal to), ~> (approximately greater than), or > (greater than). To specify more than one platform, use more than one supports field, once for each platform. For example, to support every version of Ubuntu: supports 'ubuntu'
Or, to support versions of Ubuntu between 8.04 and 9.10: supports 'ubuntu', ">= 8.04"
Or, to support only Ubuntu 9.10: supports 'ubuntu', '= 9.10'
|
| version | The current version of a cookbook. Version numbers always follow a simple three-number version sequence. For example: version "1.9.0"
|
