metadata.rb
Every cookbook requires a small amount of metadata.
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 when the
knife cookbook metadata
subcommand is run, and then stored as JSON data. - Created automatically by knife whenever the
knife cookbook create
subcommand is run. - Edited using a text editor, and then re-uploaded to the Chef Infra Server as part of a cookbook upload.
- Located at the top level of a cookbook’s directory structure.
- Compiled whenever a cookbook is uploaded to the Chef Infra Server or when the
knife cookbook metadata
subcommand is run, and then stored as JSON data. - Created automatically by knife whenever the
knife cookbook create
subcommand is run. - Edited using a text editor, and then re-uploaded to the Chef Infra Server as part of a cookbook upload.
Error Messages
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 isn’t 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.
Note
metadata.rb
file, and then re-uploaded to the Chef Infra Server.Version Constraints
Many fields in a cookbook’s metadata allow the user to constrain versions. The following operators are common to all fields:
Specification | Operator |
---|---|
Pessimistic (see note below) | ~> |
Equal to | = |
Greater than or equal to | >= |
Greater than | > |
Less than | < |
Less than or equal to | <= |
Note
>= 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: ~> 2.2
Settings
This configuration file has the following settings:
chef_version
A range of Chef Infra Client versions that are supported by this cookbook. All version constraint operators are applicable to this field.
For example, to match any 16.x version of the Chef Infra Client, but not 15.x or 17.x:
chef_version '~> 16.0'
A more complex example where you set both a lower and upper bound of the Chef Infra Client version:
chef_version '>= 17.2', '< 17.4'
depends
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’s important that the
depends
field 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
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!'
gem
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'
Warning
Use the
gem
setting only for making external chef libraries shipped as gems accessible in a Chef Infra Client run for libraries and attribute files. Thegem
setting inmetadata.rb
allows for the early installation of this specific type of gem, with the fundamental limitation that it can’t install native gems.Don’t install native gems with the
gem
setting inmetadata.rb
. Thegem
setting isn’t a general purpose replacement for the chef_gem resource, and doesn’t internally re-use thechef_gem
resource. Native gems require C compilation and must not be installed withmetadata.rb
becausemetadata.rb
runs before any recipe code runs. Consequently, Chef Infra Client Linux install the C compilers before the gem installation occurs. Instead, install native gems with thechef_gem
resource called from the recipe code. You’ll also need to use thebuild_essential
resource in the recipe code to install the prerequisite compilers onto the system.Pure ruby gems can also be installed with
metadata.rb
.issues_url
The URL of 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.
For example:
issues_url 'https://github.com/chef-cookbooks/chef-client/issues'
license
The type of license under which a cookbook is distributed:
Apache v2.0
,GPL v2
,GPL v3
,MIT
, orlicense '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.For example:
license 'Apache-2.0'
or:
license 'GPL-3.0'
or:
license 'MIT'
or:
license 'Proprietary - All Rights Reserved'
maintainer
The name of the person responsible for maintaining a cookbook, either an individual or an organization.
For example:
maintainer 'Bob Bobberson'
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’s already setup for mail forwarding.
For example:
maintainer_email 'bob@example.com'
name
Required. The name of the cookbook.
For example:
name 'cats'
ohai_version
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'
Note
This setting isn’t visible in Chef Supermarket.privacy
Specify a cookbook as private. This prevents a cookbook from being uploaded to the public Supermarket or any Supermarket where
ENFORCE_PRIVACY
has been enabled.For example:
privacy true
source_url
The URL of 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.
For example:
source_url 'https://github.com/chef-cookbooks/chef-client'
supports
Show 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 onesupports
field, once for each platform.For example, to support every version of Ubuntu:
supports 'ubuntu'
or, to support versions of Ubuntu greater than or equal to 20.04:
supports 'ubuntu', '>= 20.04'
or, to support only Ubuntu 20.04:
supports 'ubuntu', '= 20.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
version
The current version of a cookbook. Version numbers always follow a simple three-number version sequence.
For example:
version '2.0.0'