Object Lock: Retention

To protect your objects from getting deleted by accident, you can use the Object Lock options Legal Hold and Retention. For more information about the differences between both options, see the FAQ entry "What is the difference between versioning and object locking?".

This getting started focuses on retention. You have to enable object lock during Bucket creation. It is not possible to enable Object Lock on Buckets that were created without Object Lock.

The commands depend on the S3-compatible tool you're using. This getting started explains each step with example commands for the MinIO Client and the AWS CLI.

Create a new Bucket with object lock enabled
- MinIO Client
```
mc mb <alias_name>/<bucket_name> --with-lock --region fsn1
```
- AWS CLI
```
aws s3api create-bucket \
  --bucket <bucket_name> \
  --region fsn1 \
  --object-lock-enabled-for-bucket
```
  If this command fails, check the content of ~/.aws/config. If it includes the following lines, comment them out with a # symbol and try again:
```
#s3 =
#  addressing_style = virtual
```

Check the object lock status

MinIO Client
```
mc stat <alias_name>/<bucket_name>
```

AWS CLI

aws s3api get-object-lock-configuration --bucket <bucket_name>

Set retention

You can set the mode to: GOVERNANCE or COMPLIANCE

MinIO Client

Default for new objects in the Bucket:
```
mc retention set GOVERNANCE 30d --default <alias_name>/<bucket_name>
```
For an existing object:
```
mc retention set GOVERNANCE 30d <alias_name>/<bucket_name>/<object_name>
```
In both commands, you can either specify the number of days #d or the number of years #y of your choice.

AWS CLI

Default for new objects in the Bucket:

aws s3api put-object-lock-configuration --bucket <bucket_name> --object-lock-configuration \
  '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "GOVERNANCE", "Days": 30 }}}'

For an existing object:

aws s3api put-object-retention --bucket <bucket_name> --key <object_name> \
  --retention '{ "Mode": "GOVERNANCE", "RetainUntilDate": "2025-01-01T12:00:00.00Z" }'

In the first command, you can either specify the number of days "Days": # or the number of years "Years": # of your choice. In the second command, you have to specify the timestamp.

Check the object lock status

MinIO Client

Bucket default:

mc retention info --json --default <alias_name>/<bucket_name>

Object status:

mc retention info --json <alias_name>/<bucket_name>/<object_name>

AWS CLI

Bucket default:

aws s3api get-object-lock-configuration --bucket <bucket_name>

Object status:

aws s3api get-object-retention --bucket <bucket_name> --key <object_name>

Remove or reduce the retention period

Note that it is not possible to end "compliance mode" in advance.

MinIO Client

Remove default mode and time for new objects in the Bucket:

mc retention clear --default --json <alias_name>/<bucket_name>

For an existing object:

mc retention set GOVERNANCE "1d" --bypass <alias_name>/<bucket_name>/<object_name>

AWS CLI

Remove default mode and time for new objects in the Bucket:

aws s3api put-object-lock-configuration --bucket <bucket_name> --object-lock-configuration \
  '{ "ObjectLockEnabled": "Enabled" }'

For an existing object:

aws s3api put-object-retention --bucket <bucket_name> --key <object_name> \
  --retention '{ "Mode": "GOVERNANCE", "RetainUntilDate": "<current_timestamp>" }' \
  --bypass-governance

As long as the retention period hasn't ended, your objects should be save from getting deleted by accident.