Setup

This page discusses the Bucket Lock feature, which lets you configure aCloud Storage bucket's retention policy. This policy governs how longobjects in the bucket must be retained. The feature also lets you lock thebucket's retention policy, permanently preventing the policy from beingreduced or removed.

This feature can provide immutable storage on Cloud Storage.In conjunction withDetailed audit logging mode, which logsCloud Storage request and response details, Bucket Lockcan help with regulatory and compliance requirements, such as thoseassociated with FINRA, SEC, and CFTC. Bucket Lock can also help you addresscertain health care industry retention regulations.

Overview

• You can add aretention policy to a bucket to specify aretention period.

  • When a bucket retention policy is set, objects in the bucket can only bedeleted or replaced once their age is greater than the retentionperiod.

  • The policy retroactively applies to existing objects in the bucket aswell as new objects added to the bucket. This differs from theObject Retention Lock feature, which lets you define dataretention requirements on a per-object basis.

• You canlock a bucket's retention policy topermanently set it on thebucket.

  • Once you lock a policy, you cannot remove it or reduce the retentionperiod it has.

  • You cannot delete a bucket with a locked policy unless every object in thebucket has met the retention period.

  • You can increase the retention period of a locked policy.

  Caution: Locking a bucket's retention policy is an irreversible action. Formore information, seeRetention policy locks.

Bucket retention policies

You can include a retention policy when creating a new bucket, or you canadd a retention policy to an existing bucket. Placing a retention policy ona bucket ensures that all current and future objects in the bucket cannot bedeleted or replaced until they reach the age you define in the policy. Attemptsto delete or replace objects whose age is less than the retention period failwith a403 - retentionPolicyNotMet error.

For example, say you have a bucket with two objects in it: Object A you addeda month ago, and Object B you added two years ago. If you apply a retentionpolicy to your bucket that has a retention period of 1 year, you cannot deleteor replace Object A for another 11 months: it is currently 1 month old, butmust be a least 1 year old to delete or replace. Object B, on the other hand,can be deleted or replaced immediately, since its age is greater than theretention period. If you decided to replace Object B, this new version ofObject B has an age that restarts at 0 years.

To help track when individual objects are eligible for deletion, objects in abucket with a retention policy each haveretention expiration time metadata.This piece of metadata shows the date and time when an object fulfills theretention period.

General considerations

When working with retention policies, keep in mind the following:

• Unless a bucket'sretention policy is locked, you canincrease, decrease, or remove the policy.

• An object'seditable metadata is not subject to a bucket's retentionpolicy and can be modified even when the object itself cannot be.

• A bucket's retention policy contains aneffective time, the time after whichall objects in the bucket are guaranteed to be in compliance with theretention period.

• To see the earliest date when a given object is eligible for deletion ina bucket with a retention policy, view theretention expiration dateportion of theobject's metadata.

Considerations with other features

The following are interactions that retention policies have withother Cloud Storage features:

• In buckets that useObject Versioning, a live object version that has aretention expiration date in the future can still be made noncurrent, andany versioned objects that exist in the bucket at the time you apply aretention policy are also protected by the policy.

• An object that is subject to anevent-based hold cannot be deleted whilethe hold applies to it. Once the event-based hold is removed from theobject,the object's retention period is reset.

• An individual object can be subject to the bucket's retention policy and toits own, individualretention configuration. If an object is subjectto both, it is retained until both retentions have been satisfied.

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

• You can useObject Lifecycle Management to automatically delete objectsin a bucket, including in a bucket with alocked policy.A lifecycle rule won't delete an object until after the objectfulfills the retention policy.

• You should not performparallel composite uploads if your buckethas a retention policy, because the component pieces cannot be deleteduntil each has met the bucket's minimum retention period.

• Attempting tocomplete an XML API multipart upload failsif the resulting object would overwrite an object that has not yetmet its retention period.

• You can use theretention policy constraint in yourorganization policies to require that bucket retention policies withspecific retention periods be included as part of creating a new bucket oras part of adding/updating the retention policy on an existing bucket.

Retention periods

Retention periods are measured in seconds; however, some tools, like theGoogle Cloud console and theGoogle Cloud CLI allow you to set and viewretention periods with other units of time for convenience. The followingconversions apply in such cases:

• A day is considered to be 86,400 seconds.
• A week is considered to be 7 days, which is 604,800 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).

gcloud CLI

For the gcloud CLI, you should specify the retention period usingthe following format:

P#Y#M#W#DT#H#M#S

In this format, each# represents an integer you specify, whichshould be followed by a unit of time. The unitsY,W,D,H, andSsignify years, weeks, days, hours, and seconds, respectively.M signifiesmonths when it comes afterP, whileM signifies minutes when it comes afterT.

You must include at least one integer-unit pair as part of your retentionperiod, but you can omit any integer-unit pairs that you don't need.

For example,P1DT720M sets a retention period of 1 day and 720 minutes(one and a half days).

Retention policy locks

When youlock a bucket's retention policy, you prevent the policy fromever being removed or the retention period from ever being reduced (althoughyou can still increase the retention period). If you try to remove or reducethe policy duration of a locked bucket, you get a400 BadRequestExceptionerror. Once a retention policy is locked, you cannot delete the bucket untilevery object in the bucket has met the retention period.

Locking a bucket's retention policy is irreversible, and you should befamiliar with the implications of doing so prior to using this feature. When youuse anunlocked policy, you have the ability to remove the policy, allowingyou to still delete objects when desired. When youlock a policy, you mustdelete the entire bucket in order to "remove" the policy. However, you can'tdelete the bucket if there are objects in it that haven't fulfilled theirretention period. Thus, to "remove" a locked policy, you have to wait untilevery object in the bucket has fulfilled its retention period, at which pointyou can delete the bucket.

Additionally, when you lock a retention policy, Cloud Storage automaticallyapplies alien to theprojects.delete permission for the project thatcontains the bucket. While in place, the lien prevents the project from beingdeleted. To delete the project, you must firstremove all such liens.Note that removing a lien requires theresourcemanager.projects.updateLienspermission, which is part of theroles/owner androles/resourcemanager.lienModifier roles.

For information on how locking a retention policy can help your data complywith record retention regulations,see the compliance page.

What's next

• Learn touse and lock retention policies.
• Learn aboutObject Retention Lock andobject holds, which provideways to protect individual objects from deletion.
• Learn aboutDetailed audit logging mode, which can also help withregulatory and compliance requirements.