{"id":13782123,"url":"https://github.com/zuazo/chef-handler-sns","last_synced_at":"2025-04-13T05:12:24.451Z","repository":{"id":6927608,"uuid":"8178748","full_name":"zuazo/chef-handler-sns","owner":"zuazo","description":"Chef report handler to send Amazon SNS notifications on failures or changes.","archived":false,"fork":false,"pushed_at":"2017-06-25T15:49:18.000Z","size":323,"stargazers_count":12,"open_issues_count":1,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-20T20:47:04.746Z","etag":null,"topics":["amazon","aws","chef","devops","handler","iam","sns"],"latest_commit_sha":null,"homepage":"http://zuazo.github.io/chef-handler-sns/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zuazo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-13T12:31:36.000Z","updated_at":"2018-07-07T04:29:32.000Z","dependencies_parsed_at":"2022-09-13T11:40:39.497Z","dependency_job_id":null,"html_url":"https://github.com/zuazo/chef-handler-sns","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef-handler-sns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef-handler-sns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef-handler-sns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef-handler-sns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zuazo","download_url":"https://codeload.github.com/zuazo/chef-handler-sns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665743,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","aws","chef","devops","handler","iam","sns"],"created_at":"2024-08-03T18:01:33.147Z","updated_at":"2025-04-13T05:12:24.422Z","avatar_url":"https://github.com/zuazo.png","language":"Ruby","readme":"# Chef Handler SNS\n[![Gem Version](http://img.shields.io/gem/v/chef-handler-sns.svg?style=flat)](http://badge.fury.io/rb/chef-handler-sns)\n[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg?style=flat)](http://www.rubydoc.info/gems/chef-handler-sns)\n[![GitHub](http://img.shields.io/badge/github-zuazo/chef--handler--sns-blue.svg?style=flat)](https://github.com/zuazo/chef-handler-sns)\n[![License](https://img.shields.io/github/license/zuazo/chef-handler-sns.svg?style=flat)](#license-and-author)\n\n[![Dependency Status](http://img.shields.io/gemnasium/zuazo/chef-handler-sns.svg?style=flat)](https://gemnasium.com/zuazo/chef-handler-sns)\n[![Code Climate](http://img.shields.io/codeclimate/github/zuazo/chef-handler-sns.svg?style=flat)](https://codeclimate.com/github/zuazo/chef-handler-sns)\n[![Build Status](http://img.shields.io/travis/zuazo/chef-handler-sns.svg?style=flat)](https://travis-ci.org/zuazo/chef-handler-sns)\n[![Coverage Status](http://img.shields.io/coveralls/zuazo/chef-handler-sns.svg?style=flat)](https://coveralls.io/r/zuazo/chef-handler-sns?branch=master)\n[![Inline docs](http://inch-ci.org/github/zuazo/chef-handler-sns.svg?branch=master\u0026style=flat)](http://inch-ci.org/github/zuazo/chef-handler-sns)\n\nA simple Chef report handler that reports status of a Chef run through [Amazon SNS](http://aws.amazon.com/sns/), [including IAM roles support](#usage-with-amazon-iam-roles).\n\n[Amazon SNS](http://aws.amazon.com/sns/) can send notifications by SMS, email, [Amazon SQS](http://aws.amazon.com/sqs/) queues or to any HTTP endpoint.\n\nWe recommend using the [`chef_handler_sns` cookbook](https://supermarket.chef.io/cookbooks/chef_handler_sns) for easy installation.\n\nThis Chef Handler is heavily based on [Joshua Timberman](https://github.com/jtimberman) examples.\n\n* https://docs.chef.io/handlers.html#exception-report-handlers\n\n## Requirements\n\n* Amazon AWS: uses Amazon SNS service.\n* Ruby `2` or higher (recommended `2.1` or higher).\n\n## Usage\n\nYou can install this handler in two ways:\n\n### Method 1: in the Chef Config File\n\nYou can install the RubyGem and configure Chef to use it:\n\n    $ gem install chef-handler-sns\n\nThen add to the configuration (`/etc/chef/solo.rb` for chef-solo or `/etc/chef/client.rb` for chef-client):\n\n```ruby\nrequire 'chef/handler/sns'\n\n# Create the handler\nsns_handler = Chef::Handler::Sns.new\n\n# Your Amazon AWS credentials\nsns_handler.access_key '***AMAZON-KEY***'\nsns_handler.secret_key '***AMAZON-SECRET***'\n\n# Some Amazon SNS configurations\nsns_handler.topic_arn 'arn:aws:sns:***'\nsns_handler.region 'us-east-1' # optional\n\n# Add your handler\nexception_handlers \u003c\u003c sns_handler\n```\n\n### Method 2: in a Recipe with the `chef_handler` LWRP\n\n**Note:** This method will not catch errors before the convergence phase. Use the previous method if you want to be able to report such errors.\n\nUse the [`chef_handler` LWRP](https://supermarket.chef.io/cookbooks/chef_handler), creating a recipe with the following:\n\n```ruby\n# Handler configuration options\nargument_array = [\n  access_key: '***AMAZON-KEY***',\n  secret_key: '***AMAZON-SECRET***',\n  topic_arn: 'arn:aws:sns:***'\n]\n\n# Install the `chef-handler-sns` RubyGem during the compile phase\nchef_gem 'chef-handler-sns' do\n  compile_time true # Only for Chef 12\nend\n\n# Then activate the handler with the `chef_handler` LWRP\nchef_handler 'Chef::Handler::Sns' do\n  source 'chef/handler/sns'\n  arguments argument_array\n  supports exception: true\n  action :enable\nend\n```\n\nSee the [`chef_handler_sns` cookbook provider code](https://github.com/zuazo/chef_handler_sns-cookbook/blob/master/providers/default.rb) for a more complete working example.\n\n### Method 3: Using the `chef-client` Cookbook\n\nYou can also use the `node['chef_client']['config']` attribute of the [`chef-client`](https://github.com/chef-cookbooks/chef-client/tree/v4.3.2#start-report-exception-handlers) cookbook:\n\n```ruby\nnode.default['chef_client']['config']['exception_handlers'] = [{\n  'class' =\u003e 'Chef::Handler::Sns',\n  'arguments' =\u003e {\n    access_key: '***AMAZON-KEY***',\n    secret_key: '***AMAZON-SECRET***',\n    topic_arn: 'arn:aws:sns:***'\n  }.map { |k, v| \"#{k}: #{v.inspect}\" }\n}]\n```\n\n### Usage with Amazon IAM Roles\n\nIf you are using AWS [IAM roles](http://docs.aws.amazon.com/IAM/latest/UserGuide/WorkingWithRoles.html) with your server, probably you only need to specify the `topic_arn` parameter. A few simple examples:\n\n#### IAM Roles Method 1: in the Chef Config File\n\nYou can install the RubyGem and configure Chef to use it:\n\n    $ gem install chef-handler-sns\n\nThen add to the configuration (`/etc/chef/solo.rb` for chef-solo or `/etc/chef/client.rb` for chef-client):\n\n```ruby\nrequire 'chef/handler/sns'\n\nexception_handlers \u003c\u003c Chef::Handler::Sns.new(\n  topic_arn: 'arn:aws:sns:us-east-1:12341234:MyTopicName'\n)\n```\n\n#### IAM Roles Method 2: in a Recipe with the `chef_handler` LWRP\n\nUse the [`chef_handler` LWRP](https://supermarket.chef.io/cookbooks/chef_handler), creating a recipe with the following:\n\n```ruby\n# Install the `chef-handler-sns` RubyGem during the compile phase\nchef_gem 'chef-handler-sns' do\n  compile_time true # Only for Chef 12\nend\n\n# Then activate the handler with the `chef_handler` LWRP\nchef_handler 'Chef::Handler::Sns' do\n  source 'chef/handler/sns'\n  arguments topic_arn: 'arn:aws:sns:us-east-1:12341234:MyTopicName'\n  supports exception: true\n  action :enable\nend\n```\n\n### IAM Roles Method 3: Using the `chef-client` Cookbook\n\nYou can also use the `node['chef_client']['config']` attribute of the [`chef-client`](https://github.com/chef-cookbooks/chef-client/tree/v4.3.2#start-report-exception-handlers) cookbook:\n\n```ruby\nnode.default['chef_client']['config']['exception_handlers'] = [{\n  'class' =\u003e 'Chef::Handler::Sns',\n  'arguments' =\u003e ['topic_arn: \"arn:aws:sns:***\"']\n}]\n```\n\n#### OpsWorks: Filter Notifications by Activity\n\nAn optional array of OpsWorks activities can be supplied. If the array is set, notifications will\nonly be triggered for the activities in the array, everything else will be discarded.\n\n```ruby\nargument_array = [\n  filter_opsworks_activities: %w(deploy configure)\n]\n```\n\n## Handler Configuration Options\n\nThe following options are available to configure the handler:\n\n* `access_key` - AWS access key (required, but will try to read it from Ohai with IAM roles).\n* `secret_key` - AWS secret key (required, but will try to read it from Ohai with IAM roles).\n* `token` - AWS security token (optional, read from Ohai with IAM roles). Set to `false` to disable the token detected by Ohai.\n* `topic_arn` - AWS topic ARN name (required).\n* `message_structure` - Set this option to `json` if you want to send a different message for each protocol. You must set your [message body template](#body_template-configuration-option) properly. Valid value: `json` (optional).\n* `region` - AWS region (optional).\n* `subject` - Message subject string in erubis format (optional).\n* `body_template` - Full path of an erubis template file to use for the message body (optional).\n* `filter_opsworks_activities` - An array of OpsWorks activities to be triggered with (optional). When set, everything else will be discarded.\n\n**Note:** When the machine has an IAM role, will try to read the credentials from Ohai. So in the best case, you only need to specify the `topic_arn`.\n\n### `subject` Configuration Option\n\nHere is an example of the `subject` configuration option using the ruby configuration file (`solo.rb` or `client.rb`):\n\n```ruby\nsns_handler.subject(\n  \"Chef-run: \u003c%= node.name %\u003e - \u003c%= run_status.success? ? 'ok' : 'error' %\u003e\"\n)\n```\n\nUsing the [`chef_handler` LWRP](https://supermarket.chef.io/cookbooks/chef_handler):\n\n```ruby\nargument_array = [\n  access_key: '***AMAZON-KEY***',\n  secret_key: '***AMAZON-SECRET***',\n  topic_arn: 'arn:aws:sns:***',\n  subject:\n    \"Chef-run: \u003c%= node.name %\u003e - \u003c%= run_status.success? ? 'ok' : 'error' %\u003e\"\n  # [...]\n]\n\nchef_handler 'Chef::Handler::Sns' do\n  # [...]\n  arguments argument_array\nend\n```\n\nThe following variables are accessible inside the template:\n\n* `start_time` - The time the chef run started.\n* `end_time` - The time the chef run ended.\n* `elapsed_time` - The time elapsed between the start and finish of the chef run.\n* `run_context` - The Chef::RunContext object used by the chef run.\n* `exception` - The uncaught Exception that terminated the chef run, or nil if the run completed successfully.\n* `backtrace` - The backtrace captured by the uncaught exception that terminated the chef run, or nil if the run completed successfully.\n* `node` - The Chef::Node for this client run.\n* `all_resources` - An Array containing all resources in the chef-run resource collection.\n* `updated_resources` - An Array containing all resources that were updated during the chef run.\n* `success?` - Was the chef run successful? True if the chef run did not raise an uncaught exception.\n* `failed?` - Did the chef run fail? True if the chef run raised an uncaught exception.\n\n### `body_template` Configuration Option\n\nThis configuration option needs to contain the full path of an Erubis template. For example:\n\n```ruby\n# recipe 'myapp::sns_handler'\n\ncookbook_file 'chef_handler_sns_body.erb' do\n  path '/tmp/chef_handler_sns_body.erb'\n  # [...]\nend\n\nargument_array = [\n  access_key: '***AMAZON-KEY***',\n  secret_key: '***AMAZON-SECRET***',\n  topic_arn: 'arn:aws:sns:***',\n  body_template: '/tmp/chef_handler_sns_body.erb'\n  # [...]\n]\n\nchef_handler 'Chef::Handler::Sns' do\n  # [...]\n  arguments argument_array\nend\n```\n\n```erb\n\u003c%# file 'myapp/files/default/chef_handler_sns_body.erb' %\u003e\n\nNode Name: \u003c%= node.name %\u003e\n\u003c% if node.attribute?('fqdn') -%\u003e\nHostname: \u003c%= node.fqdn %\u003e\n\u003c% end -%\u003e\n\nChef Run List: \u003c%= node.run_list.to_s %\u003e\nChef Environment: \u003c%= node.chef_environment %\u003e\n\n\u003c% if node.attribute?('ec2') -%\u003e\nInstance Id: \u003c%= node.ec2.instance_id %\u003e\nInstance Public Hostname: \u003c%= node.ec2.public_hostname %\u003e\nInstance Hostname: \u003c%= node.ec2.hostname %\u003e\nInstance Public IPv4: \u003c%= node.ec2.public_ipv4 %\u003e\nInstance Local IPv4: \u003c%= node.ec2.local_ipv4 %\u003e\n\u003c% end -%\u003e\n\nChef Client Elapsed Time: \u003c%= elapsed_time.to_s %\u003e\nChef Client Start Time: \u003c%= start_time.to_s %\u003e\nChef Client Start Time: \u003c%= end_time.to_s %\u003e\n\n\u003c% if exception -%\u003e\nException: \u003c%= run_status.formatted_exception %\u003e\nStacktrace:\n\u003c%= Array(backtrace).join(\"\\n\") %\u003e\n\n\u003c% end -%\u003e\n```\n\nSee the [subject](#subject) documentation for more details on the variables accessible inside the template.\n\nIf you set `message_structure` to `json`, the body template must:\n\n* be a syntactically valid JSON; and\n* contain at least a top-level JSON key of `default` with a value that is a string.\n\nYou can define other top-level keys that define the message you want to send to a specific transport protocol (e.g., \"http\").\n```erb\n\u003c%# file 'myapp/files/default/chef_handler_sns_body.erb' %\u003e\n{\n\"default\": \"Message body text here.\",\n\"email\": \"Message body text here.\",\n\"http\": \"Message body text here.\"\n}\n```\nSee the [AWS SNS](http://docs.aws.amazon.com/sns/latest/api/API_Publish.html#API_Publish_RequestParameters) documentation for more details on SNS message format.\n\n## IAM Role Credentials from Ohai\n\nIAM Role information and credentials are gathered from Ohai by default if they exists.\n\nNo aditional Ohai plugin is required. This is natively supported by Ohai since version `6.16.0` ([OHAI-400](https://tickets.opscode.com/browse/OHAI-400)).\n\nThese are the used Ohai attributes:\n\n```\nec2\n├── placement_availability_zone: region is set from here.\n└── iam\n    └── security-credentials\n        └── IAMRoleName\n            ├── AccessKeyId\n            ├── SecretAccessKey\n            └── Token\n```\n\n## Testing\n\nSee [TESTING.md](https://github.com/zuazo/chef-handler-sns/blob/master/TESTING.md).\n\n## Contributing\n\nPlease do not hesitate to [open an issue](https://github.com/zuazo/chef-handler-sns/issues/new) with any questions or problems.\n\nSee [CONTRIBUTING.md](https://github.com/zuazo/chef-handler-sns/blob/master/CONTRIBUTING.md).\n\n## TODO\n\nSee [TODO.md](https://github.com/zuazo/chef-handler-sns/blob/master/TODO.md).\n\n## License and Author\n\n|                      |                                          |\n|:---------------------|:-----------------------------------------|\n| **Author:**          | [Xabier de Zuazo](https://github.com/zuazo) (\u003cxabier@zuazo.org\u003e)\n| **Contributor:**     | [Florian Holzhauer](https://github.com/fh)\n| **Contributor:**     | [Michael Hobbs](https://github.com/michaelshobbs)\n| **Contributor:**     | [Hugo Lopes Tavares](https://github.com/hltbra)\n| **Contributor:**     | [Dmitry Averkiev](https://github.com/d-averkiev)\n| **Copyright:**       | Copyright (c) 2015 Xabier de Zuazo\n| **Copyright:**       | Copyright (c) 2013-2014 Onddo Labs, SL.\n| **License:**         | Apache License, Version 2.0\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n    \n        http://www.apache.org/licenses/LICENSE-2.0\n    \n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n    \n","funding_links":[],"categories":["Chef handlers"],"sub_categories":["Resources - Application configuration"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fchef-handler-sns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuazo%2Fchef-handler-sns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fchef-handler-sns/lists"}