Table of Contents

S3 Object Versioning

Enable Versioning
Check Versioning Status
Suspend Versioning
List Object Versions
Access Specific Versions

Get a specific version of an object:
Copy a specific version:
Delete a specific version:

Versioning Behavior

When Versioning is Enabled:
When Versioning is Suspended:

Storage Layout
Limitations
Best Practices

S3 Object Versioning

SeaweedFS supports S3 object versioning, which allows you to keep multiple variants of an object in the same bucket. This provides data protection against accidental deletion or modification.

Enable Versioning

To enable versioning on a bucket, use the PutBucketVersioning API:

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

Check Versioning Status

To check the versioning status of a bucket:

aws s3api get-bucket-versioning --bucket my-bucket

Response:

{
    "Status": "Enabled"
}

Suspend Versioning

To suspend versioning (not disable completely):

aws s3api put-bucket-versioning \
    --bucket my-bucket \
    --versioning-configuration Status=Suspended

List Object Versions

To list all versions of objects in a bucket:

aws s3api list-object-versions --bucket my-bucket

Response includes both object versions and delete markers:

{
    "Versions": [
        {
            "Key": "example.txt",
            "VersionId": "v_1234567890abcdef",
            "IsLatest": true,
            "LastModified": "2023-12-01T10:00:00Z",
            "ETag": "\"abcdef1234567890\"",
            "Size": 1024
        }
    ],
    "DeleteMarkers": [
        {
            "Key": "deleted-file.txt",
            "VersionId": "v_fedcba0987654321",
            "IsLatest": true,
            "LastModified": "2023-12-01T11:00:00Z"
        }
    ]
}

Access Specific Versions

Get a specific version of an object:

aws s3api get-object \
    --bucket my-bucket \
    --key example.txt \
    --version-id v_1234567890abcdef \
    output.txt

Copy a specific version:

aws s3api copy-object \
    --copy-source my-bucket/example.txt?versionId=v_1234567890abcdef \
    --bucket my-bucket \
    --key example-copy.txt

Delete a specific version:

aws s3api delete-object \
    --bucket my-bucket \
    --key example.txt \
    --version-id v_1234567890abcdef

Versioning Behavior

When Versioning is Enabled:

PUT Object: Creates a new version with a unique version ID
GET Object: Returns the latest version (unless version ID is specified)
DELETE Object: Creates a delete marker (soft delete)
DELETE Object with version ID: Permanently deletes that specific version

When Versioning is Suspended:

PUT Object: Overwrites the object with version ID "null"
GET Object: Returns the current version
DELETE Object: Permanently deletes the object

Storage Layout

SeaweedFS stores versioned objects using the following structure:

/buckets/my-bucket/
├── example.txt          # Current version (if versioning suspended)
└── example.txt.versions/
    ├── v_1234567890abcdef  # Version 1
    ├── v_fedcba0987654321  # Version 2
    └── v_abcdef1234567890  # Version 3 (latest)

Limitations

Version ID Format: SeaweedFS generates version IDs in the format v_<32-char-hex>
Restore Operations: Only partial support for RestoreObject API
Lifecycle Policies: Version-specific lifecycle rules are not fully implemented
MFA Delete: Not currently supported

Best Practices

Enable versioning before storing important data to ensure all versions are captured
Monitor storage usage as versioning can increase storage consumption
Implement lifecycle policies to automatically clean up old versions
Use version-specific operations when you need to access historical data
Consider performance impact when listing many versions of objects

Introduction

API

Configuration

Filer

Filer Stores

Management

Advanced Filer Configurations

FUSE Mount

WebDAV

Cloud Drive

AWS S3 API

Server-Side Encryption

AWS IAM

Machine Learning

TensorFlow with SeaweedFS

HDFS

Replication and Backup

Async Replication to another Filer [Deprecated]
Async Backup
Async Filer Metadata Backup
Async Replication to Cloud [Deprecated]
Kubernetes Backups and Recovery with K8up