{"id":29091693,"url":"https://github.com/eheydrick/aws-cleaner","last_synced_at":"2025-06-28T06:41:38.480Z","repository":{"id":29350093,"uuid":"32884285","full_name":"eheydrick/aws-cleaner","owner":"eheydrick","description":"Tool to remove nodes from Chef and Sensu when they are terminated in EC2","archived":false,"fork":false,"pushed_at":"2019-12-02T04:13:50.000Z","size":95,"stargazers_count":19,"open_issues_count":5,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-21T01:45:29.924Z","etag":null,"topics":["aws","chef","cloudwatch-events","ec2","sensu"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eheydrick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-25T18:50:23.000Z","updated_at":"2023-05-25T17:50:38.000Z","dependencies_parsed_at":"2022-07-24T16:17:23.128Z","dependency_job_id":null,"html_url":"https://github.com/eheydrick/aws-cleaner","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/eheydrick/aws-cleaner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eheydrick%2Faws-cleaner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eheydrick%2Faws-cleaner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eheydrick%2Faws-cleaner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eheydrick%2Faws-cleaner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eheydrick","download_url":"https://codeload.github.com/eheydrick/aws-cleaner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eheydrick%2Faws-cleaner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262388754,"owners_count":23303322,"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":["aws","chef","cloudwatch-events","ec2","sensu"],"created_at":"2025-06-28T06:41:32.688Z","updated_at":"2025-06-28T06:41:38.468Z","avatar_url":"https://github.com/eheydrick.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"## AWS Cleaner\n\n[![Build Status](https://travis-ci.org/eheydrick/aws-cleaner.svg?branch=master)](https://travis-ci.org/eheydrick/aws-cleaner)\n[![Gem Version](https://badge.fury.io/rb/aws-cleaner.svg)](http://badge.fury.io/rb/aws-cleaner)\n\nAWS Cleaner listens for EC2 termination events produced by AWS [CloudWatch Events](http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchEvents.html)\nand removes the instances from Chef. It can optionally remove the node from Sensu Monitoring (defaults true), fire off webhooks, and send notifications via Slack when actions occur.\n\n![aws-cleaner](https://raw.github.com/eheydrick/aws-cleaner/master/aws-cleaner.png)\n\n### Prerequisites\n\nYou will need to create a CloudWatch Events rule that's configured to send termination event messages to SQS.\n\n1. Create an SQS Queue for cloudwatch-events\n1. Goto CloudWatch Events in the AWS Console\n1. Click *Create rule*\n1. Select event source of *EC2 instance state change notification*\n1. Select specific state of *Terminated*\n1. Add a target of *SQS Queue* and set queue to the cloudwatch-events queue created in step one\n1. Give the rule a name/description and click *Create rule*\n\nYou will also need to create a user with the required permissions. I recommend creating a 'aws-cleaner' user in chef and add it to its own group. The minimum permissions we found that works is read and delete nodes/clients.\n\nSteps:\n\n1. on chef server: `chef-server-ctl user-create aws-cleaner AWS Cleaner`\n1. on chef server: `address@domain.tld \"$SOMEREALLYLONGRANDOMPASSWORD\" -f aws-cleaner.pem`\n1. on chef server: `chef-server-ctl org-user-add $MYORG aws-cleaner`\n1. on workstation: `gem install knife-acl`\n1. on workstation: `knife group create aws-cleaner`\n1. on workstation: `knife group add user aws-cleaner aws-cleaner`\n1. on workstation: `knife acl bulk add group aws-cleaner clients '.*' read,delete -y`\n1. on workstation: `knife acl bulk add group aws-cleaner nodes '.*' read,delete -y`\n\nAn astute reader might notice that this wont work for new nodes that come up as they have not had their ACL updated. I recommend that you add the who bulk acl knife commands (modified for just self as opposed to bulk) as part of your normal bootstrap process before deleting your validation key.\n\n### Installation\n\n1. `gem install aws-cleaner`\n\n### Usage\n\n```\nOptions:\n  -c, --config=\u003cs\u003e    Path to config file (default: config.yml)\n  -h, --help          Show this message\n```\n\nCopy the example config file ``config.yml.sample`` to ``config.yml``\nand fill in the configuration details. You will need AWS Credentials\nand are strongly encouraged to use an IAM user with access limited to\nthe AWS CloudWatch Events SQS queue.You will need to specify the region\nin the config even if you are using IAM Credentials.\n\nThe app takes one arg '-c' that points at the config file. If -c is\nomitted it will look for the config file in the current directory.\n\nThe app is started by running aws_config.rb and it will run until\nterminated. A production install would start it with upstart or\nsimilar.\n\n### Logging\n\nBy default aws-cleaner will log to STDOUT. If you wish to log to a specific file\nadd a `log` section to the config. See [`config.yml.sample`](config.yml.sample) for an example.\n\n### Webhooks\n\nAWS Cleaner can optionally make an HTTP request to a specified endpoint. You can\nalso template the URL that is called. Templating is currently limited to a single\nvariable and the value can be either the Chef node name or the FQDN of the instance.\n\nTo enable webhooks, add a `:webhooks:` section to the config:\n\n```\n:webhooks:\n  my-webhook:\n    :url: 'http://my.webhook.com/blah/{fqdn}'\n    :method: GET\n    :template_variables:\n      :variable: 'fqdn'\n      :method: 'get_chef_fqdn' (or 'get_chef_node_name')\n```\n\nChat notifications can be sent when the webhook successfully executes. See\nconfig.yml.sample for an example of the config.\n\n### Sensu\n\nBy default aws-cleaner assumes that removing from sensu is desired as this was one of its core intentions. To allow people to leverage this without sensu you can disable it via config:\n```\n:sensu:\n  :enable: false\n```\n\nWhen wanting to use sensu you will want the following config:\n```\n:sensu:\n  :url: 'http://sensu.example.com:4567'\n  :enable: true\n```\n\nWhile we currently assume sensu removal being desired is considered the default it may not always be so you should set `enable` to true to avoid a breaking change later.\n\n### Limitations\n\n- Currently only supports a single AWS region.\n- Only support chef and sensu with non self signed certificates. Look at Aws Certificate Manager or Let's Encrypt for free SSL certificates.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feheydrick%2Faws-cleaner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feheydrick%2Faws-cleaner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feheydrick%2Faws-cleaner/lists"}