DragonFly On-Line Manual Pages
KNIFE-COOKBOOK(1) knife cookbook KNIFE-COOKBOOK(1)
NAME
knife-cookbook - The man page for the knife cookbook subcommand.
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:
o Attribute values that are set on nodes
o Definitions that allow the creation of reusable collections of
resources
o File distributions
o Libraries that extend the chef-client and/or provide helpers to Ruby
code
o Recipes that specify which resources to manage and the order in which
those resources will be applied
o Custom resources and providers
o Templates
o Versions
o 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.
COMMON OPTIONS
The following options may be used with any of the arguments available
to the knife cookbook subcommand:
--chef-zero-port PORT
The port on which chef-zero will listen.
-c CONFIG_FILE, --config CONFIG_FILE
The configuration file to use.
-d, --disable-editing
Use to prevent the $EDITOR from being opened and to accept data
as-is.
--defaults
Use to have Knife use the default value instead of asking a user
to provide one.
-e EDITOR, --editor EDITOR
The $EDITOR that is used for all interactive commands.
-E ENVIRONMENT, --environment ENVIRONMENT
The name of the environment. When this option is added to a
command, the command will run only against the named
environment.
-F FORMAT, --format FORMAT
The output format: summary (default), text, json, yaml, and pp.
-h, --help
Shows help for the command.
-k KEY, --key KEY
The private key that Knife will use to sign requests made by the
API client to the Chef server.
--[no-]color
Use to view colored output.
--print-after
Use to show data after a destructive operation.
-s URL, --server-url URL
The URL for the Chef server.
-u USER, --user USER
The user name used by Knife to sign requests made by the API
client to the Chef server. Authentication will fail if the user
name does not match the private key.
-V, --verbose
Set for more verbose outputs. Use -VV for maximum verbosity.
-v, --version
The version of the chef-client.
-y, --yes
Use to respond to all confirmation prompts with "Yes". Knife
will not ask for confirmation.
-z, --local-mode
Use to run the chef-client in local mode. This allows all
commands that work against the Chef server to also work against
the local chef-repo.
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
Use to entirely remove a cookbook (or cookbook version) 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.
Examples
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:
o cookbook/attributes
o cookbook/CHANGELOG.md
o cookbook/definitions
o cookbook/files/default
o cookbook/libraries
o cookbook/metadata.rb
o cookbook/providers
o cookbook/README.md (or .rdoc)
o cookbook/recipes/default.rb
o cookbook/resources
o 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).
Examples
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
Use to delete all cookbooks (and cookbook versions).
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
Use to entirely remove a cookbook (or cookbook version) 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.
Examples
$ 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
Use to overwrite an existing directory.
-N, --latest
Use to download the most recent version of a cookbook.
Examples
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
Use to return all available versions for every cookbook.
-w, --with-uri
Use to show the corresponding URIs.
Examples
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
Use to generate metadata for all cookbooks.
-o PATH:PATH, --cookbook-path PATH:PATH
The directory in which cookbook are created. This can be a
colon-separated path.
Examples
$ 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
$ 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
Use to show the corresponding URIs.
Examples
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
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: []
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
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). This argument will respect
.chefignore files when determining which cookbooks to test for syntax
errors.
Syntax
This argument has the following syntax:
$ knife cookbook test COOKBOOK_NAME (options)
Options
This argument has the following options:
-a, --all
Use to test all cookbooks.
-o PATH:PATH, --cookbook-path PATH:PATH
The directory in which cookbook are created. This can be a
colon-separated path.
Examples
$ 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
Use to upload all cookbooks.
--concurrency
The number of allowed concurrent connections. Default: 10.
-d, --include-dependencies
Use to ensure 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
Use to update a cookbook even if the --freeze flag has been set.
--freeze
Use to require changes to a cookbook 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.
Examples
$ knife cookbook upload cookbook_name
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.
AUTHOR
Chef
Chef 11.14 KNIFE-COOKBOOK(1)