s3undelete
This utility simplifies the process of undeleting a deleted file in a
versioned S3 bucket. When versioning is enabled on a
bucket, deleting a file actually creates a delete marker which effectively masks the previous versions. To undelete a
file, the delete marker iteself must be deleted.
As detailed in Deleting Object Versions,
you can use the console to see all versions, identify the delete maker and then remove it. Alternatively, you can make
a series of calls to the AWS API. These approaches are OK for a single file or possibly even a few, however when many
files need to be restored it would be too time consuming. s3undelete
was built to perform bulk undeletes for objects
deleted within a configurable time range, by default the last hour.
Installation
If you have installed Go, you can simply run this command
to install s3undelete
:
go get github.com/claranet/s3undelete/cmd/s3undelete
You can also download the latest x64 release.
Usage
AWS access is achieved using the default credential provider chain as part of the AWS SDK. As detailed in the
Specifying Credentials section of the
SDK documentation, credentials are sought in environment variables, the shared credentials file and finally the instance
profile if you are running within AWS. Please note that you will need to specify your region, for example with the
AWS_REGION
environment variable.
Example
Assuming you have got your AWS access keys,
you can export the three required environment variables and call s3undelete
. s3undelete
requires the -bucket
parameter with which you name the bucket you wish to undelete files in.
export AWS_ACCESS_KEY_ID=*****
export AWS_SECRET_ACCESS_KEY=*****
export AWS_REGION=eu-west-1
s3undelete -bucket my-versioned-bucket
Command line arguments
s3undelete
accepts the following command line arguments:
-
-age
duration
Maximum time since deletion, as a duration specification with a default
of an hour (1h
).
-
-bucket
string required
Target S3 bucket name.
-
-keys
int
Maximum number of keys per request (default 1024
)
Developing & Testing
Instead of using go get
, you can clone this repository and use the Makefile
. The following targets are available:
-
lint
Runs golint
across the source reporting any style mistakes. If not already installed locally, you can run
go get -u golang.org/x/lint/golint
to install.
-
build
Runs lint
and compiles the source to produce the s3undelete
binary in the local directory.
-
test
Runs build
then uses Terraform to create two buckets with 5 objects each, one with
versioning enabled and the other not. These objects are deleted and s3undelete
is then tested. Once the tests have
passed, the bucekts are destroyed. Terraform is configured in the same way as s3undelete
but requires additional IAM
permissions as detailed below.
-
install
default
Runs test
and copies the local s3undelete
to the user's $GOPATH/bin
folder.
-
clean
Removes the local s3undelete
if present and runs terraform destroy
to ensure the buckets have been removed.
IAM Permissions
The following IAM policy documents detail the minimum permissions required to execute s3undelete
and terraform
.
Minimum required permissions for s3undelete
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:DeleteObjectVersion"
],
"Resource": [
"arn:aws:s3:::YOUR-BUCKET-NAME/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:ListBucketVersions"
],
"Resource": [
"arn:aws:s3:::YOUR-BUCKET-NAME"
],
"Effect": "Allow"
}
]
}
Minimum required permissions for terraform
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:CreateBucket",
"s3:DeleteBucket",
"s3:DeleteObject",
"s3:DeleteObjectVersion",
"s3:Get*",
"s3:ListBucket",
"s3:ListBucketVersions",
"s3:PutBucketVersioning",
"s3:PutObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}