Skip to content

Versioning

Keep earlier versions of a bucket's objects when they are overwritten or deleted, and list, read, restore and delete them.

Updated View as Markdown

With versioning enabled, a bucket keeps every version of its objects.

  • Overwriting an object adds a new version, which becomes the current one. The earlier versions stay.
  • Deleting an object adds a delete marker. The object no longer appears in listings and reads answer 404, while its versions stay.
  • Every version has a version ID. Standard S3 tools list, read, copy and delete versions by ID.

A bucket’s versioning is Off, Enabled or Suspended. Once enabled, it can be suspended but not turned off.

Status Writes Deletes
Off Replace the object Remove the object
Enabled Add a version Add a delete marker
Suspended Replace the version with ID null. Versions made while enabled stay Replace the version with ID null with a delete marker

Objects written before versioning was enabled have the version ID null.

Enable versioning

Changing a bucket’s versioning needs objects.buckets.update.

  1. Open the bucket and select Versioning.
  2. Select Enable.
  3. Select Enable versioning to confirm.

With ezgh 0.71.0 or later:

ezgh objects buckets settings my-bucket --versioning enabled
ezgh objects buckets get my-bucket
export AWS_PROFILE=ezgh

aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Enabled
aws s3api get-bucket-versioning --bucket my-bucket

See AWS CLI for the profile.

With the client from boto3:

s3.put_bucket_versioning(Bucket="my-bucket", VersioningConfiguration={"Status": "Enabled"})

status = s3.get_bucket_versioning(Bucket="my-bucket").get("Status")

The Terraform AWS provider’s aws_s3_bucket_versioning sets a bucket’s versioning:

provider "aws" {
  region     = "us-west-1"
  access_key = "oak_…"
  secret_key = "…"

  endpoints {
    s3 = "https://s3.us-west-1.ezghapps.com"
  }

  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_requesting_account_id  = true
  skip_region_validation      = true
}

resource "aws_s3_bucket_versioning" "my_bucket" {
  bucket = "my-bucket"

  versioning_configuration {
    status = "Enabled"
  }
}

PutBucketVersioning in the Object Storage API takes enabled or suspended. A bucket’s versioning is null until versioning is first enabled.

MFA Delete isn’t supported: a PutBucketVersioning that enables it answers NotImplemented.

List versions

Listing versions needs objects.objects.list.

In the console, open the bucket, select Objects and turn on Show versions. The list shows every version and delete marker under the current prefix. The current version of each object is marked Latest.

aws s3api list-object-versions --bucket my-bucket --prefix reports/

Versions holds the versions and DeleteMarkers the delete markers. IsLatest is true on the current one of each key.

pages = s3.get_paginator("list_object_versions").paginate(Bucket="my-bucket", Prefix="reports/")
for page in pages:
    for version in page.get("Versions", []):
        print(version["Key"], version["VersionId"], version["IsLatest"], version["Size"])
    for marker in page.get("DeleteMarkers", []):
        print(marker["Key"], marker["VersionId"], marker["IsLatest"], "delete marker")

ListObjectVersions in the Object Storage API.

Read a version

Reading a version needs objects.objects.download. In the console, select a version and then Download.

aws s3api get-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID" q3.pdf
aws s3api head-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID"
body = s3.get_object(Bucket="my-bucket", Key="reports/q3.pdf", VersionId=version_id)["Body"].read()

A version ID that names a delete marker, or no version, answers 404.

A read by version ID always needs credentials. Public-read buckets and CDN distributions serve current objects only, and answer 403 AccessDenied to a request with a versionId.

Restore an object

To restore a deleted object, delete its delete marker. The version before it becomes current again. Find the marker’s ID under DeleteMarkers in the version listing, with IsLatest true:

aws s3api delete-object --bucket my-bucket --key reports/q3.pdf --version-id "$MARKER_ID"

In the console, select the delete marker marked Latest in the versions list, then Delete.

To go back to an earlier version of an object that was overwritten, copy that version over the object. The copy becomes a new current version, and every earlier version stays:

aws s3api copy-object --bucket my-bucket --key reports/q3.pdf \
  --copy-source "my-bucket/reports/q3.pdf?versionId=$VERSION_ID"
s3.copy_object(
    Bucket="my-bucket",
    Key="reports/q3.pdf",
    CopySource={"Bucket": "my-bucket", "Key": "reports/q3.pdf", "VersionId": version_id},
)

Delete a version

Deleting a version needs objects.objects.delete.

aws s3api delete-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID"
s3.delete_object(Bucket="my-bucket", Key="reports/q3.pdf", VersionId=version_id)

DeleteObjects takes a VersionId for each key. In the console, select a version and then Delete.

A bucket must hold no versions and no delete markers to be deleted.

Suspend versioning

Suspending keeps every version there is. New writes and deletes no longer add versions: they replace the version with ID null.

Open the bucket, select Versioning, then Suspend.

ezgh objects buckets settings my-bucket --versioning suspended
aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Suspended

Enable versioning again the same way as the first time.

Storage and lifecycle

Every version counts toward your organization’s storage. A bucket’s usage counts objects including versions.

Lifecycle rules delete versions a number of days after a newer version replaces them, and remove delete markers that are the only version left of their object.

Supported S3 operations

Operation Notes
GetBucketVersioning, PutBucketVersioning Enabled and Suspended. MFA Delete answers NotImplemented
ListObjectVersions
GetObject, HeadObject versionId
DeleteObject, DeleteObjects versionId
CopyObject, UploadPartCopy versionId on the copy source

Conditional writes

Of concurrent conditional writes of one key, with If-None-Match or If-Match, one succeeds. The others answer 412, or 409 ConditionalRequestConflict while the first is still being written. Retry a 409.

Permissions

To You need
View a bucket’s versioning objects.buckets.get
Enable or suspend versioning objects.buckets.update
List versions and delete markers objects.objects.list
Read or copy from a version objects.objects.download
Delete a version or a delete marker objects.objects.delete

These apply to the console, the CLI, the API and S3 requests alike. See Permissions.

Trails

Trails records changes to a bucket’s versioning. It doesn’t record version listings, reads or deletes.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close