{"id":21745182,"url":"https://github.com/zuazo/chef_handler_sns-cookbook","last_synced_at":"2025-08-22T23:07:28.272Z","repository":{"id":14215764,"uuid":"16922565","full_name":"zuazo/chef_handler_sns-cookbook","owner":"zuazo","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.","archived":false,"fork":false,"pushed_at":"2017-05-14T20:26:26.000Z","size":101,"stargazers_count":1,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T22:05:25.484Z","etag":null,"topics":["amazon","aws","chef","cookbook","devops","handler","sns"],"latest_commit_sha":null,"homepage":"https://supermarket.chef.io/cookbooks/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":"2014-02-17T18:40:41.000Z","updated_at":"2017-05-06T06:14:57.000Z","dependencies_parsed_at":"2022-09-18T21:38:49.755Z","dependency_job_id":null,"html_url":"https://github.com/zuazo/chef_handler_sns-cookbook","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef_handler_sns-cookbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef_handler_sns-cookbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef_handler_sns-cookbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuazo%2Fchef_handler_sns-cookbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zuazo","download_url":"https://codeload.github.com/zuazo/chef_handler_sns-cookbook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665742,"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","cookbook","devops","handler","sns"],"created_at":"2024-11-26T07:13:52.495Z","updated_at":"2025-04-13T05:12:30.712Z","avatar_url":"https://github.com/zuazo.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Description\n===========\n[![GitHub](http://img.shields.io/badge/github-zuazo/chef__handler__sns--cookbook-blue.svg?style=flat)](https://github.com/zuazo/chef_handler_sns-cookbook)\n[![License](https://img.shields.io/github/license/zuazo/chef_handler_sns-cookbook.svg?style=flat)](#license-and-author)\n\n[![Cookbook Version](https://img.shields.io/cookbook/v/chef_handler_sns.svg?style=flat)](https://supermarket.chef.io/cookbooks/chef_handler_sns)\n[![Dependency Status](http://img.shields.io/gemnasium/zuazo/chef_handler_sns-cookbook.svg?style=flat)](https://gemnasium.com/zuazo/chef_handler_sns-cookbook)\n[![Build Status](http://img.shields.io/travis/zuazo/chef_handler_sns-cookbook.svg?style=flat)](https://travis-ci.org/zuazo/chef_handler_sns-cookbook)\n\nChef cookbook to install and enable [chef-handler-sns](http://zuazo.github.io/chef-handler-sns/): A simple Chef report handler that reports status of a Chef run through [Amazon SNS](http://aws.amazon.com/sns/). Includes IAM roles support.\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\nThis cookbook has been tested to work with [AWS OpsWorks](http://aws.amazon.com//opsworks/).\n\nRequirements\n============\n\n## Supported Platforms\n\n* Amazon Linux\n* CentOS\n* Debian\n* Fedora\n* FreeBSD\n* openSUSE\n* Oracle Linux\n* RedHat\n* Scientific Linux\n* SUSE\n* Ubuntu\n\n## Required Cookbooks\n\n* [chef_handler](https://supermarket.chef.io/cookbooks/chef_handler)\n\n## Required Applications\n\n* Chef `12` or higher.\n* Ruby `2.3` or higher.\n\nAttributes\n==========\n\n| Attribute                                   | Default                               | Description                       |\n|:--------------------------------------------|:--------------------------------------|:----------------------------------|\n| `node['chef_handler_sns']['topic_arn']`     | *required*                            | AWS topic ARN name (required).\n| `node['chef_handler_sns']['access_key']`    | *calculated from ohai with IAM roles* | AWS access key (required, but will try to read it from ohai with IAM roles).\n| `node['chef_handler_sns']['secret_key']`    | *calculated from ohai with IAM roles* | AWS secret key (required, but will try to read it from ohai with IAM roles). We do not recomend using this attribute, it is better to use [the LWRP](#chef_handler_snstopic_arn).\n| `node['chef_handler_sns']['token']`         | *calculated from ohai with IAM roles* | AWS security token (read from ohai with IAM roles). Set to `false` to disable the token detected by ohai.\n| `node['chef_handler_sns']['region']`        | *calculated from ohai*                | AWS region.\n| `node['chef_handler_sns']['subject']`       | *calculated*                          | Message subject string in erubis format.\n| `node['chef_handler_sns']['body_template']` | *calculated*                          | Full path of an erubis template file to use for the message body.\n| `node['chef_handler_sns']['supports']`      | `{ 'exception' =\u003e true }`             | Type of Chef Handler to register as, ie `:report`, `:exception` or both.\n| `node['chef_handler_sns']['version']`       | *latest stable*                       | chef-handler-sns gem version to install.\n| `node['chef_handler_sns']['mirror_url']`    | `nil`                                 | chef-handler-sns mirror to download the gem from. For cases where you do not want to use RubyGems.\n\nRecipes\n=======\n\n## chef_handler_sns::default\n\nInstalls and enables the Chef SNS Handler.\n\nResources\n=========\n\n## chef_handler_sns[topic_arn]\n\nInstalls and enables the Chef SNS handler.\n\n### chef_handler_sns Actions\n\n* `enable`: Installs and enables the Chef Handler.\n\n### chef_handler_sns Parameters\n\n| Parameter     | Default                                     | Description                       |\n|:--------------|:--------------------------------------------|:----------------------------------|\n| topic_arn     | *resource name*                             | AWS topic ARN name (required).\n| access_key    | `node['chef_handler_sns']['access_key']`    | AWS access key (required, but will try to read it from ohai with IAM roles).\n| secret_key    | `node['chef_handler_sns']['secret_key']`    | AWS secret key (required, but will try to read it from ohai with IAM roles).\n| token         | `node['chef_handler_sns']['token']`         | AWS security token (read from ohai with IAM roles). Set to `false` to disable the token detected by ohai.\n| region        | `node['chef_handler_sns']['region']`        | AWS region.\n| subject       | `node['chef_handler_sns']['subject']`       | Message subject string in erubis format.\n| body_template | `node['chef_handler_sns']['body_template']` | Full path of an erubis template file to use for the message body.\n| supports      | `node['chef_handler_sns']['supports']`      | Type of Chef Handler to register as, ie `:report`, `:exception` or both.\n| version       | `node['chef_handler_sns']['version']`       | chef-handler-sns gem version to install.\n| mirror_url    | `node['chef_handler_sns']['mirror_url']`    | chef-handler-sns mirror to download the gem from. For cases where you do not want to use RubyGems.\n\nAWS Credentials Permissions\n===========================\n\nIf you are using AWS IAM credentials or AWS IAM role credentials, they should have at least the following privileges:\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Sid\": \"Stmt1234\",\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"sns:Publish\"\n      ],\n      \"Resource\": [\n        \"arn:aws:sns:us-east-1:12341234:MyTopicName\"\n      ]\n    }\n  ]\n}\n```\n\nUsage Examples\n==============\n\n## Using Amazon IAM roles\n\nUsing `chef_handler_sns` cookbook with IAM roles is rather easy.\n\n### Including in a Cookbook Recipe\n\nFirst, you need to include this cookbook as a dependency in your cookbook:\n\n```ruby\n# metadata.rb\ndepends 'chef_handler_sns'\n```\n\n```ruby\n# in your recipe\nnode['chef_handler_sns']['topic_arn'] = 'arn:aws:sns:us-east-1:12341234:MyTopicName'\ninclude_recipe 'chef_handler_sns::default'\n```\n\n### Using the LWRP from a Cookbook Recipe\n\nYou can also use the `chef_handler_sns` LWRP directly instead of including the recipe:\n\n```ruby\n# metadata.rb\ndepends 'chef_handler_sns'\n```\n\n```ruby\n# in your recipe\nchef_handler_sns 'arn:aws:sns:us-east-1:12341234:MyTopicName'\n```\n\n### Including in the Run List\n\nTo include this cookbook directly in your run list, you must set at least the `topic_arn` attribute:\n\n```json\n{\n  \"name\": \"git.zuazo.org\",\n  \"[...]\": \"[...]\",\n  \"normal\": {\n    \"chef_handler_sns\": {\n      \"topic_arn\": \"arn:aws:sns:us-east-1:12341234:MyTopicName\"\n    }\n  },\n  \"run_list\": [\n    \"recipe[chef_handler_sns]\",\n    \"[...]\"\n  ]\n}\n```\n\n## Passing the AWS credentials (machines without IAM roles)\n\nIf 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`).\n\n### Using the LWRP from a Cookbook Recipe\n\n```ruby\n# metadata.rb\ndepends 'chef_handler_sns'\n```\n\n```ruby\n# in your recipe\nchef_handler_sns 'arn:aws:sns:us-east-1:12341234:MyTopicName' do\n  access_key '***AMAZON-KEY***'\n  secret_key '***AMAZON-SECRET***'\nend\n```\n\n### Installing Old Versions\n\nIf you want to install `chef-handler-sns` gem versions older than version `2`, you can use previous cookbook versions:\n\n```ruby\n# Berksfile\n\ncookbook 'chef_handler_sns', '~\u003e 2.0'\n```\n\nTesting\n=======\n\nSee [TESTING.md](https://github.com/zuazo/chef_handler_sns-cookbook/blob/master/TESTING.md).\n\n## ChefSpec Matchers\n\n### chef_handler_sns(topic_arn)\n\nHelper method for locating a `chef_handler_sns` resource in the collection.\n\n```ruby\ntopic_arn = 'arn:aws:sns:us-east-1:12341234:MyTopicName'\nresource = chef_run.chef_handler_sns(topic_arn)\n\nexpect(resource).to notify('service[apache2]').to(:reload)\n```\n\n### enable_chef_handler_sns(topic_arn)\n\nAssert that the Chef run enables `chef_handler_sns`.\n\n```ruby\ntopic_arn = 'arn:aws:sns:us-east-1:12341234:MyTopicName'\n\nexpect(chef_run).to enable_chef_handler_sns(topic_arn)\n  .with_access_key('***AMAZON-KEY***')\n  .with_secret_key('***AMAZON-SECRET***')\n```\n\nContributing\n============\n\nPlease do not hesitate to [open an issue](https://github.com/zuazo/chef_handler_sns-cookbook/issues/new) with any questions or problems.\n\nSee [CONTRIBUTING.md](https://github.com/zuazo/chef_handler_sns-cookbook/blob/master/CONTRIBUTING.md).\n\nTODO\n====\n\nSee [TODO.md](https://github.com/zuazo/chef_handler_sns-cookbook/blob/master/TODO.md).\n\nLicense and Author\n==================\n\n|                      |                                          |\n|:---------------------|:-----------------------------------------|\n| **Author:**          | Xabier de Zuazo (\u003cxabier@zuazo.org\u003e)\n| **Copyright:**       | Copyright (c) 2015-2016, Xabier de Zuazo\n| **Copyright:**       | Copyright (c) 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fchef_handler_sns-cookbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuazo%2Fchef_handler_sns-cookbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuazo%2Fchef_handler_sns-cookbook/lists"}