Implementing Recipes for Chef 11.10 Stacks

Chef 11.10 stacks provide the following advantages over Chef 11.4 stacks:

Cookbook Installation and Precedence

The procedure for installing AWS OpsWorks Stacks cookbooks works somewhat differently for Chef 11.10 stacks than for earlier Chef versions. For Chef 11.10 stacks, after AWS OpsWorks Stacks installs the built-in, custom, and Berkshelf cookbooks, it merges them to a common directory in the following order:

When AWS OpsWorks Stacks performs this merge, it copies the entire contents of the directories, including recipes. If there are any duplicates, the following rules apply:

To illustrate how this process works, consider the following scenario, where all three cookbook directories include a cookbook named mycookbook:

The merged cookbook contains the following:

Using Chef Search

You can use the Chef search Method in your recipes to query for stack data. You use the same syntax as you would for Chef server, but AWS OpsWorks Stacks obtains the data from the local node object instead of querying a Chef server. This data includes:

The stack configuration and deployment attributes contain most of the information that recipes typically obtain through search, including data such as host names and IP addresses for each online instance in the stack. AWS OpsWorks Stacks updates these attributes for each lifecycle event, which ensures that they accurately reflect the current stack state. This means that you can often use search-dependent community recipes in your stack without modification. The search method still returns the appropriate data; it's just coming from the stack configuration and deployment attributes instead of a server.

The primary limitation of AWS OpsWorks Stacks search is that handles only the data in the local node object, the stack configuration and deployment attributes in particular. For that reason, the following types of data might not be available through search:

The following recipe excerpt shows how to get the private IP address of a PHP layer's instance by using search.

appserver = search(:node, "role:php-app").first
Chef::Log.info("The private IP is '#{appserver[:private_ip]}'")

Using Data Bags

You can use the Chef data_bag_item method in your recipes to query for information in a data bag. You use the same syntax as you would for Chef server, but AWS OpsWorks Stacks obtains the data from the instance's stack configuration and deployment attributes. However, AWS OpsWorks Stacks does not currently support Chef environments, so node.chef_environment always returns _default.

You create a data bag by using custom JSON to add one or more attributes to the [:opsworks][:data_bags] attribute. The following example shows the general format for creating a data bag in custom JSON.

{
  "opsworks": {
    "data_bags": {
      "bag_name1": {
        "item_name1: {
          "key1" : “value1”,
          "key2" : “value2”,
          ...
        }
      },
      "bag_name2": {
        "item_name1": {
          "key1" : “value1”,
          "key2" : “value2”,
          ...
        }
      },
      ...
    }
  }
}

You typically specify custom JSON for the stack, which installs the custom attributes on every instance for each subsequent lifecycle event. You can also specify custom JSON when you deploy an app, but those attributes are installed only for that deployment, and might be installed to only a selected set of instances. For more information, see Deploying Apps.

The following custom JSON example creates data bag named myapp. It has one item, mysql, with two key-value pairs.

{ "opsworks": {
    "data_bags": {
      "myapp": {
        "mysql": { 
          "username": "default-user",
          "password": "default-pass"
        }
      }
    }
  }
}

To use the data in your recipe, you can call data_bag_item and pass it the data bag and value names, as shown in the following excerpt.

mything = data_bag_item("myapp", "mysql")
Chef::Log.info("The username is '#{mything['username']}' ")

To modify the data in the data bag, just modify the custom JSON, and it will be installed on the stack's instances for the next lifecycle event.

Using Berkshelf

With Chef 0.9 and Chef 11.4 stacks, you can install only one custom cookbook repository. With Chef 11.10 stacks, you can use Berkshelf to manage your cookbooks and their dependencies, which allows you to install cookbooks from multiple repositories. (For more information, see Packaging Cookbook Dependencies Locally.) In particular, with Berkshelf, you can install AWS OpsWorks Stacks-compatible community cookbooks directly from their repositories instead of having to copy them to your custom cookbook repository. The supported Berkshelf versions depend on the operating system. For more information, see AWS OpsWorks Stacks operating systems.

To use Berkshelf, you must explicitly enable it, as described in Installing Custom Cookbooks. Then, include a Berksfile file in your cookbook repository's root directory that specifies which cookbooks to install.

To specify an external cookbook source in a Berksfile, include a source attribute at the top of the file that specifies the default repository URL. Berkshelf will look for the cookbooks in the source URLs unless you explicitly specify a repository. Then include a line for each cookbook that you want to install in the following format:

cookbook 'cookbook_name', ['>= cookbook_version'], [cookbook_options]

The fields following cookbook specify the particular cookbook.

The following is an example of a Berksfile that shows different ways to specify cookbooks For more information on how to create a Berksfile, see Berkshelf.

source "https://supermarket.chef.io"

cookbook 'apt'
cookbook 'bluepill', '>= 2.3.1'
cookbook 'ark', git: 'git://github.com/opscode-cookbooks/ark.git'
cookbook 'build-essential', '>= 1.4.2', git: 'git://github.com/opscode-cookbooks/build-essential.git', tag: 'v1.4.2'

This file installs the following cookbooks:

A custom cookbook repository can contain custom cookbooks in addition to a Berksfile. In that case, AWS OpsWorks Stacks installs both sets of cookbooks, which means that an instance can have as many as three cookbook repositories.

The built-in cookbooks and your custom cookbooks are installed on each instance during setup and are not subsequently updated unless you manually run the Update Custom Cookbooks stack command. AWS OpsWorks Stacks runs berks install for every Chef run, so your Berkshelf cookbooks are updated for each lifecycle event, according to the following rules:

You can also update your Berkshelf cookbooks by running the Update Custom Cookbooks stack command, which updates both the Berkshelf cookbooks and your custom cookbooks.