Using Amazon Opsworks with Berkshelf

AWS, Berkshelf, Chef, Opsworks Posted on

Amazon Opsworks supplies its users with a nice collection of starter cookbooks on GitHub. Berkshelf prefers users treat each cookbook as its own software project, but for Opsworks users, that is not an option. Let me demonstrate a few ways you can use Berkshelf in tandem with Amazon Opsworks.

There are two common ways to force Berkshelf to use the "monolithic repo" mode. Please note: you should only follow this approach if you absolutely have to. We (the Berkshelf core team) highly recommend individual repositories for each cookbook.

Option #1: :rel

Berkshelf supports a :rel option, which loads a cookbook from a relative path inside a given path. This is especially useful when loading a cookbook from GitHub. For example:

cookbook 'unicorn',
  github: 'aws/opsworks-cookbooks',
  branch: 'release-chef-11.10',
  rel: 'unicorn'

Note: Amazon uses branches of cookbooks to correspond to releases of Chef. You will need to look on GitHub to find the appropriate branch and update it above.

However, there is a critical caching bug that I have yet to fix, so the git repo is not cached, meaning you could be doing a lot of downloading. Therefore I recommend the latter approach.

Option #2: :path

  1. Clone the entire monolithic repo onto your local machine:

    git clone git://
  2. Create a DSL method at the top of your Berksfile:

    def opsworks_cookbook(name, version = '>= 0.0.0', options = {})
      cookbook name, version, { path: "/path/to/repo/#{name}" }.merge(options)
  3. Use this DSL method for opsworks cookbooks:

    opsworks_cookbook 'unicorn'
    opsworks_cookbook 'rails'

I hope this approach alleviates some pain. It is worth noting, Berkshelf requires the presence of a metadata.rb to parse a cookbook's metadata. At the time of this writing, there are several cookbooks in Amazon's repository that do not have metadata definitions and therefore are unusable with Berkshelf.

About Seth

Seth Vargo is an engineer at Google. Previously he worked at HashiCorp, Chef Software, CustomInk, and some Pittsburgh-based startups. He is the author of Learning Chef and is passionate about reducing inequality in technology. When he is not writing, working on open source, teaching, or speaking at conferences, Seth advises non-profits.