Adde more documentation about IAM roles

README.md

@@ -1,6 +1,6 @@
 # Chef Handler SNS
 
-A simple Chef report handler that reports status of a Chef run through Amazon SNS.
+A simple Chef report handler that reports status of a Chef run through Amazon SNS, including IAM roles support.
 
 This Chef Handler is heavily based on [Joshua Timberman](https://github.com/jtimberman) examples.
 
@@ -109,6 +109,43 @@ chef_handler "Chef::Handler::Sns" do
 end
 ```
 
+### Usage with Amazon IAM roles
+
+If you are using AWS IAM roles with your server, probably you only need to specify the `topic_arn` parameter. A few simple examples:
+
+#### Method 1: In the Chef config file
+
+You can install the RubyGem and configure Chef to use it:
+
+    gem install chef-handler-sns
+
+Then add to the configuration (`/etc/chef/solo.rb` for chef-solo or `/etc/chef/client.rb` for chef-client):
+
+```ruby
+require "chef/handler/sns"
+
+exception_handlers << Chef::Handler::Sns.new({
+  :topic_arn => "arn:aws:sns:us-east-1:661624769153:TestChefHandlerSns"
+})
+```
+
+#### Method 2: In a recipe with the chef_handler LWRP
+
+Use the [chef_handler LWRP](http://community.opscode.com/cookbooks/chef_handler), creating a recipe with the following:
+
+```ruby
+# Install the `chef-handler-sns` RubyGem during the compile phase
+chef_gem "chef-handler-sns"
+
+# Then activate the handler with the `chef_handler` LWRP
+chef_handler "Chef::Handler::Sns" do
+  source "#{Gem::Specification.find_by_name("chef-handler-sns").lib_dirs_glob}/chef/handler/sns"
+  arguments { :topic_arn => "arn:aws:sns:***" }
+  supports :exception => true
+  action :enable
+end
+```
+
 ## Handler Configuration Options
 
 The following options are available to configure the handler:

chef-handler-sns.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.date = '2014-02-07'
   s.platform = Gem::Platform::RUBY
   s.summary = 'Chef SNS reports'
-  s.description = 'Chef report handler to send SNS notifications on failures or changes'
+  s.description = 'Chef report handler to send Amazon SNS notifications on failures or changes, includes IAM roles support'
   s.license = 'Apache-2.0'
   s.authors = ['Onddo Labs, SL.']
   s.email = 'team@onddo.com'