Object Retention Lock

Setup

This page discusses the Object Retention Lock feature, which lets you set a retention configuration on objects within Cloud Storage buckets that have enabled the feature. A retention configuration governs how long the object must be retained and has the option to permanently prevent the retention time from being reduced or removed.

In conjunction with Detailed audit logging mode, which logs Cloud Storage request and response details, Object Retention Lock can help with regulatory and compliance requirements, such as those associated with FINRA, SEC, and CFTC. It can also help you address regulations in other industries such as health care.

Overview

Object Retention Lock lets you define data retention requirements on a per-object basis. This differs from Bucket Lock, which defines data retention requirements uniformly for all objects in a bucket. With Object Retention Lock, the retention configuration that you place on an object contains the following properties:

• A retain-until time that specifies a date and time until which the object must be retained. Prior to this time, the object cannot be deleted or replaced. Note that an object that hasn't reached this retain-until time can still be made noncurrent.

  • The retain-until time has a maximum value of 3,155,760,000 seconds (100 years) from the current date and time.

• A retention mode that controls what changes you can make to the retention configuration.

  • Unlocked allows authorized users to modify or remove an object's retention configuration without any limitations. In the XML API, this mode is named GOVERNANCE.

  • Locked permanently prevents the retention date from being reduced or removed. Once set to Locked, the mode cannot be changed, and the retention period can only be increased. In the XML API, this mode is named COMPLIANCE.

  • Locking a retention configuration can help your data comply with record retention regulations.

You can only set retention configurations on objects that reside in buckets that have enabled the feature.

• Existing buckets can only enable the feature using the Google Cloud console.

• Once enabled, the feature cannot be disabled on a bucket.

• After you enable the feature on a bucket, Cloud Storage applies a lien to the projects.delete permission for the project that contains the bucket, at best effort. To find out whether a lien has been applied, list all project liens.

  While in place, the lien prevents the project from being deleted. To delete the project, you must first remove the lien.

Considerations

• A bucket containing retained objects cannot be deleted until the retain-until time on all objects in the bucket has passed and all objects inside the bucket have been deleted.

• An object can be subject to both its own retention configuration and an overall bucket retention policy. If it is, the object is retained until both retentions that apply to it have been satisfied.

  • To see the earliest date that an object is eligible for deletion, view the retention expiration date metadata for the object.

• Requests that attempt to set a retention configuration on a object that is subject to an event-based hold fail.

  • Requests that would simultaneously set a retention configuration for an object and place an event-based hold on the object similarly fail.

  • An object can simultaneously have a retention configuration and a temporary hold.

• You cannot destroy Cloud Key Management Service key versions that encrypt locked objects if the objects haven't met their retention expiration times. For more information, see Key versions used to encrypt locked objects.

• You can use Object Lifecycle Management to automatically delete objects, but a lifecycle rule won't delete an object until after the object has reached its retention expiration date, even if the conditions of the lifecycle rule have been met.

• In buckets that use Object Versioning, a live object version that has a retain-until time in the future can still be made noncurrent.

• You shouldn't set retention configurations on objects that are meant to be temporary, such as component pieces of a parallel composite upload.

• An object's editable metadata is not subject to the retention configuration and can be modified even when the object itself cannot be.

What's next

• Use object retentions.
• Learn about other Cloud Storage features that protect objects and control their lifecycles.
• Learn about Detailed audit logging mode, which can also help with regulatory and compliance requirements.