About Knife
knife is a command-line tool that provides an interface between a local chef-repo and the Chef Infra Server. knife helps users to manage:
- Nodes
- Cookbooks and recipes
- Roles, Environments, and Data Bags
- Resources within various cloud environments
- The installation of Chef Infra Client onto nodes
- Searching of indexed data on the Chef Infra Server
| Topic | Description |
|---|---|
| Setting up Knife | Configure knife to interact with your organization's Chef Infra Server and infrastructure. |
| Knife Common Options | Common options that are available for all knife subcommands. |
| config.rb | Common options for the config.rb (knife.rb) file |
| config.rb Optional Settings | Additional options for your config.rb file |
Knife Subcommands
knife includes a collection of built in subcommands that work together to provide the functionality required to take specific actions against any object in an organization, including cookbooks, nodes, roles, data bags, environments, and users.
Knife Command Syntax
All knife subcommands have the following syntax:
knife subcommand [ARGUMENT] (options)
Each subcommand has its own set of arguments and options.
Note
-u PORT_LIST (where PORT_LIST is a comma-separated list of
local and public UDP ports) or -F FORMAT (where FORMAT determines the
output format, either summary, text, json, yaml, or pp). These
variables often require specific values that are unique to each
organization.Built-in Subcommands
| Subcommand | Description |
|---|---|
| knife_bootstrap | Use the knife bootstrap subcommand to run a bootstrap operation that
installs Chef Infra Client on the target system. The bootstrap operation
must specify the IP address or FQDN of the target system. |
| knife_client | Use the knife client subcommand to manage an API client list and their
associated RSA public key-pairs. This allows authentication requests to
be made to the Chef Infra Server by any entity that uses the Chef Infra
Server API, such as Chef Infra Client and knife. |
| knife configure | Use the knife configure subcommand to create the client.rb and credential files so that they can be distributed to workstations and nodes. |
| knife cookbook | Use the knife cookbook subcommand to interact with cookbooks that are
located on the Chef Infra Server or the local chef-repo. |
| knife data bag | Use the knife data bag subcommand to manage arbitrary stores of
globally available JSON data. |
| knife delete | Use the knife delete subcommand to delete an object from a Chef Infra
Server. This subcommand works similar to knife cookbook delete,
knife data bag delete, knife environment delete,
knife node delete, and knife role delete, but with a single verb
(and a single action). |
| knife deps | Use the knife deps subcommand to identify dependencies for a node,
role, or cookbook. |
| knife diff | Use the knife diff subcommand to compare the differences between files
and directories on the Chef Infra Server and in the chef-repo. For
example, to compare files on the Chef Infra Server before uploading or
downloading files using the knife download and knife upload
subcommands, or to ensure that certain files in multiple production
environments are the same. This subcommand is similar to the git diff
command that can be used to diff what is in the chef-repo with what is
synced to a git repository. |
| knife download | Use the knife download subcommand to download roles, cookbooks,
environments, nodes, and data bags from the Chef Infra Server to the
current working directory. It can be used to back up data on the Chef
Infra Server, inspect the state of one or more files, or to extract
out-of-process changes users may have made to files on the Chef Infra
Server, such as if a user made a change that bypassed version source
control. This subcommand is often used in conjunction with knife diff,
which can be used to see exactly what changes will be downloaded, and
then knife upload, which does the opposite of knife download. |
| knife edit | Use the knife edit subcommand to edit objects on the Chef Infra
Server. This subcommand works similar to knife cookbook edit,
knife data bag edit, knife environment edit, knife node edit, and
knife role edit, but with a single verb (and a single action). |
| knife environment | Use the knife environment subcommand to manage environments within a
single organization on the Chef Infra Server. |
| knife exec | Use the knife exec subcommand to execute Ruby scripts in the context
of a fully configured Chef Infra Client. Use this subcommand to run
scripts that will only access Chef Infra Server one time (or otherwise
infrequently) or any time that an operation does not warrant full
usage of the knife subcommand library. |
| knife list | Use the knife list subcommand to view a list of objects on the Chef
Infra Server. This subcommand works similar to knife cookbook list,
knife data bag list, knife environment list, knife node list, and
knife role list, but with a single verb (and a single action). |
| knife node | Use the knife node subcommand to manage the nodes that exist on a Chef
Infra Server. |
| knife raw | Use the knife raw subcommand to send a REST request to an endpoint in
the Chef Infra Server API. |
| knife recipe list | Use the knife recipe list subcommand to view all of the recipes that
are on a Chef Infra Server. A regular expression can be used to limit
the results to recipes that match a specific pattern. The regular
expression must be within quotes and not be surrounded by forward
slashes (/). |
| knife role | Use the knife role subcommand to manage the roles that are associated
with one or more nodes on a Chef Infra Server. |
| knife search | Use the knife search subcommand to run a search query for information
that is indexed on a Chef Infra Server. |
| knife serve | Use the knife serve subcommand to run a persistent chef-zero against
the local chef-repo. (chef-zero is a lightweight Chef Infra Server that
runs in-memory on the local machine.) This is the same as running the
Chef Infra Client executable with the --local-mode option. The
chef_repo_path is located automatically and the Chef Infra Server will
bind to the first available port between 8889 and 9999.
knife serve will print the URL for the local Chef Infra Server, so
that it may be added to the config.rb file. |
| knife show | Use the knife show subcommand to view the details of one (or more)
objects on the Chef Infra Server. This subcommand works similar to
knife cookbook show, knife data bag show, knife environment show,
knife node show, and knife role show, but with a single verb (and a
single action). |
| knife ssh | Use the knife ssh subcommand to invoke SSH commands (in parallel) on a
subset of nodes within an organization, based on the results of a
search query made to the Chef Infra Server. |
| knife ssl check | Use the When this command is run, the certificate files ( Warning When verification of a remote server’s SSL certificate is disabled, Chef
Infra Client will issue a warning similar to “SSL validation of HTTPS
requests is disabled. HTTPS connections are still encrypted, but Chef
Infra Client is not able to detect forged replies or man-in-the-middle
attacks.” To configure SSL for Chef Infra Client, set ssl_verify_mode
to :verify_peer (recommended) or verify_api_cert to true in
the client.rb file. |
| knife ssl fetch | Use the Warning It is the user’s responsibility to verify the authenticity of every SSL
certificate before downloading it to the /.chef/trusted_certs
directory. knife will use any certificate in that directory as if it is
a 100% trusted and authentic SSL certificate. knife will not be able to
determine if any certificate in this directory has been tampered with,
is forged, malicious, or otherwise harmful. Therefore it is essential
that users take the proper steps before downloading certificates into
this directory. |
| knife status | Use the knife status subcommand to display a brief summary of the
nodes on a Chef Infra Server, including the time of the most recent
successful Chef Infra Client run. |
| knife tag | Use the knife tag subcommand to apply tags to nodes on a Chef Infra
Server. |
| knife supermarket | Use the knife supermarket subcommand to interact with cookbooks that are available in the Chef Supermarket. A user account is required for any community actions that write data to this site. The following arguments do not require a user account: download, search, install, and list. |
| knife upload | Use the
(Roles and environments stored as Ruby data will not be uploaded.) This
subcommand is often used in conjunction with |
| knife user | Use the knife user subcommand to manage the list of users and their
associated RSA public key-pairs. |
| knife xargs | Use the knife xargs subcommand to take patterns from standard input,
download as JSON, run a command against the downloaded JSON, and then
upload any changes. |
Verb Subcommands
knife includes a set of subcommands that are built around common verbs:
delete, deps, diff, download, edit, list, show, upload,
xargs. These subcommands allow knife to issue commands that interact
with any object stored in the chef-repo or stored on the Chef Infra
Server. Some important principles behind this group of subcommands
includes:
- A command that works with each object in the chef-repo. The subcommands specify the desired action (the “verb”), and then directory in which that object resides (
clients,cookbooks/,data_bags/,environments/,nodes,roles/, andusers). For example:download cookbooks/ - A command that works with certain objects in the Chef Infra Server, including
acls,groups, andcontainers - Uses the Chef Infra Server as if it were a file system, allowing the chef-repo on the Chef Infra Server to behave like a mirror of the chef-repo on the workstation. The Chef Infra Server will have the same objects as the local chef-repo. To make changes to the files on the Chef Infra Server, just download files from the Chef Infra Server or upload files from the chef-repo
- The context from which a command is run matters. For example, when working in the
roles/directory, knife will know what is being worked with. Enterknife show base.jsonand knife will return the base role from the Chef Infra Server. From the chef-repo root, enterknife show roles/base.jsonto get the same result - Parallel requests can be made to the Chef Infra Server and are configurable on a per-command basis
Wildcard Search
A wildcard matching pattern can be used for substring matches that replace zero (or more) characters. There are two types of wildcard patterns:
- A question mark ("?") can be used to replace exactly one character (as long as that character is not the first character)
- An asterisk ("*") can be used to replace any number of characters (including zero)
Wildcard patterns must be escaped (using a backslash) so that the
wildcard itself can reach the Chef Infra Server. If they are not
escaped, the wildcard is expanded into the actual filenames and knife
will not know the wildcard was intended to be used. For example, if the
Chef Infra Server has data bags named aardvarks, anagrams, and
arp_tables, but the local file system only has aardvarks and
anagrams, escaping vs. not escaping the wildcard pattern will yield
different results:
knife list data_bags/a\*
asks the Chef Infra Server for everything starting with the letter “a” and will return:
aardvarks/ anagrams/ arp_tables/
But, the following:
knife list data_bags/a*
will return:
aardvarks/ anagrams/
Which is the same as entering:
knife list data_bags/aardvarks data_bags/anagrams
to return:
aardvarks/ anagrams/
Knife Plug-ins
Knife functionality can be extended with plugins, which work the same as built-in subcommands (including common options). Knife plugins have been written to interact with common cloud providers, to simplify common Chef tasks, and to aid in Chef workflows.
Plugin Installation
Knife plugins ship as RubyGems and are installed into the Chef
Workstation installation using the chef command:
chef gem install PLUGIN_NAME
Post installation you will also need to rehash the list of knife commands by running:
knife rehash
Chef Maintained Knife Plugins
Chef maintains the following plugins which ship with Chef Workstation:
knife-aclknife-azureknife-ec2knife-googleknife-lparknife-opcknife-openstackknife-rackspaceknife-reportingknife-vcenterknife-windows
Community Knife Plugins
Knife plugins written by Chef community members can be found on Supermarket under Knife Plugins.