Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@jckuester
jckuester committed May 10, 2020
1 parent 69ddf1b commit dcfbc0b
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 76 deletions.
132 changes: 56 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,33 @@
# AWSweeper

<p align="right">
<a href="https://github.com/cloudetc/awsweeper/releases/latest">
<img alt="Release" src="https://img.shields.io/github/release/cloudetc/awsweeper.svg?style=flat-square">
</a>
<a href="https://travis-ci.org/cloudetc/awsweeper">
<img alt="pipeline status" src="https://img.shields.io/travis/cloudetc/awsweeper/master.svg" />
</a>
<a href="https://goreportcard.com/report/github.com/cloudetc/awsweeper">
<img alt="Go Report" src="https://goreportcard.com/badge/github.com/cloudetc/awsweeper?style=flat-square" />
</a>
<a href="https://godoc.org/github.com/cloudetc/awsweeper">
<img alt="Go Doc" src="https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square" />
</a>
<a href="https://github.com/cloudetc/awsweeper/blob/master/LICENSE">
<img alt="Software License" src="https://img.shields.io/github/license/cloudetc/awsweeper.svg?style=flat-square" />
</a>
<p align="center">
<img alt="AWSweeper Logo" src="https://github.com/cloudetc/awsweeper/blob/master/img/logo.png" height="180" />
<h3 align="center">AWSweeper</h3>
<p align="center">A tool for cleaning your AWS account</p>
</p>

AWSweeper wipes out all (or parts) of the resources in your AWS account. Resources to be deleted can be filtered by their ID, tags or
creation date using [regular expressions](https://golang.org/pkg/regexp/syntax/) declared in a yaml file (see [config.yml](example/config.yml)).
---
[![Release](https://img.shields.io/github/release/awsweeper/awsweeper.svg?style=for-the-badge)](https://github.com/cloudetc/awsweeper/releases/latest)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge)](/LICENSE.md)
[![Travis](https://img.shields.io/travis/cloudetc/awsweeper/master.svg?style=for-the-badge)](https://travis-ci.org/cloudetc/awsweeper)
[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=for-the-badge)](http://godoc.org/github.com/cloudetc/awsweeper)

AWSweeper cleans out all (or part) of the resources in your AWS account. Resources can be deleted by type, ID, tags or
creation date using [regular expressions](https://golang.org/pkg/regexp/syntax/) provided via a filter in a YAML file
(see [filter.yml](example/config.yml)).

AWSweeper [can delete many](#supported-resources), but not all resources yet. Your help
supporting more resources is very much appreciated ([please read this issue](https://github.com/cloudetc/awsweeper/issues/21)
to see how easy it is). Note that AWSweeper is based on the cloud-agnostic Terraform API for deletion - so it's planned to support
deleting Azure and Google Cloud Platform resources soon, too.
to see how easy it is).

Happy erasing!

[![AWSweeper tutorial](img/asciinema-tutorial.gif)](https://asciinema.org/a/149097)

## Installation

It's recommended to install a specific version of awsweeper available on the
It's recommended to install a specific version of AWSweeper available on the
[releases page](https://github.com/cloudetc/awsweeper/releases).

Here is the recommended way to install awsweeper v0.6.0:
Here is the recommended way to install AWSweeper v0.6.0:

```bash
# install it into ./bin/
Expand All @@ -44,45 +36,41 @@ curl -sSfL https://raw.githubusercontent.com/cloudetc/awsweeper/master/install.s

## Usage

awsweeper [options] <config.yml>
awsweeper [options] <filter.yml>

To see options available run `awsweeper --help`.

## Filtering

Resources to be deleted are filtered by a yaml configuration. To learn how, have a look at the following example:
Delete resources via a filter provided in a YAML file.

The following filter deletes all EC2 instances that ID matches `^foo.*` and have been created between
`2018-10-28 12:28:39 +0000 UTC` and `2018-06-14` (instance filter part 1); additionally, instances with tag
`foo: bar` *AND* not a tag key `owner` (instance filter part 2); Furthermore, ALL security groups are deleted.

aws_instance:

# instance filter part 1
- id: ^foo.*
tags:
foo: bar
bla: blub
created:
before: 2018-06-14
after: 2018-10-28 12:28:39.0000
# instance filter part 2
- tags:
foo: bar
created:
before: 2018-06-14
- tags:
foo: NOT(bar)
created:
after: 2018-06-14
aws_iam_role:

This config would delete all instances which ID matches `^foo.*` *AND* which have tags `foo: bar` *AND* `bla: blub`
*AND* which have been created between `2018-10-28 12:28:39 +0000 UTC` and `2018-06-14`. Additionally, it would delete instances
with tag `foo: bar` and which are older than `2018-06-14`.

Furthermore, this config would delete all IAM roles, as there is no list of filters provided for this resource type.
NOT(owner): .*
aws_security_groups:

The general syntax of the filter config is as follows:
The general syntax of the filter is as follows:

<resource type>:
# filter 1
- id: <regex to filter by id> | NOT(<regex to filter by id>)
tagged: bool
tags:
<key>: <regex to filter value> | NOT(<regex to filter value>)
<key> | NOT(key): <regex to filter value> | NOT(<regex to filter value>)
...
created:
before: <timestamp> (optional)
Expand All @@ -92,52 +80,44 @@ The general syntax of the filter config is as follows:
<resource type>:
...

A more detailed description of the ways to filter resources:

##### 1) All resources of a particular type

[Terraform types](https://www.terraform.io/docs/providers/aws/index.html) are used to identify resources of a particular type
(e.g., `aws_security_group` selects all resources that are security groups, `aws_iam_role` all roles,
or `aws_instance` all EC2 instances).

In the example above, by simply adding `security_group:` (no further filters for IDs or tags),
all security groups in your account would be deleted. Use the [all.yml](./all.yml), to delete all (currently supported)
resources.
Here is a more detailed description of the ways to filter resources:

##### 2) By tags
##### 1) Delete all resources of a particular type

You can narrow down on particular types of resources by the tags they have.
[Terraform resource type indentifiers](https://www.terraform.io/docs/providers/aws/index.html) are used to delete
resources by type.

The following filter config deletes ALL security groups, IAM roles, and EC2 instances:

aws_security_group:
aws_iam_role:
aws_instance:

Don't forget the `:` at the end of each line.

If most of your resources have tags, this is probably the best to filter them
for deletion. But be aware: not all resources support tags and can be filtered this way.
##### 2) Delete by tags

In the example above, all EC2 instances are terminated that have a tag with key `foo` and value `bar` as well as
`bla` and value `blub`.
If most of your resources have tags, this is probably the best way to filter them
for deletion. **Be aware**: Not all resources [support tags](#supported-resources) yet and can be filtered this way.

The tag filter can be negated by surrounding the regex with `NOT(...)`

Resources not matching tag can be removed with Untagged: true
`tagged: false` deletes all resources that have no tags resources with any tags can be deleted with `tagged: true`.

The key and the value part of the tag filter can be negated by a surrounding `NOT(...)`. This allows for removing of
all resources not matching some tag key and.or value. In the example below, all EC2 instances without the `owner: me`
tag are deleted:

aws_instance:
- tags:
Persist: NOT(true)
created:
before: 1w
untagged: true

This allows for removing of all resources not matching tags to be deleted. In the above example all aws instances without the `Persist: true` tag that are older than 1 week will be deleted. *NOTE: Does not work with resources currently not supporting tags.*
NOT(Owner): me


##### 3) By ID
##### 3) Delete By ID

You can narrow down on particular types of resources by filtering on their IDs.

To see what the IDs of your resources are (could be their name, ARN, a random number),
run awsweeper in dry-run mode: `awsweeper --dry-run all.yml`. This way, nothing is deleted but
all the IDs and tags of your resources are printed. Then, use this information to create the yaml file.

In the example above, all roles which name starts with `foo` are deleted (the ID of roles is their name).

The id filter can be negated by surrounding the regex with `NOT(...)`

##### 4) By creation date
Expand All @@ -164,8 +144,8 @@ A more detailed description of the ways to filter resources:

## Dry-run mode

Use `awsweeper --dry-run <config.yml>` to only show what
would be deleted. This way, you can fine-tune your yaml configuration until it works the way you want it to.
Use `awsweeper --dry-run <filter.yml>` to only show what
would be deleted. This way, you can fine-tune your YAML filter configuration until it works the way you want it to.

## Supported resources

Expand Down
Binary file added img/logo.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit dcfbc0b

Please sign in to comment.