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.

Knife

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.

List

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
  [etc]

Search

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:

  mysql:
    cookbook:             http://cookbooks.opscode.com/api/v1/cookbooks/mysql
    cookbook_description: Provides mysql_service, mysql_config, and mysql_client resources
    cookbook_maintainer:  chef
    cookbook_name:        mysql
  mysql-apt-config:
    cookbook:             http://cookbooks.opscode.com/api/v1/cookbooks/mysql-apt-config
    cookbook_description: Installs/Configures mysql-apt-config
    cookbook_maintainer:  tata
    cookbook_name:        mysql-apt-config
  mysql-multi:
    cookbook:             http://cookbooks.opscode.com/api/v1/cookbooks/mysql-multi
    cookbook_description: MySQL replication wrapper cookbook
    cookbook_maintainer:  rackops
    cookbook_name:        mysql-multi

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

Show

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

 $ knife cookbook site show mysql

Which will return input similar to this:

 average_rating:
  category:           Other
  created_at:         2009-10-28T19:16:54.000Z
  deprecated:         false
  description:        Provides mysql_service, mysql_config, and mysql_client resources
  external_url:       http://github.com/opscode-cookbooks/mysql
  foodcritic_failure: true
  issues_url:
  latest_version:     http://cookbooks.opscode.com/api/v1/cookbooks/mysql/versions/6.0.15
  maintainer:         chef
  metrics:
    downloads:
      total:    79275449
    versions:
      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:

  average_rating:
  cookbook:          http://cookbooks.opscode.com/api/v1/cookbooks/mysql
  file:              http://cookbooks.opscode.com/api/v1/cookbooks/mysql/versions/0.10.0/download
  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?

Download

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

Install

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.

Share

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

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

Unshare

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 https://supermarket.getchef.com/api/v1/cookbooks/my\_apache2\_cookbook to https://supermarket.chef.io/api/v1/cookbooks/my\_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 Principal Software Development Engineer at Chef and member of the Habitat core team. She specializes in Chef, Ruby, Rails, Rust, 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.