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 ea7e4eb
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 82 deletions.
144 changes: 62 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,88 +1,76 @@
# 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/cloudetc/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/) declared via a filter in a YAML file
(see example snippets of a [filter.yml](#filter) below).

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.8.0:

```bash
# install it into ./bin/
curl -sSfL https://raw.githubusercontent.com/cloudetc/awsweeper/master/install.sh | sh -s v0.6.0
curl -sSfL https://raw.githubusercontent.com/cloudetc/awsweeper/master/install.sh | sh -s v0.8.0
```

## Usage

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

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

## Filtering
## Filter

Delete resources via a filter declared in a YAML file.

Resources to be deleted are filtered by a yaml configuration. To learn how, have a look at the following example:
The following filter deletes all EC2 instances that ID matches `^foo.*` and that have been created between
`2018-10-28 12:28:39` and `2018-06-14` UTC (instance filter part 1); additionally, EC2 instances with tag
`foo: bar` *AND* not a tag key `owner` (instance filter part 2) are deleted; finally, also 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
after: 2018-10-28 12:28:39
# 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 filter syntax is as follows:

<resource type>:
# filter 1
- id: <regex to filter by id> | NOT(<regex to filter by id>)
tagged: bool (optional)
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,51 +80,43 @@ 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 various 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 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. Contrary, 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 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).
To see what the ID of a resource is (could be its 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 config file.

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

Expand Down Expand Up @@ -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 ea7e4eb

Please sign in to comment.