Description

Chef cookbook to install and enable chef-handler-sns: A simple Chef report handler that reports status of a Chef run through Amazon SNS. Includes IAM roles support.

Amazon SNS can send notifications by SMS, email, Amazon SQS queues or to any HTTP endpoint.

This cookbook has been tested to work with AWS OpsWorks.

Requirements

Cookbooks:

• xml
• chef_handler

Attributes

Recipes

chef_handler_sns::default

Installs and enables the Chef SNS Handler.

Resources

chef_handler_sns[topic_arn]

Installs and enables the Chef SNS handler.

chef_handler_sns Actions

• enable: Installs and enables the Chef Handler.

chef_handler_sns Parameters

AWS Credentials permissions

If you are using AWS IAM credentials or AWS IAM role credentials, they should have at least the following privileges:

{
  "Statement": [
    {
      "Sid": "Stmt1234",
      "Effect": "Allow",
      "Action": [
        "sns:Publish"
      ],
      "Resource": [
        "arn:aws:sns:us-east-1:12341234:MyTopicName"
      ]
    }
  ]
}

Usage Examples

Using Amazon IAM roles

Using chef_handler_sns cookbook with IAM roles is rather easy.

Including in a Cookbook Recipe

First, you need to include this cookbook as a dependency in your cookbook:

# metadata.rb
depends 'chef_handler_sns'

# in your recipe
node['chef_handler_sns']['topic_arn'] = 'arn:aws:sns:us-east-1:12341234:MyTopicName'
include_recipe 'chef_handler_sns::default'

Using the LWRP from a Cookbook Recipe

You can also use the chef_handler_sns LWRP directly instead of including the recipe:

# metadata.rb
depends 'chef_handler_sns'

# in your recipe
chef_handler_sns 'arn:aws:sns:us-east-1:12341234:MyTopicName'

Including in the Run List

To include this cookbook directly in your run list, you must set at least the topic_arn attribute:

{
  "name": "git.zuazo.org",
  [...]
  "normal": {
    "chef_handler_sns": {
      "topic_arn": "arn:aws:sns:us-east-1:12341234:MyTopicName"
    }
  },
  "run_list": [
    [...]
    "recipe[chef_handler_sns]"
  ]
}

Passing the AWS credentials (machines without IAM roles)

If you are using Amazon EC2 without IAM roles or machines from other providers outside AWS, you must set the AWS credentials: access_key and secret_key (and sometimes also token).

Using the LWRP from a Cookbook Recipe

# metadata.rb
depends 'chef_handler_sns'

# in your recipe
chef_handler_sns 'arn:aws:sns:us-east-1:12341234:MyTopicName' do
  access_key '***AMAZON-KEY***'
  secret_key '***AMAZON-SECRET***'
end

Installing old versions

If you are not using IAM roles and you don't need to use AWS security tokens, you can use old versions of chef-handler-sns (< 1.0.0). Those versions does not require nokogiri, so they have lighter dependencies and take less time to install.

chef_handler_sns 'arn:aws:sns:us-east-1:12341234:MyTopicName' do
  access_key '***AMAZON-KEY***'
  secret_key '***AMAZON-SECRET***'
  version '0.2.6'
end

Testing

See TESTING.md.

Contributing

Please do not hesitate to open an issue with any questions or problems.

See CONTRIBUTING.md.

TODO

See TODO.md.

License and Author

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.