The Cookbooks Site API is used to provide access to the cookbooks community hosted at http://community.opscode.com/cookbooks. All of the cookbooks in the community are accessible through a RESTful API located at https://cookbooks.opscode.com/api/v1/cookbooks by using any of the supported endpoints. In most cases, using Knife and the knife cookbook site sub-command (and any of its arguments) is the recommended method of interacting with these cookbooks, but in some cases, using the Cookbooks Site API directly may make sense.
The knife cookbook site subcommand is used to interact with cookbooks that are located at http://community.opscode.com/cookbooks. 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.
Note
Review the list of common options available to this (and all) Knife subcommands and plugins.
The download argument is used to download a cookbook from the community website. A cookbook will be downloaded as a tar.gz archive and placed in the current working directory. If a cookbook (or cookbook version) has been deprecated and the --force option is not used, Knife will alert the user that the cookbook is deprecated and then will provide the name of the most recent non-deprecated version of that cookbook.
This argument has the following syntax:
$ knife cookbook site download COOKBOOK_NAME [COOKBOOK_VERSION] (options)
This argument has the following options:
The following examples show how to use this Knife subcommand:
Download a cookbook
To download the cookbook “getting-started”, enter:
$ knife cookbook site download getting-started
to return something like:
Downloading getting-started from the cookbooks site at version 0.3.0 to
/Users/sdanna/opscodesupport/getting-started-0.3.0.tar.gz
Cookbook saved: /Users/sdanna/opscodesupport/getting-started-0.3.0.tar.gz
The install argument is used to install a cookbook that has been downloaded from the community site to a local git repository . This action uses the git version control system in conjunction with the http://community.opscode.com/cookbooks site to install community-contributed cookbooks to the local chef-repo. Using this argument does the following:
- A new “pristine copy” branch is created in git for tracking the upstream.
- All existing versions of a cookbook are removed from the branch.
- The cookbook is downloaded from http://community.opscode.com/cookbooks in the tar.gz format.
- The downloaded cookbook is untarred and its contents are committed to git and a tag is created.
- The “pristine copy” branch is merged into the master branch.
This process allows the upstream cookbook in the master branch to be modified while letting git maintain changes as a separate patch. When an updated upstream version becomes available, those changes can be merged while maintaining any local modifications.
This argument has the following syntax:
$ knife cookbook site install COOKBOOK_NAME [COOKBOOK_VERSION] (options)
This argument has the following options:
The following examples show how to use this Knife subcommand:
Install a cookbook
To install the cookbook “getting-started”, enter:
$ knife cookbook site install getting-started
to return something like:
Installing getting-started to /Users/sdanna/opscodesupport/.chef/../cookbooks
Checking out the master branch.
Creating pristine copy branch chef-vendor-getting-started
Downloading getting-started from the cookbooks site at version 0.3.0 to
/Users/sdanna/opscodesupport/.chef/../cookbooks/getting-started.tar.gz
Cookbook saved: /Users/sdanna/opscodesupport/.chef/../cookbooks/getting-started.tar.gz
Removing pre-existing version.
Uncompressing getting-started version /Users/sdanna/opscodesupport/.chef/../cookbooks.
removing downloaded tarball
1 files updated, committing changes
Creating tag cookbook-site-imported-getting-started-0.3.0
Checking out the master branch.
Updating 4d44b5b..b4c32f2
Fast-forward
cookbooks/getting-started/README.rdoc | 4 +++
cookbooks/getting-started/attributes/default.rb | 1 +
cookbooks/getting-started/metadata.json | 29 ++++++++++++++++++++
cookbooks/getting-started/metadata.rb | 6 ++++
cookbooks/getting-started/recipes/default.rb | 23 +++++++++++++++
.../templates/default/chef-getting-started.txt.erb | 5 +++
6 files changed, 68 insertions(+), 0 deletions(-)
create mode 100644 cookbooks/getting-started/README.rdoc
create mode 100644 cookbooks/getting-started/attributes/default.rb
create mode 100644 cookbooks/getting-started/metadata.json
create mode 100644 cookbooks/getting-started/metadata.rb
create mode 100644 cookbooks/getting-started/recipes/default.rb
create mode 100644 cookbooks/getting-started/templates/default/chef-getting-started.txt.erb
Cookbook getting-started version 0.3.0 successfully installed
The list argument is used to view a list of cookbooks that are currently available at http://community.opscode.com/cookbooks.
This argument has the following options:
The following examples show how to use this Knife subcommand:
View a list of cookbooks
To view a list of cookbooks at http://community.opscode.com/cookbooks server, enter:
$ knife cookbook site list
to return:
1password homesick rabbitmq
7-zip hostname rabbitmq-management
AmazonEC2Tag hosts rabbitmq_chef
R hosts-awareness rackspaceknife
accounts htop radiant
ack-grep hudson rails
activemq icinga rails_enterprise
ad id3lib redis-package
ad-likewise iftop redis2
ant iis redmine
[...truncated...]
The search argument is used to search for a cookbook at http://community.opscode.com/cookbooks. A search query is used to return a list of cookbooks at http://community.opscode.com/cookbooks and uses the same syntax as the knife search sub-command.
This command does not have any specific options.
The following examples show how to use this Knife subcommand:
Search for cookbooks
To search for all of the cookbooks that can be used with Apache, enter:
$ knife cookbook site search apache*
to return something like:
apache2:
cookbook: http://cookbooks.opscode.com/api/v1/cookbooks/apache2
cookbook_description: Installs and configures apache2 using Debian symlinks with helper definitions
cookbook_maintainer: opscode
cookbook_name: apache2
instiki:
cookbook: http://cookbooks.opscode.com/api/v1/cookbooks/instiki
cookbook_description: Installs instiki, a Ruby on Rails wiki server under passenger+Apache2.
cookbook_maintainer: jtimberman
cookbook_name: instiki
kickstart:
cookbook: http://cookbooks.opscode.com/api/v1/cookbooks/kickstart
cookbook_description: Creates apache2 vhost and serves a kickstart file.
cookbook_maintainer: opscode
cookbook_name: kickstart
[...truncated...]
The show argument is used to view information about a cookbook on http://community.opscode.com/cookbooks.
This argument has the following syntax:
$ knife cookbook site show COOKBOOK_NAME [COOKBOOK_VERSION]
This argument has the following options:
The following examples show how to use this Knife subcommand:
Show cookbook data
To show the details for a cookbook named “haproxy”:
$ knife cookbook site show haproxy
to return something like:
average_rating:
category: Networking
created_at: 2009-10-25T23:51:07Z
description: Installs and configures haproxy
external_url:
latest_version: http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
maintainer: opscode
name: haproxy
updated_at: 2011-06-30T21:53:25Z
versions:
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_2
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_1
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_0
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_1
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_0
http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_7_0
Show cookbook data as JSON
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.