Every cookbook requires a small amount of metadata. A file named metadata.rb is located at the top of every cookbook directory structure. The contents of the metadata.rb file provides information that helps Chef Infra Client and Server correctly deploy cookbooks to each node.
A metadata.rb file is:
- Located at the top level of a cookbook’s directory structure.
- Compiled whenever a cookbook is uploaded to the Chef Infra Server or
knife cookbook metadatasubcommand is run, and then stored as JSON data.
- Created automatically by knife whenever the
knife cookbook createsubcommand is run.
- Edited using a text editor, and then re-uploaded to the Chef Infra Server as part of a cookbook upload.
The Chef Infra 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 Infra 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 Infra Server
about cookbook distribution, verify the
depends entries in the
metadata.rb file, and then try again.
Many fields in a cookbook’s metadata allow the user to constrain versions. There are a set of operators common to all fields:
|Pessimistic (see note below)|
|Greater than or equal to|
|Less than or equal to|
>= 2.2.0, < 3.0. Instead, we can write this by combining a tilde “~” and right angle bracket “>”–often called a tilde-rocket or “twiddle-wakka”–followed by the major and minor version numbers. For example:
This configuration file has the following settings:
A range of Chef Client versions that are supported by this cookbook. All version constraint operators are applicable to this field.
For example, to match any 14.x version of the Chef Client, but not 13.x or 15.x:
chef_version '~> 14.0'
A more complex example where you set both a lower and upper bound of the Chef Infra Client version:
chef_version '>= 14.2.1', '< 14.5.1'
This field requires that a cookbook with a matching name and version exists on the Chef Infra Server. When the match exists, the Chef Infra Server includes the dependency as part of the set of cookbooks that are sent to the node during a Chef Infra Client run. It is very important that the
dependsfield contain accurate data. If a dependency statement is inaccurate, Chef Infra Client may not be able to complete the configuration of the system. All version constraint operators are applicable to this field.
For example, to set a dependency a cookbook named
or, to set a dependency on the same cookbook, but only when the version is less than 1.0:
depends 'cats', '< 1.0'
A short description of a cookbook and its functionality.
description 'A fancy cookbook that manages a herd of cats!'
Specifies a gem dependency for installation in Chef Infra Client through bundler. The gem installation occurs after all cookbooks are synchronized but before loading any other cookbooks. Use this attribute one time for each gem dependency. For example:
gem 'loofah' gem 'chef-sugar'
gemsetting only for making external chef libraries shipped as gems accessible in a Chef Infra Client run for libraries and attribute files. The
metadata.rballows for the early installation of this specific type of gem, with the fundamental limitation that it cannot install native gems. Do not install native gems with the
gemsetting is not a general purpose replacement for the chef_gem resource, and does not internally re-use the
chef_gemresource. Native gems require C compilation and must not be installed with
metadata.rbruns before any recipe code runs. Consequently, Chef Infra Client cannot install the C compilers before the gem installation occurs. Instead, install native gems with the
chef_gemresource called from the recipe code. You’ll also need to use the
build_essentialresource in the recipe code to install the prerequisite compilers onto the system. Pure ruby gems can also be installed with metadata.rb.
The URL for the location in which a cookbook’s issue tracking is maintained. This setting is also used by Chef Supermarket. In Chef Supermarket, this value is used to define the destination for the “View Issues” link.
The type of license under which a cookbook is distributed:
license 'Proprietary - All Rights Reserved(default). Please be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe.
license 'Proprietary - All Rights Reserved'
The name of the person responsible for maintaining a cookbook, either an individual or an organization.
maintainer 'Adam Jacob'
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.
Required. The name of the cookbook.
A range of Ohai versions that are supported by this cookbook. All version constraint operators are applicable to this field.
For example, to match any 8.x version of Ohai, but not 7.x or 9.x:
ohai_version '~> 8'
NoteThis setting is not visible in Chef Supermarket.
Specify a cookbook as private.
The URL for the location in which a cookbook’s source code is maintained. This setting is also used by Chef Supermarket. In Chef Supermarket, this value is used to define the destination for the “View Source” link.
Show that a cookbook has a supported platform. Use a version constraint to define dependencies for platform versions:
<=(less than or equal to),
>=(greater than or equal to),
~>(approximately greater than), or
>(greater than). To specify more than one platform, use more than one
supportsfield, once for each platform.
For example, to support every version of Ubuntu:
or, to support versions of Ubuntu greater than or equal to 16.04:
supports 'ubuntu', '>= 16.04'
or, to support only Ubuntu 18.04:
supports 'ubuntu', '= 18.04'
Here is a list of all of the supported specific operating systems:
%w( aix amazon centos fedora freebsd debian oracle mac_os_x redhat suse opensuseleap ubuntu windows zlinux ).each do |os| supports os end
The current version of a cookbook. Version numbers always follow a simple three-number version sequence.