Manage versioning in Bucket

By default, Object Storage Service does not provide backup capabilities. That means that if you delete an object incidentally, it is not possible to restore it.

Versioning means of keeping multiple variants of an object in the same Bucket. You can use the S3 Versioning feature to preserve, retrieve, and restore every version of every object stored in your Bucket.

With versioning you can recover more easily from both unintended user actions and application failures.

Versioning-enabled Buckets can help you recover objects from accidental deletion or overwrite. For example, if you delete an object, a delete marker is created instead of removing the object permanently.

The delete marker becomes the current object version. If you overwrite an object, it results in a new object version in the Bucket.

By default, S3 Versioning is disabled on buckets, and you must explicitly enable it. To manage Bucket and Object versioning, you can you can use the AWS CLI or any compatible tools or SDK.

Billing

You will be charged of space being used by older versions of your objects.

Limitation

We suggest keep the object version less than 50k. You can use a lifecycle configuration to delete versions of your objects.

Get current versioning state of a bucket

We use aws s3 and aws s3api command line tools from AWSCLIv2 on Linux.

${S3_ENDPOINT} and ${S3_PROFILE} are environment variables

If the versioning state has never been set on a Bucket, it has no versioning state. Using aws s3api AWS CLI, get-bucket-versioning, will return nothing:

aws s3api --endpoint-url=${S3_ENDPOINT} get-bucket-versioning --bucket my-bucket --profile ${S3_PROFILE}

For a Bucket with versioning enabled:

aws s3api --endpoint-url=${S3_ENDPOINT} get-bucket-versioning --bucket my-bucket --profile ${S3_PROFILE}

Output

{
    "Status": "Enabled"
}

For a Bucket with versioning suspended:

aws s3api --endpoint-url=${S3_ENDPOINT} get-bucket-versioning --bucket my-bucket --profile ${S3_PROFILE}

Output

{
    "Status": "Suspended"
}

Enable versioning on buckets

aws s3api --endpoint-url=${S3_ENDPOINT} put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Enabled --profile ${S3_PROFILE}

Suspend versioning on buckets

Once versioning enable on a bucket it can't be remove. But you have the possibility to suspend it.

aws s3api --endpoint-url=${S3_ENDPOINT} put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Suspended --profile ${S3_PROFILE}

Manage Objects versions

List Objects versions

You can use the list-object-versions from s3 api from AWSCLI:

aws --profile=${PROFILE} --endpoint ${S3_ENDPOINT} s3api list-object-versions --bucket my-bucket --prefix feather.ttf

Output

{
    "Versions": [
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427517621",
            "IsLatest": true,
            "LastModified": "2022-10-22T08:31:57.621Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        },
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427487088",
            "IsLatest": false,
            "LastModified": "2022-10-22T08:31:27.088Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        }
    ]
}

To get a specific version of an object using get-object and --version-id <Version ID>

aws --profile=${PROFILE} --endpoint ${S3_ENDPOINT} s3api get-object --bucket my-bucket --key feather.ttf --version-id 1666427487088 feather_1666427487088.ttf

Output

{
    "LastModified": "Sat, 22 Oct 2022 08:31:27 GMT",
    "ContentLength": 81512,
    "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
    "VersionId": "1666427487088",
    "ContentType": "font/ttf",
    "Metadata": {}
}

Delete an Object in a versioning Bucket

When you delete an object in a versioning Bucket, a delete marker is created and become the current version of the object:

aws --profile=${S3_PROFILE} --endpoint ${S3_ENDPOINT} s3api delete-object --bucket my-bucket --key feather.ttf

Output

{
    "DeleteMarker": true,
    "VersionId": "1666428023859"
}

aws --profile=${PROFILE} --endpoint ${S3_ENDPOINT} s3api list-object-versions --bucket my-bucket --prefix feather.ttf

Output

{
    "Versions": [
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427517621",
            "IsLatest": false,
            "LastModified": "2022-10-22T08:31:57.621Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        },
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427487088",
            "IsLatest": false,
            "LastModified": "2022-10-22T08:31:27.088Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        }
    ],
    "DeleteMarkers": [
        {
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            },
            "Key": "feather.ttf",
            "VersionId": "1666428023859",
            "IsLatest": true,
            "LastModified": "2022-10-22T08:40:23.859Z"
        }
    ]
}

Restore Objects

The delete marker has a version id too, you can delete it using its version ID in order to restore your object.

aws --profile=${S3_PROFILE} --endpoint ${S3_ENDPOINT} s3api delete-object --bucket my-bucket --key feather.ttf --version-id 1666428023859

Output

{
    "DeleteMarker": true,
    "VersionId": "1666428023859"
}

aws --profile=${PROFILE} --endpoint ${S3_ENDPOINT} s3api list-object-versions --bucket my-bucket --prefix feather.ttf

Output

{
    "Versions": [
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427517621",
            "IsLatest": true,
            "LastModified": "2022-10-22T08:31:57.621Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        },
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427487088",
            "IsLatest": false,
            "LastModified": "2022-10-22T08:31:27.088Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        }
    ]
}

Delete a specific version of an Object

You can delete a specific version on an object. If the specified version is not the current version, the object version is deleted and no delete marker is created.

aws --profile=${S3_PROFILE} --endpoint ${S3_ENDPOINT} s3api delete-object --bucket my-bucket --key feather.ttf --version-id 1666427487088

Output

{
    "VersionId": "1666427487088"
}

aws --profile=${PROFILE} --endpoint ${S3_ENDPOINT} s3api list-object-versions --bucket my-bucket --prefix feather.ttf

Output

{
    "Versions": [
        {
            "ETag": "\"2232dadea2f05fa28e3f08b5b3346df9\"",
            "Size": 81512,
            "StorageClass": "STANDARD",
            "Key": "feather.ttf",
            "VersionId": "1666427517621",
            "IsLatest": true,
            "LastModified": "2022-10-22T08:31:57.621Z",
            "Owner": {
                "DisplayName": "fwd37xbv8237hyhx2wkm",
                "ID": "fwd37xbv8237hyhx2wkm"
            }
        }
    ]
}