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. As mentioned in the list of supported actions, you have to enable object lock during Bucket creation.

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.

1. 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

2. Check the object lock status

   • MinIO Client

     mc stat <alias_name>/<bucket_name>

     
     

   • AWS CLI

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

3. 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.

4. 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>

5. 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

Your objects should now be save from getting deleted by accident.

Next:

• Object Lock: Legal Hold

• Versioning