Versioning and object lock

Versioning

With versioning on, every upload to an existing key keeps the old file as a noncurrent version, and deleting a file adds a delete marker instead of removing data. You can list, download and restore any version.

Turn it on

Versioning needs an Admin key. Once on, it can be suspended but never turned fully off.

EP=https://s3.dockhive.io
aws s3api put-bucket-versioning --bucket my-app-uploads \
  --versioning-configuration Status=Enabled --endpoint-url $EP
aws s3api get-bucket-versioning --bucket my-app-uploads --endpoint-url $EP

Use Status=Suspended to stop creating new versions; existing versions are kept.

Work with versions

# List versions and delete markers, newest first
aws s3api list-object-versions --bucket my-app-uploads --prefix reports/ --endpoint-url $EP

# Download an old version
aws s3api get-object --bucket my-app-uploads --key reports/report.pdf \
  --version-id <version-id> old-report.pdf --endpoint-url $EP

# Restore it: copy the old version over the current one
aws s3api copy-object --bucket my-app-uploads --key reports/report.pdf \
  --copy-source "my-app-uploads/reports/report.pdf?versionId=<version-id>" --endpoint-url $EP

# Delete one version permanently (deleting a delete marker brings the file back)
aws s3api delete-object --bucket my-app-uploads --key reports/report.pdf \
  --version-id <version-id> --endpoint-url $EP

• GET and HEAD without a version id return the current version, or 404 NoSuchKey if the current version is a delete marker.
• Copy, tagging, ACL, retention and legal hold requests accept a versionId.
• Every stored version counts as storage, including noncurrent ones. Use a lifecycle rule to expire old versions automatically.
• A multipart upload gets its version when it starts: an upload started while versioning was on completes as a new version even if versioning was suspended in the meantime.

Object lock

Object lock makes versions impossible to delete or overwrite for a period (retention) or until you remove a legal hold. Use it for backups, audit logs and records you must keep.

Turn it on

Object lock needs versioning. Turn it on when you create the bucket, or later on a bucket with versioning Enabled. It can’t be turned off, and versioning can no longer be suspended.

# New bucket with object lock (needs an Admin key for all buckets)
aws s3api create-bucket --bucket my-backups --object-lock-enabled-for-bucket --endpoint-url $EP

# Default retention for new uploads: 30 days, governance mode
aws s3api put-object-lock-configuration --bucket my-backups --endpoint-url $EP \
  --object-lock-configuration '{"ObjectLockEnabled":"Enabled","Rule":{"DefaultRetention":{"Mode":"GOVERNANCE","Days":30}}}'

Retention modes

Mode	Who can shorten or remove it
GOVERNANCE	An Admin key of the bucket owner, by sending x-amz-bypass-governance-retention: true (--bypass-governance-retention in the CLI). Nobody else.
COMPLIANCE	Nobody, not even you. The retention can only be extended. Choose it only when you’re sure.

Set retention on one version, or when uploading:

aws s3api put-object-retention --bucket my-backups --key db/2026-10-11.sql.gz --endpoint-url $EP \
  --retention '{"Mode":"COMPLIANCE","RetainUntilDate":"2027-10-11T00:00:00Z"}'

aws s3api put-object --bucket my-backups --key db/today.sql.gz --body today.sql.gz --endpoint-url $EP \
  --object-lock-mode GOVERNANCE --object-lock-retain-until-date 2026-12-31T00:00:00Z

Legal hold

A legal hold blocks deletion of a version, with no end date, until it’s removed. It works independently of retention. Read & write keys can set and remove it.

aws s3api put-object-legal-hold --bucket my-backups --key db/2026-10-11.sql.gz \
  --legal-hold Status=ON --endpoint-url $EP
aws s3api put-object-legal-hold --bucket my-backups --key db/2026-10-11.sql.gz \
  --legal-hold Status=OFF --endpoint-url $EP

What’s enforced

• A locked version can’t be deleted or overwritten, by S3 tools, the console, the API or lifecycle rules. Deleting the bucket fails while it holds locked versions.
• Adding a delete marker is always allowed, so a “deleted” file disappears from listings but the locked version stays and can be restored.
• Locked versions are billed as storage until they can be deleted.
• MFA delete isn’t supported.