Chef

Table Of Contents

knife cookbook

A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including:

  • Attribute values that are set on nodes
  • Definitions that allow the creation of reusable collections of resources
  • File distributions
  • Libraries that extend the chef-client and/or provide helpers to Ruby code
  • Recipes that specify which resources to manage and the order in which those resources will be applied
  • Custom resources and providers
  • Templates
  • Versions
  • Metadata about recipes (including dependencies), version constraints, supported platforms, and so on

The knife cookbook subcommand is used to interact with cookbooks that are located on the Chef server or the local chef-repo.

Note

Review the list of common options available to this (and all) Knife subcommands and plugins.

bulk delete

The bulk delete argument is used to delete cookbook files that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/).

Syntax

This argument has the following syntax:

$ knife cookbook bulk delete REGEX (options)

Options

This argument has the following options:

-p, --purge
Indicates that a cookbook (or cookbook version) will be removed entirely from the Chef server. This action should be used carefully because only one copy of any single file is stored on the Chef server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook bulk delete settings can be added to the knife.rb file:

knife[:purge]
Use to add the --purge option.
knife[:yes]
Use to add the --yes option.

Examples

The following examples show how to use this Knife subcommand:

Bulk delete many cookbooks

Use a regular expression to define the pattern used to bulk delete cookbooks:

$ knife cookbook bulk delete "^[0-9]{3}$" -p

create

The create argument is used to create a new cookbook directory on the local machine, including the following directories and files:

  • cookbook/attributes
  • cookbook/CHANGELOG.md
  • cookbook/definitions
  • cookbook/files/default
  • cookbook/libraries
  • cookbook/metadata.rb
  • cookbook/providers
  • cookbook/README.md (or .rdoc)
  • cookbook/recipes/default.rb
  • cookbook/resources
  • cookbook/templates/default

After the cookbook is created, it can be uploaded to the Chef server using the knife upload argument.

Syntax

This argument has the following syntax:

$ knife cookbook create COOKBOOK_NAME (options)

Options

This argument has the following options:

-C COPYRIGHT_HOLDER, --copyright COPYRIGHT_HOLDER
The name of the copyright holder. This option will place a copyright notice that contains the name of the copyright holder in each of the pre-created files. If this option is not specified, a copyright name of “your_company_name” will be used instead; it can be easily modified later.
-I LICENSE, --license LICENSE
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: Apache v2.0 (for apachev2), GPL v2 (for gplv2), GPL v3 (for gplv3), MIT (for mit), or license 'Proprietary - All Rights Reserved (for none). Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe.
-m EMAIL, --email EMAIL
The email address for the individual who maintains the cookbook. This option will place an email address in each of the pre-created files. If this option is not specified, an email name of “your_email” will be used instead; it can be easily modified later.
-o PATH, --cookbook-path PATH
The directory in which cookbook are created. This can be a colon-separated path.
-r FORMAT, --readme-format FORMAT
The document format of the readme file: md (markdown) and rdoc (Ruby docs).

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook create settings can be added to the knife.rb file:

knife[:readme_format]
Use to add the --readme-format option.

Examples

The following examples show how to use this Knife subcommand:

Create a cookbook

To create a cookbook named “my_cookbook” with copyright, email, license, and readme format options specified, enter:

$ knife cookbook create my_cookbook -C "My Name" -m "my@email.com" -I apachev2 -r md

to return something like:

** Creating cookbook my_cookbook
** Creating README for cookbook: my_cookbook
** Creating metadata for cookbook: my_cookbook

delete

The delete argument is used to delete a specified cookbook or cookbook version on the Chef server (and not locally).

Syntax

This argument has the following syntax:

$ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options)

Options

This argument has the following options:

-a, --all
Indicates that a cookbook and every version of that cookbook will be deleted.
COOKBOOK_VERSION
The version of a cookbook to be deleted. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, Knife will prompt for a version.
-p, --purge
Indicates that a cookbook (or cookbook version) will be removed entirely from the Chef server. This action should be used carefully because only one copy of any single file is stored on the Chef server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook delete settings can be added to the knife.rb file:

knife[:all]
Use to add the --all option.
knife[:print_after]
Use to add the --print-after option.
knife[:purge]
Use to add the --purge option.

Examples

The following examples show how to use this Knife subcommand:

Delete a cookbook

$ knife cookbook delete cookbook_name version

For example:

$ knife cookbook delete smartmon 0.8

Type Y to confirm a deletion.

download

The download argument is used to download a cookbook from the Chef server to the current working directory.

Syntax

This argument has the following syntax:

$ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options)

Options

This argument has the following options:

-d DOWNLOAD_DIRECTORY, --dir DOWNLOAD_DIRECTORY
The directory into which a cookbook will be downloaded.
-f, --force
Indicates that an existing directory will be overwritten.
-N, --latest
Indicates that the most recent version of a cookbook will be downloaded.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook download settings can be added to the knife.rb file:

knife[:download_directory]
Use to add the --dir option.
knife[:force]
Use to add the --force option.
knife[:latest]
Use to add the --latest option.

Examples

The following examples show how to use this Knife subcommand:

Download a cookbook

To download a cookbook named “smartmon”, enter:

$ knife cookbook download smartmon

list

The list argument is used to view a list of cookbooks that are currently available on the Chef server. The list will contain only the most recent version for each cookbook by default.

Syntax

This argument has the following syntax:

$ knife cookbook list (options)

Options

This argument has the following options:

-a, --all
Indicates that all available versions of each cookbook will be returned.
-w, --with-uri
Indicates that the corresponding URIs will be shown.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook list settings can be added to the knife.rb file:

knife[:all]
Use to add the --all option.
knife[:environment]
Use to add the --environment option.

Examples

The following examples show how to use this Knife subcommand:

View a list of cookbooks

To view a list of cookbooks:

$ knife cookbook list

metadata

The metadata argument is used to generate the metadata for one or more cookbooks.

Syntax

This argument has the following syntax:

$ knife cookbook metadata (options)

Options

This argument has the following options:

-a, --all
Indicates that metadata should be generated for all cookbooks, and not just for a specified cookbook.
-o PATH:PATH, --cookbook-path PATH:PATH
The directory in which cookbook are created. This can be a colon-separated path.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook metadata settings can be added to the knife.rb file:

knife[:all]
Use to add the --all option.

Examples

The following examples show how to use this Knife subcommand:

Generate metadata

$ knife cookbook metadata -a

metadata from file

The metadata from file argument is used to load the metadata for a cookbook from a file.

Syntax

This argument has the following syntax:

$ knife cookbook metadata from file FILE

Options

This command does not have any specific options.

Examples

The following examples show how to use this Knife subcommand:

View metadata

$ knife cookbook metadata from file /path/to/file

show

The show argument is used to view information about a cookbook, parts of a cookbook (attributes, definitions, files, libraries, providers, recipes, resources, and templates), or a file that is associated with a cookbook (including attributes such as checksum or specificity).

Syntax

This argument has the following syntax:

$ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (options)

Options

This argument has the following options:

COOKBOOK_VERSION
The version of a cookbook to be shown. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, a list of cookbook versions will be returned.
-f FQDN, --fqdn FQDN
The FQDN of the host.
FILE_NAME
The name of a file that is associated with a cookbook.
-p PLATFORM, --platform PLATFORM
The platform for which a cookbook is designed.
PART
The part of the cookbook to show: attributes, definitions, files, libraries, providers, recipes, resources, or templates. More than one part can be specified.
-V PLATFORM_VERSION, --platform-version PLATFORM_VERSION
The version of the platform.
-w, --with-uri
Indicates that the corresponding URIs will be shown.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook show settings can be added to the knife.rb file:

knife[:fqdn]
Use to add the --fqdn option.
knife[:platform]
Use to add the --platform option.
knife[:platform_version]
Use to add the --platform-version option.

Examples

The following examples show how to use this Knife subcommand:

Show cookbook data

To get the list of available versions of a cookbook named “getting-started”, enter:

$ knife cookbook show getting-started

to return something like:

getting-started   0.3.0  0.2.0

Show cookbook versions

To show a list of data about a cookbook using the name of the cookbook and the version, enter:

$ knife cookbook show getting-started 0.3.0

to return something like:

attributes:
  checksum:     fa0fc4abf3f6787aeb5c3c5c35de667c
  name:         default.rb
  path:         attributes/default.rb
  specificity:  default
  url:          https://somelongurlhere.com
chef_type:      cookbook_version
cookbook_name:  getting-started
definitions:    []
files:          []
frozen?:        false
json_class:     Chef::CookbookVersion
libraries:      []

Show a cookbook version

To only view data about “templates”, enter:

$ knife cookbook show getting-started 0.3.0 templates

to return something like:

checksum:     a29d6f254577b830091f140c3a78b1fe
name:         chef-getting-started.txt.erb
path:         templates/default/chef-getting-started.txt.erb
specificity:  default
url:          https://someurlhere.com

Show cookbook data as JSON

To view information in JSON format, use the -F common option as part of the command like this:

$ knife role show devops -F json

Other formats available include text, yaml, and pp.

test

The test argument is used to test a cookbook for syntax errors. This argument uses Ruby syntax checking to verify every file in a cookbook that ends in .rb and Embedded Ruby (ERB).

Syntax

This argument has the following syntax:

$ knife cookbook test COOKBOOK_NAME (options)

Options

This argument has the following options:

-a, --all
Indicates that all cookbooks will be tested.
-o PATH:PATH, --cookbook-path PATH:PATH
The directory in which cookbook are created. This can be a colon-separated path.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook test settings can be added to the knife.rb file:

knife[:all]
Use to add the --all option.

Examples

The following examples show how to use this Knife subcommand:

Test a cookbook

$ knife cookbook test cookbook_name

upload

The upload argument is used to upload one or more cookbooks (and any files that are associated with those cookbooks) from a local repository to the Chef server. Only files that do not already exist on the Chef server will be uploaded.

Note

Use a .chefignore file to prevent the upload of specific files and file types, such as temporary files or files placed in folders by version control systems. The .chefignore file must be located in the root of the cookbook repository and must use rules similar to filename globbing (as defined by the Ruby File.fnmatch syntax).

Note

Empty directories are not uploaded to the Chef server. To upload an empty directory, create a “dot” file—e.g. .keep—in that directory to ensure that the directory itself is not empty.

Syntax

This argument has the following syntax:

$ knife cookbook upload [COOKBOOK_NAME...] (options)

Options

This argument has the following options:

-a, --all
Indicates that all cookbooks will be uploaded.
--concurrency
The number of allowed concurrent connections. Default: 10.
-d, --include-dependencies
Indicates that when a cookbook has a dependency on one (or more) cookbooks, those cookbooks will also be uploaded.
-E ENVIRONMENT, --environment ENVIRONMENT
Use to set the environment version dependency to the cookbook version being uploaded.
--force
Indicates that a cookbook should be updated even if the --freeze flag has been set.
--freeze
Indicates that a cookbook cannot be modified; any changes to this cookbook must be included as a new version. Only the --force option can override this setting.
-o PATH:PATH, --cookbook-path PATH:PATH
The directory in which cookbook are created. This can be a colon-separated path.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife cookbook upload settings can be added to the knife.rb file:

knife[:all]
Use to add the --all option.
knife[:depends]
Use to add the --include-dependencies option.
knife[:environment]
Use to add the --environment option.
knife[:force]
Use to add the --force option.
knife[:freeze]
Use to add the --freeze option.

Examples

The following examples show how to use this Knife subcommand:

Upload a cookbook

$ knife cookbook upload cookbook_name

Freeze a cookbook

To upload a cookbook, and then prevent other users from being able to make changes to it, enter:

$ knife cookbook upload redis --freeze

to return something like:

Uploading redis...
Upload completed

If a cookbook is frozen and the --force option is not specified, Knife will return an error message similar to the following:

Uploading redis...
ERROR: Version 0.1.6 of cookbook redis is frozen. Use --force to override.