Cookbook Directories and Metadata

[edit on GitHub]

The cookbooks/ directory is used to store the cookbooks that are used by the chef-client when configuring the various systems in the organization. This directory contains the cookbooks that are used to configure systems in the infrastructure. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.

To configure cookbook-specific copyright, email, and license data, add the following to the config.rb file in the chef-repo:

cookbook_copyright "Example, Com."
cookbook_email     "cookbooks@example.com"
cookbook_license   "apachev2"

where the cookbook_copyright and cookbook_email are specific to the organization and cookbook_license is either apachev2 or none. These settings will be used in the default recipe and in corresponding values in the metadata.rb file, but can be modified in those locations as well (if they should be different from the default values contained in the config.rb file.)

Work with Cookbooks

Use the following knife subcommands to create, install, and/or download cookbooks.

Create

To create a cookbook (including all default components), run the following command:

$ knife cookbook create COOKBOOK_NAME

where COOKBOOK_NAME is the name of the cookbook that will be created. Any unneeded directory components can be left unused or deleted, if preferred.

Install

To download a cookbook when git is used for version source control, run the following command:

$ knife supermarket install COOKBOOK_NAME

where COOKBOOK_NAME is the name of a cookbook on Chef Supermarket. This will start a process that:

  • downloads the cookbook from Chef Supermarket as a tar.gz archive
  • ensures that its using the git master branch, and then checks out the cookbook from a vendor branch (creating a new vendor branch, if required)
  • removes the old (existing) version
  • expands the tar.gz archive and adds the expanded files to the git index and commits
  • creates a tag for the version that was downloaded
  • checks out the master branch
  • merges the cookbook into the master (to ensure that any local changes or modifications are preserved)

Download

To download a cookbook when git is not used for version source control, run the following command:

$ knife supermarket download COOKBOOK_NAME

where COOKBOOK_NAME is the name of a cookbook on Chef Supermarket. This will download the tar.gz file associated with the cookbook and will create a file named COOKBOOK_NAME.tar.gz in the current directory (e.g., ~/chef-repo). Once downloaded, using a version source control system is recommended.

About Cookbook Metadata

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 Client and Server correctly deploy cookbooks to each node.

Error Messages

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.

metadata.rb

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 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 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 server as part of a cookbook upload.

Settings

This configuration file has the following settings:

chef_version

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'

A more complex example where you set both a lower and upper bound of the chef-client version:

chef_version ">= 14.2.1", "< 14.5.1"
depends

This field requires that a cookbook with a matching name and version exists on the Chef server. When the match exists, the Chef server includes 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, the chef-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 into the chef-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 "poise"
gem "chef-sugar"

Warning

Use the gem setting only for making external chef libraries shipped as gems accessible in the chef-client run for libraries and attribute files. The gem setting in metadata.rb allows 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 gem setting in metadata.rb . The gem setting is not a general purpose replacement for the chef_gem resource, and does not internally re-use the chef_gem resource. Native gems require C compilation and must not be installed with metadata.rb because metadata.rb runs before any recipe code runs. Consequently, the chef-client cannot install the C compilers before the gem installation occurs. Instead, install native gems with the chef_gem resource called from the recipe code. You’ll also need to use the build_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 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.

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, or 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.

For example:

license 'Apache-2.0'

or:

license 'GPL-3.0'

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 resources, 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

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 is not visible in Chef Supermarket.

privacy
Specify that a cookbook is private.
provides

Add 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'

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.'
source_url

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.

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 one supports 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 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 opensuse 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'