Workflow

This gem makes a number of assumptions in order to enforce a specific workflow. First among them is the Opsworks stack naming convection. This will need to adhere to the following format:

PROJECT::ENV::REGION

If PROJECT will be comprised of multiple words, they should be joined with underscores, e.g.

my_awesome_rails_app::prod::us-east

So for example, if you have an Elastic cluster in dev and prod in us-east, and dev in us-west:

elastic::dev::us-east
elastic::dev::us-west
elastic::prod::us-east

The next workflow that must be conformed to is berkshelf management. In this context, that means a git repository that conforms to the following setup:

opsworks-project

Inside that repository, you will have branches that match each of your environments and regions.

So in our Elastic example, you would have the following setup:

• a git repository called opsworks-elastic
• branches in that repository called dev-us-east, dev-us-west and prod-us-east

In each of those branches, you should have the following:

• Berksfile
• stack.json (if you want to maintain the stack json using the opzworks json utility)

The Berksfile will look similar to the following. If you're familiar with Berkshelf, there's nothing new here:

source 'https://api.berkshelf.com'

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

# external
#
cookbook 'lvm',           '= 1.0.8'
cookbook 'sensu',         '= 2.10.0'
cookbook 'runit',         '= 1.5.10'
cookbook 'java',          '= 1.29.0'
cookbook 'nodejs',        '= 2.1.0'
cookbook 'elasticsearch', '= 0.3.13'
cookbook 'chef_handler',  '= 1.1.6'

# mapzen wrappers
#
cookbook 'mapzen_sensu_clients',  git: '[email protected]:mapzen/chef-mapzen_sensu_clients', tag: '0.12.0'
cookbook 'mapzen_elasticsearch',  git: '[email protected]:mapzen/chef-mapzen_elasticsearch', tag: '0.16.3'
cookbook 'mapzen_logstash',       git: '[email protected]:mapzen/chef-mapzen_logstash',      tag: '0.13.1'
cookbook 'mapzen_graphite',       git: '[email protected]:mapzen/chef-mapzen_graphite',      tag: '0.6.0'
cookbook 'mapzen_pelias',         git: '[email protected]:mapzen/chef-mapzen_pelias',        tag: '0.34.2'

If we placed that Berkshelf file in opsworks-elastic, in the prod-us-east branch, we would run opzworks berks elastic::prod::us-east, which would do the following:

• build the berkshelf locally
• push the resultant cookbook tarball to: s3://opzworks/elastic-prod-us-east/cookbooks.tgz
• run update_custom_cookbook on the stack (unless you pass the --no-update flag)

Note that if you want to update the dependencies defined in the Berksfile, you need to run with the -u flag. This behavior mimics that of the gem and berks commands. So for example if you have an existing Berksfile and Berksfile.lock that you've build previously, and you have updated a tag in Berksfile to reflect a change you want to push, you need to either run:

opzworks berks stack::env::region -u, which will update the lockfile to reflect both the change to the cookbook you've updated, as well as update any unpinned dependencies (so if, for example, your cookbook requires the python cookbook without specifying the version, and there is a newer version available, that will get pulled in).

or

opzworks berks stack::env::region -u -c [cookbook1] [cookbook2] ..., which will only update the cookbook(s) referenced.

Your stack should be configured to use a berkshelf from an S3 archive. The url will look as below:

https://s3.amazonaws.com/opzworks/elastic-prod-us-east/cookbooks.tgz

You'll need to set up an IAM user or users with permission to access the location.