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.
- Open the bucket and select Versioning.
- Select Enable.
- 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-bucketexport AWS_PROFILE=ezgh
aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Enabled
aws s3api get-bucket-versioning --bucket my-bucketSee 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 suspendedaws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=SuspendedEnable 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.