All Docs

Object Versioning

Enable and disable versioning, list versions, restore previous versions. Version lifecycle, MFA delete protection.

Object versioning keeps multiple versions of objects in a bucket. When enabled, overwrites and deletes create new versions or delete markers instead of permanently replacing or removing data. Use versioning for compliance, backup, and recovery from accidental changes.

Enable and Disable Versioning

Enable Versioning

aws s3api put-bucket-versioning \
  --bucket my-bucket \
  --versioning-configuration Status=Enabled \
  --endpoint-url https://storage.yourdomain.com

Once enabled, versioning can be suspended but not fully disabled while versions exist.

Suspend Versioning

New uploads will overwrite the current version (no new version created). Existing versions remain.

aws s3api put-bucket-versioning \
  --bucket my-bucket \
  --versioning-configuration Status=Suspended \
  --endpoint-url https://storage.yourdomain.com

Check Status

aws s3api get-bucket-versioning \
  --bucket my-bucket \
  --endpoint-url https://storage.yourdomain.com

Output:

{
  "Status": "Enabled",
  "MfaDelete": "Disabled"
}

How Versioning Works

Upload (PutObject)

  • Versioning Enabled — Each upload creates a new version with a unique VersionId
  • Versioning Suspended — Upload overwrites the current object; no new version

Delete (DeleteObject)

  • Versioning Enabled — Adds a delete marker as the latest version; previous versions remain
  • Versioning Suspended — Permanently deletes the object

GetObject (Default)

Without VersionId, GetObject returns the latest non-deleted version. If the latest is a delete marker, the request returns 404 Not Found.

Listing Versions

List All Versions

aws s3api list-object-versions \
  --bucket my-bucket \
  --prefix documents/ \
  --endpoint-url https://storage.yourdomain.com

Output includes:

  • Versions — Object versions with VersionId, LastModified, Size, IsLatest
  • DeleteMarkers — Delete markers (also have VersionId)

List with Pagination

aws s3api list-object-versions \
  --bucket my-bucket \
  --prefix documents/ \
  --max-keys 100 \
  --key-marker "documents/old.pdf" \
  --version-id-marker "previous_version_id" \
  --endpoint-url https://storage.yourdomain.com

Restoring Previous Versions

Copy Previous Version to Current

To “restore” a previous version, copy it over the current key (creates a new version):

# Get the version ID of the version you want to restore
VERSION_ID="abc123def456"

# Copy that version to the same key (overwrites "current" with a new version)
aws s3api copy-object \
  --bucket my-bucket \
  --copy-source "my-bucket/documents/report.pdf?versionId=$VERSION_ID" \
  --key documents/report.pdf \
  --endpoint-url https://storage.yourdomain.com

Download Specific Version

aws s3 cp "s3://my-bucket/documents/report.pdf?versionId=$VERSION_ID" ./report-restored.pdf \
  --endpoint-url https://storage.yourdomain.com

Remove Delete Marker (Undelete)

If the latest “version” is a delete marker, delete that marker to make the previous version current again:

aws s3api delete-object \
  --bucket my-bucket \
  --key documents/report.pdf \
  --version-id DELETE_MARKER_VERSION_ID \
  --endpoint-url https://storage.yourdomain.com

Version Lifecycle

Use lifecycle rules to manage old versions:

  • Transition — Move old versions to Infrequent Access or Glacier
  • Expiration — Permanently delete old versions or delete markers after N days

Example: Delete noncurrent versions after 90 days:

{
  "Rules": [
    {
      "ID": "ExpireOldVersions",
      "Status": "Enabled",
      "Filter": {},
      "NoncurrentVersionExpiration": { "NoncurrentDays": 90 }
    }
  ]
}

MFA Delete Protection

MFA Delete requires multi-factor authentication to permanently delete a version or change the bucket’s versioning state. This adds a layer of protection against accidental or malicious deletion.

Enable MFA Delete (if supported by your NFYio deployment):

aws s3api put-bucket-versioning \
  --bucket my-bucket \
  --versioning-configuration '{
    "Status": "Enabled",
    "MFADelete": "Enabled"
  }' \
  --mfa "arn:aws:iam::ACCOUNT:mfa/root-account-mfa-device 123456" \
  --endpoint-url https://storage.yourdomain.com

Once enabled, MFA Delete cannot be disabled. Deleting a version or changing versioning state requires the MFA code.

Best Practices

  • Enable versioning for critical buckets — Protects against accidental overwrites and deletes
  • Use lifecycle rules — Automate cleanup of old versions to control storage costs
  • Document restore procedures — Ensure your team knows how to restore from a previous version
  • Consider MFA Delete — For compliance-sensitive data, require MFA for permanent deletion

Next Steps

Edit this page on GitHub