Skip to end of metadata
Go to start of metadata

This content has been moved to docs.opscode.com

See the following links:

  
Early Bird Pricing for #ChefConf ends March 10th

Presentations on best practices for using Chef in IT operations, cloud architecture, and application development from over 30 companies, including Facebook, General Electric, Nordstrom, Forrester Research, Riot GamesAncestry.com, Edmunds, Kickstarter, Message Bus, Nordstrom, Riot Games and Splunk.

April 24-26, 2013 San Francisco, California

Register today

 

 

 

What is Knife?

Knife is a powerful command-line interface (CLI) that comes with Chef.

It is used by administrators to interact with the Chef Server API and the local Chef repository. It provides the capability to manipulate nodes, cookbooks, roles, databags, environments, etc., and can also be used to provision cloud resources and to bootstrap systems.

Overview

As the administrators command line tool for interacting for the chef server, Knife is run from the management workstation, acting as the intersection between the Chef Server and your infrastructure.

Knife interacts with the Chef Server through the same REST API that the Chef Client software uses, authenticating as an API client. Hosted Chef and Private Chef then have the additional role based authentication controls (RBAC) that authorize changes based upon users and organizations. See Authentication and Authorization for more information on this model.

Knife comes with a series of built in subcommands, which provide the functionality and capability for specific actions upon cookbooks, nodes, roles, etc. within your infrastructure. Knife also has the capability to be a container for Knife Plugins - which extend its functionality beyond the built in commands to features including launching cloud instances and bootstrapping systems.

There is a built in contextual help system for obtaining more information on the commands and subcommands, options for their use, or reviewing manpage documentation. When you go through Workstation Setup, one of the actions includes establishing and configuring knife for use. Subsequent modifications can be made through editing the knife.rb configuration file.

 

Knife Built In Subcommands

The following subcommands are built into Knife, and available for managing their respective components from the Knife command line interface.
See Knife Built In Subcommands for details on use of each.

return to top of page

Subcommands built into Knife:
  • Bootstrap
  • Client
  • Cloud Plugins
  • Configure
  • Cookbook
  • Cookbook Site
  • Data Bag
  • Environment
  • Exec
  • Node
  • Recipe
  • Role
  • Search
  • SSH
  • Status
  • Tag

 

Contextual Help

Knife has a smart contextual help system built right in.

return to top of page

If you invoke knife with the --help option at the top level you will see options common to all subcommands.

 

If you invoke knife with the --help option at a specific subcommand level, knife presents the options specific to that subcommand.

 

Further, you can directly access manpages with content similar to this page using the help sub-command. Use knife help list.

 

You can then read individual pages by using a command in the form of:

Configuring Your System For Knife

 

Knife configuration

The knife configuration file is a Ruby DSL to set configuration parameters for Knife's common options.

return to top of page

Knife's configuration file is named knife.rb. Unless directly passed the configuration file location via the -c command line option, Knife searches for this configuration by searching for .chef/knife.rb, starting at the current working directory and moving upward. If no configuration is found ~/.chef/knife.rb is used if it exists.

The following parameters can be set in knife.rb:
  • node_name:
    User or client identity (i.e., name) to use for authenticating requests to the Chef Server.
  • client_key:
    Private key file to authenticate to the Chef server. Corresponds to the -k or --key option.
  • chef_server_url:
    URL of the Chef server. Corresponds to the -s or --server-url option. This is requested from the user when running this sub-command.
  • cache_type:
    The type of cache to use. Default is BasicFile. This can be any type of Cache that moneta supports: BasicFile, Berkeley, Couch, DataMapper, File, LMC, Memcache, Memory, MongoDB, Redis, Rufus, S3, SDBM, Tyrant, Xattr, YAML.
  • cache_option:
    Specifies various options to use for caching. These options are dependent on the cache_type.
  • validation_client_name:
    Specifies the name of the client used to validate new clients.
  • validation_key:
    Specifies the private key file to use when bootstrapping new hosts. See knife-client(1) for more information about the validation client.
  • cookbook_path: Specifies where knife should look for cookbooks
  • cookbook_copyright, cookbook_email, cookbook_license:
    Used by knife cookbook create sub-command to specify the copyright holder, maintainer email and license (respectively) for new cookbooks. The copyright holder is listed as the maintainer in the cookbook's metadata and as the Copyright in the comments of the default recipe. The maintainer email is used in the cookbook metadata. The license determines what preamble to put in the comment of the default recipe, and is listed as the license in the cookbook metadata. Currently supported licenses are "apachev2" and "none". Any other values will result in an empty license in the metadata (needs to be filled in by the author), and no comment preamble in the default recipe.

 

Knife Plugins

As Chef will load commands from a set of specific locations, you can create plugins for reuse across projects in your home directory, share plugins with your team by including them in your cookbook repo, and share plugins with the whole Chef community by distributing them as Ruby gems.

return to top of page

With Chef 0.10, knife will load commands from the following locations:

  • The core set of knife commands shipped with Chef
  • Commands in your home chef directory: ~/.chef/plugins/knife/
  • Commands in a .chef/plugins/knife/ directory in your cookbook repo
  • Commands located in a chef/knife/ directory in a Ruby Gem you have installed.

See Knife Plugins for details on creating and installing plugins, and Community Plugins for a listing of plugins that have been made available by Chef community members.

 

EDITOR Environment Variable

Many knife commands use the EDITOR environment variable when create or editing objects that will be saved on the Chef Server.

return to top of page

You can set this variable when issuing the command.
Alternatively you can set the variable for the rest of your shell's session.

See your shell's documentation for information on how to ensure that EDITOR is always set when you start a new shell.

Command and Output Options

 

Common Options

The following options can be passed to any subcommand. For sub-command specific options, see the section of Knife Built In Subcommands for the relevant subcommand.

  • -s, --server-url URL:
    Chef Server URL
  • -k, --key KEY:
    API Client Key
  • --color:
    Use colored output
  • -c, --config CONFIG:
    The configuration file to use
  • --defaults:
    Accept default values for all questions
  • -e, --editor EDITOR:
    Set the editor to use for interactive commands
  • -E, --environment ENVIRONMENT:
    Set the Chef environment
  • -F, --format FORMAT:
    Which format to use for output. See the Output Formats section below.
  • --no-color:
    Don't use colors in the output
  • -n, --no-editor:
    Do not open EDITOR, just accept the data as is
  • -u, --user USER:
    API Client Username
  • --print-after:
    Show the data after a destructive operation
  • -V, --verbose:
    More verbose output. Use twice for max verbosity
  • -v, --version:
    Show chef version
  • -y, --yes:
    Say yes to all prompts for confirmation
  • -h, --help:
    Show this message

Output Formats

The amount of content displayed and the output format can be modified by the `--format` option. If no alternate format is selected, the default is summary.

Valid formats are:

  • summary:
    displays the data in a custom, summarized format (default)
  • text:
    displays the data in its entirety using the colorized tree display
  • json:
    displays the data in JSON format
  • yaml:
    displays the data in YAML format
  • pp:
    displays the data using Ruby's pretty printer.

For brevity, only the first character of the format is required, for example, -Fj will produce JSON format output.

 

Bash Command Completion

Get the code here: from Gist
To use, you need the bash-completion package; Source the script from .bashrc or elsewhere.
The script uses the KNIFE_HOME variable to location knife.rb, so be sure to export it if your knife.rb is can't be found.

Completion cache

The completion reads completion alternatives from knife invocations and can be a little slow without caching. To enable the cache, simply create the directory $KNIFE_HOME/.chef/.completion_cache (KNIFE_HOME defaults to $HOME/.chef)
Since environment, role, node and data bag names are cached cache cleanup may be necessary when they change. Simply delete the files in the completion directory.

Bash command completion on OS X (Tested on OS X 10.7.3)

1. Install bash-completion

2. Install gnu-sed

3. Create local bash-completion dir

4. Install knife completions

5. Source core brew-installed bash completion and then our knife stuff in ~/.bash_profile

6. Source your ~/.bash_profile again to refresh



 

 


 

 

 

Labels
  • None
  1. Apr 29, 2011

    If you are using Mac OS X and want to use the knife bash completions mentioned on this page and you are using brew instead of Macports the command to install gsed is:
    brew install gnu-sed

    You'll also have to install bash_completion no mater if you are using Macports or brew. Some good instructions for this and other Mac OS X setup goodness at http://justinhileman.info/article/building-a-lamp-development-environment-on-snow-leopard/ Search for bash_completion on that page.