xenial (1) knife-cookbook.1.gz

Provided by: chef_12.3.0-3ubuntu1_all bug

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:

       • 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.

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:

          • 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 cookbooks 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 in which cookbooks are located.

       -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 cookbooks 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 cookbooks 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 cookbooks 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 12.0                                  KNIFE-COOKBOOK(1)