This page discusses the Bucket Lock feature, which allows you to configure a data retention policy for a Cloud Storage bucket that governs how long objects in the bucket must be retained. The feature also allows you to lock the data retention policy, permanently preventing the policy from being reduced or removed.
This feature can provide immutable storage on Cloud Storage. Bucket Lock can help with regulatory and compliance requirements, such as those associated with FINRA, SEC, and CFTC. Bucket Lock may also help you address certain health care industry retention regulations.
You can add a retention policy to a bucket to specify a retention period.
If a bucket does not have a retention policy, you can delete or overwrite objects in the bucket at any time.
If a bucket has a retention policy, objects in the bucket can only be deleted or overwritten once their age is greater than the retention period.
A retention policy retroactively applies to existing objects in the bucket as well as new objects added to the bucket.
You can lock a retention policy to permanently set it on the bucket.
Once you lock a retention policy, you cannot remove it or reduce the retention period it has.
You cannot delete a bucket with a locked retention policy unless every object in the bucket has met the retention period.
You can increase the retention period of a locked retention policy.
Locking a retention policy can help your data comply with record retention regulations.
You can include a retention policy when creating a new bucket, or you can
add a retention policy to an existing bucket. Placing a retention policy on
a bucket ensures that all current and future objects in the bucket cannot be
deleted or overwritten until they reach the age you define in the retention
policy. Attempts to delete or overwrite objects whose age is less than the
retention period fail with a
403 - retentionPolicyNotMet error.
For example, say you have a bucket with two objects in it: Object A you added a month ago, and Object B you added two years ago. If you apply a retention policy to your bucket that has a retention period of 1 year, you cannot delete or overwrite Object A for another 11 months: it is currently 1 month old, but must be a least 1 year old to delete or overwrite. Object B, on the other hand, can be deleted or overwritten immediately, since its age is greater than the retention period. If you decided to overwrite Object B, this new version of Object B has an age that restarts at 0 years.
To help track when individual objects are eligible for deletion, objects in a bucket with a retention policy each have retention expiration time metadata. This piece of metadata shows the date and time when an object fulfills the retention period.
When working with retention policies, keep in mind the following:
Unless the retention policy is locked, you can increase, decrease, or remove the retention policy from a bucket.
Changing a retention policy is considered a single Class A operation, regardless of the number of objects affected.
An object's editable metadata is not subject to the retention policy and can be modified even when the object itself cannot be.
A retention policy contains an effective time, the time after which all objects in the bucket are guaranteed to be in compliance with the retention period.
To see the earliest date when a given object is eligible for deletion in a bucket with a retention policy, view the retention expiration date portion of the object's metadata.
Retention policies and Object Versioning are mutually exclusive features in Cloud Storage: for a given bucket, only one of these can be enabled at a time. Any versioned objects remaining in a bucket when you apply a retention policy are also protected by the retention policy.
You can use Object Lifecycle Management to automatically delete objects in a bucket, including in a bucket with a locked policy. A lifecycle rule won't delete an object until after the object fulfills the retention policy.
You should not perform parallel composite uploads if your bucket has a retention policy, because the component pieces cannot be deleted until each has met the bucket's minimum retention period.
You can use the retention policy constraint in your organization policies to require that retention policies with specific retention periods be included as part of creating a new bucket or as part of adding/updating the a retention policy on an existing bucket.
Retention periods are measured in seconds; however, some tools, like the Google Cloud Console and gsutil allow you to set and view retention periods with other units of time for convenience. The following conversions apply in such cases:
- A day is considered to be 86,400 seconds.
- A month is considered to be 31 days, which is 2,678,400 seconds.
- A year is considered to be 365.25 days, which is 31,557,600 seconds.
You can set a maximum retention period of 3,155,760,000 seconds (100 years).
For gsutil, when specifying a retention period, you use a
[UNIT] can be
y to signify seconds,
days, months, or years, respectively. Only one unit of time can be used in a command.
For example, you can use
1d, but you cannot use
Retention policy locks
When you lock a retention policy on a bucket, you prevent the policy from
ever being removed or the retention period from ever being reduced (although
you can still increase the retention period). If you try to remove or reduce
the policy duration of a locked bucket, you get a
error. Once a retention policy is locked, you cannot delete the bucket until
every object in the bucket has met the retention period.
Locking a retention policy is irreversible, and you should be familiar with the implications of doing so prior to using this feature. When you use an unlocked retention policy, you have the ability to remove the policy, allowing you to still delete objects when desired. When you lock a retention policy, you must delete the entire bucket in order to "remove" the policy. However, you can't delete the bucket if there are objects in it that haven't fulfilled their retention period. Thus, to "remove" a locked retention policy, you have to wait until every object in the bucket has fulfilled its retention period, at which point you can delete the bucket.
Additionally, when you lock a retention policy, Cloud Storage automatically
applies a lien to the
projects.delete permission for the project that
contains the bucket. While in place, the lien prevents the project from being
deleted. To delete the project, you must first remove all such liens.
Note that removing a lien requires the
permission, which is part of the
For information on how locking a retention policy can help your data comply with record retention regulations, see the compliance page.