[edit on GitHub]
knife is a command-line tool that provides an interface between a local chef-repo and the Chef server. knife helps users to manage:
- Cookbooks and recipes
- Roles, Environments, and Data Bags
- Resources within various cloud environments
- The installation of the chef-client onto nodes
- Searching of indexed data on the Chef server
The Knife Quick Reference provides an all-in-one quick reference of knife commands. You can view the overview or download the source files.
knife includes a collection of built in subcommands that work together to provide all of 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.
All syntax examples in this document show variables in ALL_CAPS. For example
-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
pp). These variables often require specific values that are unique to each organization.
knife bootstrap subcommand to run a bootstrap operation that installs the chef-client on the target system. The bootstrap operation must specify the IP address or FQDN of the target system.
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 server by any entity that uses the Chef server API, such as the chef-client and knife.
knife configure subcommand to create the client.rb and config.rb files so that they can be distributed to workstations and nodes.
knife cookbook subcommand to interact with cookbooks that are located on the Chef server or the local chef-repo.
|knife data bag
knife data bag subcommand to manage arbitrary stores of globally available JSON data.
knife delete subcommand to delete an object from a Chef 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 subcommand to identify dependencies for a node, role, or cookbook.
knife diff subcommand to compare the differences between files and directories on the Chef server and in the chef-repo. For example, to compare files on the Chef server prior to an 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 subcommand to download roles, cookbooks, environments, nodes, and data bags from the Chef server to the current working directory. It can be used to back up data on the Chef 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 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 edit subcommand to edit objects on the Chef 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 subcommand to manage environments within a single organization on the Chef server.
knife exec subcommand to execute Ruby scripts in the context of a fully configured chef-client. Use this subcommand to run scripts that will only access Chef server one time (or otherwise very infrequently) or any time that an operation does not warrant full usage of the knife subcommand library.
knife list subcommand to view a list of objects on the Chef 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 subcommand to manage the nodes that exist on a Chef server.
knife raw subcommand to send a REST request to an endpoint in the Chef server API.
|knife recipe list
knife recipe list subcommand to view all of the recipes that are on a Chef 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 subcommand to manage the roles that are associated with one or more nodes on a Chef server.
knife search subcommand to run a search query for information that is indexed on a Chef server.
knife serve subcommand to run a persistent chef-zero against the local chef-repo. (chef-zero is a lightweight Chef server that runs in-memory on the local machine.) This is the same as running the chef-client executable with the
--local-mode option. The
chef_repo_path is located automatically and the Chef server will bind to the first available port between
knife serve will print the URL for the local Chef server, so that it may be added to the config.rb file.
knife show subcommand to view the details of one (or more) objects on the Chef 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 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 server.
|knife ssl check
knife ssl check subcommand to verify the SSL configuration for the Chef server or a location specified by a URL or URI. Invalid certificates will not be used by OpenSSL.
When this command is run, the certificate files (
*.pem) that are located in the
/.chef/trusted_certs directory are checked to see if they have valid X.509 certificate properties. A warning is returned when certificates do not have valid X.509 certificate properties or if the
/.chef/trusted_certs directory does not contain any certificates.
When verification of a remote server's SSL certificate is disabled, the chef-client will issue a warning similar to "SSL validation of HTTPS requests is disabled. HTTPS connections are still encrypted, but the chef-client is not able to detect forged replies or man-in-the-middle attacks." To configure SSL for the chef-client, set
:verify_peer (recommended) or
true in the client.rb file.
|knife ssl fetch
knife ssl fetch subcommand to copy SSL certificates from an HTTPS server to the
trusted_certs_dir directory that is used by knife and the chef-client to store trusted SSL certificates. When these certificates match the hostname of the remote server, running
knife ssl fetch is the only step required to verify a remote server that is accessed by either knife or the chef-client.
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 subcommand to display a brief summary of the nodes on a Chef server, including the time of the most recent successful chef-client run.
knife tag subcommand to apply tags to nodes on a Chef server.
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:
knife upload subcommand to upload data to the Chef server from the current working directory in the chef-repo. The following types of data may be uploaded with this subcommand:
- Data bags
- Roles stored as JSON data
- Environments stored as JSON data
(Roles and environments stored as Ruby data will not be uploaded.) This subcommand is often used in conjunction with
knife diff, which can be used to see exactly what changes will be uploaded, and then
knife download, which does the opposite of
knife user subcommand to manage the list of users and their associated RSA public key-pairs.
knife xargs subcommand to take patterns from standard input, download as JSON, run a command against the downloaded JSON, and then upload any changes.
knife includes a set of subcommands that are built around common verbs:
xargs. These subcommands allow knife to issue commands that interact with any object stored in the chef-repo or stored on the Chef 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 (
users). For example:
- A command that works with certain objects in the Chef server, including
- Uses the Chef server as if it were a file system, allowing the chef-repo on the Chef server to behave like a mirror of the chef-repo on the workstation. The Chef server will have the same objects as the local chef-repo. To make changes to the files on the Chef server, just download files from the Chef 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. Enter
knife show base.json and knife will return the base role from the Chef server. From the chef-repo root, enter
knife show roles/base.json to get the same result
- Parallel requests can be made to the Chef server and are configurable on a per-command basis
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 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 server has data bags named
arp_tables, but the local file system only has
anagrams, escaping vs. not escaping the wildcard pattern will yield different results:
$ knife list data_bags/a\*
asks the Chef server for everything starting with the letter "a" and will return:
$ aardvarks/ anagrams/ arp_tables/
But, the following:
$ knife list data_bags/a*
Which is the same as entering:
$ knife list data_bags/aardvarks data_bags/anagrams
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.
Knife plugins ship as RubyGems and are installed into the Chef Workstation installation using the
chef gem install PLUGIN_NAME
Post installation you will also need to rehash the list of knife commands by running:
Chef Maintained Knife Plugins
Chef maintains the following plugins which ship with Chef Workstation:
Community Knife Plugins
Knife plugins written by Chef community members can be found on Supermarket under Knife Plugins.