Using Chef Supermarket: A Guided Tour

Supermarket is the Chef community’s central clearing house for sharing cookbooks, tools, and plugins. It is a place for Chef community members to download community cookbooks, collaborate on cookbooks, and upload cookbooks to be used by other community members. It is also the place to share information about tools that improve Chef’s ecosystem. The Supermarket makes it easier to start participating in Chef’s open source projects by allowing individuals and corporations to sign and manage their Contributor License Agreements (CLA’s). Check out the Supermarket Announcement Blog Post for more information.

There are two versions of Supermarket available today.

Public Supermarket

This is available at the Chef Supermarket site. This is an open source project, you can find and contribute to the repo on GitHub.

Private Supermarket

There is also a version of Supermarket that can be run privately in your own infrastructure. This guide will not cover the private version of Supermarket, but many of the same principles will apply. Stay tuned for a Private Supermarket guide!

Getting Started with Supermarket

There are a few things you will need to work with Supermarket.


You will need Knife to interact with the Supermarket.

The easiest way to get Knife (along with many other tools needed to use both Supermarket and Chef) is through the Chef Development Kit.

Make sure you have a knife.rb config file setup.

This guide will take you through the basics of using Knife and Supermarket. For more information on the various commands and options, please see the full Knife cookbook site documentation.

Browsing the Supermarket

You can now take several actions to browse the community cookbooks available on the Supermarket site.


To see a list of all community cookbooks available from Supermarket, run the following:

$ knife cookbook site list

This will return lots of output similar to:

  1password                            minecraft
  301                                  mineos
  7-zip                                minidlna
  AWS\_see\_spots\_run                    minitest
  AmazonEC2Tag                         minitest-handler
  Appfirst-Cookbook                    mirage
  CVE-2014-3566-poodle                 mlocate
  CVE-2015-0235                        mod\_security
  Obfsproxy                            mod\_security2
  R                                    modcloth-hubot
  Rstats                               modcloth-nad
  SysinternalsBginfo                   modman
  VRTSralus                            modules
  abiquo                               mogilefs
  acadock                              mongodb
  accel-ppp                            mongodb-10gen
  accounts                             mongodb-agents
  accumulator                          monit


Looking for a particular cookbook? The most downloaded cookbook as of February 2015 is the mysql cookbook. If I wanted to search for this cookbook I would use a command similar to this:

$ knife cookbook site search mysql

Which will return output similar to this:

    cookbook\_description: Provides mysql\_service, mysql\_config, and mysql\_client resources
    cookbook\_maintainer:  chef
    cookbook\_name:        mysql
    cookbook\_description: Installs/Configures mysql-apt-config
    cookbook\_maintainer:  tata
    cookbook\_name:        mysql-apt-config
    cookbook\_description: MySQL replication wrapper cookbook
    cookbook\_maintainer:  rackops
    cookbook\_name:        mysql-multi

Let’s take a closer look at that first mysql cookbook.


To view more information about a particular cookbook, run the following:

$ knife cookbook site show mysql

Which will return input similar to this:

  category:           Other
  created\_at:         2009-10-28T19:16:54.000Z
  deprecated:         false
  description:        Provides mysql\_service, mysql\_config, and mysql\_client resources
  foodcritic_failure: true
  maintainer:         chef
      total:    79275449
      0.10.0: 927561
      0.15.0: 927536
      0.20.0: 927321
      0.21.0: 927298
      0.21.1: 927311
      0.21.2: 927424
      0.21.3: 927441
      0.21.5: 927326
      0.22.0: 927297
      0.23.0: 927353
      0.23.1: 927862
      0.24.0: 927316

If you want to take a look at a specific version of a cookbook, include it in the command like this:

$ knife cookbook site show mysql 0.10.0

Which will return output similar to:

  license:           Apache 2.0
  tarball\_file\_size: 7010
  version:           0.10.0

Downloading and Installing from the Supermarket

Ready to downlad and install a cookbook from the community site?


To download a cookbook as a tar.gz archive and place it in the current working directory, use the download command.

$ knife cookbook site download mysql


Installing a cookbook is similar to downloading it, but rather than saving the cookbook as a tar.gz, it extracts the cookbook and sets up a git branch so you can keep it up to date with the original cookbook. See this Stack Overflow for an excellent explanation.

It also resolves dependencies and creates a new branch for each of the dependent cookbooks.

$ knife cookbook site install mysql

NOTE: If you receive the error “ERROR: IOError: Cannot open or read /Users/nshamrell/chef-repo/cookbooks/mysql/metadata.rb”, check which version of knife you are using with:

$ knife -v

If it is lower than Chef: 12.0.2, you will need to update your version of Knife. However, if you are using Chef DK and rvm, try running this command:

$ rvm use system

Then retry

$ knife cookbook site install mysql

Uploading to the Supermarket

Now let’s upload a cookbook to the Supermarket. If you have a cookbook of your own you would like to use, please do! If you’d like some guidance in creating a very basic cookbook of you own to practice uploading to the Supermarket, see the “Create Cookbook” section of this section of the Supermarket Docs.


There are a few things you’ll need in place before you can upload your cookbook to the Supermarket.
First, take a look at your knife.rb configuration file. Mine lives at .chef/knife.rb.

You will need to have lines similar to this in the config file. If you don’t already have them, please add them in.

  node\_name "nellshamrell" # Replace with the login name you use to login to the Supermarket.
  client\_key "#{ENV['HOME']}/.chef/client.pem" # Define the path to wherever your client.pem file lives.  This is the key you generated when you signed up for a Chef account.
  cookbook\_path [ '/Users/nshamrell/Projects/my\_chef\_repo/cookbooks' ] # Directory where the cookbook you're uploading resides.

We also recommend that you add both a source\_url' and 'issues\_url' in your cookbooks┬ámetadata. Then, when your cookbook appears on Supermarket, it will also display a link to your cookbook’s source (i.e. a GitHub repo) and issues (i.e. GitHub issues for your repo).

Then use this command to upload the cookbook to the Supermarket!

$ knife cookbook site share "my\_apache2\_cookbook" "Web Servers"

Notice that I defined the Supermarket category my cookbook should be in – in this case, “Web Servers”. Other categories you can use are “Databases”, “Process Management”, “Monitoring & Trending”, “Programming Languages”, “Package Management”, “Applications”, “Networking”, “Operating Systems & Virtualization”, “Utilities”, or “Other”.


Stove is an alternate tool for sharing cookbooks. For more information, please see the project GitHub page.


Should you ever need to unshare a cookbook from the Supermarket, you can use the “unshare” command to do so.

$ knife cookbook site unshare my\_apache2\_cookbook

This will remove your cookbook from the Supermarket site.

If you receive an error which looks like this:

ERROR: Invalid Redirect: DELETE request was redirected from\_apache2\_cookbook to\_apache2\_cookbook. Only GET and HEAD support redirects.
Change your server location in knife.rb to the server's FQDN to avoid unwanted redirections.

You need to upgrade your Chef version to 12.1.1 or higher. Visit the Chef Client Download Site to download and install it for your operating system.

For more information, check out the Supermarket docs.

And there you have it, the basics of using Chef Supermarket! Happy cooking!

Author Nell Shamrell-Harrington

Nell Shamrell-Harrington is a Software Development Engineer at Chef, focusing on the Supermarket open source product. She also sits on the advisory board for the University of Washington Certificates in Ruby Programming and DevOps. She specializes in Chef, Ruby, Rails, Regular Expressions, and Test Driven Development and has traveled the world speaking on these topics. Prior to entering the world of software development, she studied and worked in the field of theatre. The world of theatre prepared her well for the dynamic world of creating software applications. In both, she strives to create a cohesive and extraordinary experience. In her free time she enjoys practicing the martial art Naginata.