retention - Provides utilities to interact with Retention Policy feature.

Synopsis

gsutil retention set <retention_period> bucket_url...

gsutil retention clear bucket_url...

gsutil retention get bucket_url...

gsutil retention lock bucket_url...

gsutil retention event-default <set|release> bucket_url...

gsutil retention event <set|release> object_url...

gsutil retention temp <set|release> object_url...

Description

Set

The "gsutil retention set" command will allow you to set or update the Retention Policy on one or more buckets.

If you would like to remove an unlocked Retention Policy from one or more buckets, use the "gsutil retention clear" command.

The "set" sub-command can set retention policy with the following formats:

Set Formats

Formats for the "set" subcommand include:

<number>s
Specifies retention period of <number> seconds for objects in this bucket.
<number>d
Specifies retention period of <number> days for objects in this bucket.
<number>m
Specifies retention period of <number> months for objects in this bucket.
<number>y
Specifies retention period of <number> years for objects in this bucket.

Cloud Storage JSON API accepts retention period as number of seconds. Durations provided in terms of days, months or years will be converted to their rough equivalent values in seconds, using the following conversions:

  • A month is considered to be 31 days or 2,678,400 seconds.
  • A year is considered to be 365.25 days or 31,557,600 seconds.

For more information, see the Bucket Lock documentation.

Provided retention period must be greater than 0 and less than 100 years. Clients may define retention duration only in one form (seconds, days, months, or years) and not a combination of them.

It is important to note that, while it is possible to specify durations shorter than a day (using seconds), enforcement of such retentions is not guaranteed. Such durations may only be used for testing purposes.

Examples

Setting Retention Policy with duration of 1 year on a bucket:

gsutil retention set 1y gs://my-bucket

Setting Retention Policy with duration of 36 months on a bucket:

gsutil retention set 36m gs://some-bucket

You can also provide a precondition on a bucket's meta-generation in order to avoid potential race conditions. You can use gsutil's '-h' option to specify preconditions. For example, the following specifies a precondition that checks a bucket's metageneration before setting the Retention Policy on the bucket:

gsutil -h "x-goog-if-metageneration-match: 1" \
  retention set 1y gs://my-bucket

Clear

The "gsutil retention clear" command removes an unlocked Retention Policy from one or more buckets. A locked Retention Policy cannot be removed or reduced in duration.

Examples

Clearing Retention Policy (that has not yet been locked) on a bucket:

gsutil retention clear gs://my-bucket

Get

The "gsutil retention get" command retrieves the Retention Policy for given bucket and displays a human-readable representation of the configuration.

Lock

The "gsutil retention lock" command will PERMANENTLY lock unlocked Retention Policy on one or more buckets.

Caution: A locked Retention Policy cannot be removed from a bucket or reduced in duration. Once locked, deleting the bucket is the only way to "remove" a Retention Policy.

Event-Default

The "gsutil retention event-default" command sets the default value for an Event-Based Hold on one or more buckets.

By setting the default Event-Based Hold on a bucket, newly created objects will inherit that value as their Event-Based Hold (it is not applied retroactively).

Examples

Setting the default Event-Based Hold on a bucket:

gsutil retention event-default set gs://my-bucket

Releasing the default Event-Based Hold on a bucket:

gsutil retention event-default release gs://my-bucket

You can also provide a precondition on a bucket's meta-generation in order to avoid potential race conditions. You can use gsutil's '-h' option to specify preconditions. For example, the following specifies a precondition that checks a bucket's metageneration before setting the Retention Policy on the bucket:

gsutil -h "x-goog-if-metageneration-match: 1" \
  retention event-default set gs://my-bucket

Event

The "gsutil retention event" command will enable or disable a Event-Based Hold on an object.

Examples

Setting the Event-Based Hold on object(s):

gsutil retention event set gs://my-bucket/my-object

Releasing the Event-Based Hold on object(s):

gsutil retention event release gs://my-bucket/my-object

You can also provide a precondition on an object's meta-generation in order to avoid potential race conditions. You can use gsutil's '-h' option to specify preconditions. For example, the following specifies a precondition that checks an object's metageneration before setting the Event-Based hold on the object:

gsutil -h "x-goog-if-metageneration-match: 1" \
  retention event set gs://my-bucket/my-object

If you want to (un)set an Event-Based Hold on a large number of objects, then you might want to use the top-level '-m' option to perform a parallel update. For example, the following command sets an Event-Based Hold on objects ending with .jpg in parallel, in the root folder:

gsutil -m retention event set gs://my-bucket/*.jpg

Temp

The "gsutil retention temp" command will enable or disable a Temporary Hold on an object.

Examples

Setting the Temporary Hold on object(s):

gsutil retention temp set gs://my-bucket/my-object

Releasing the Temporary Hold on object(s):

gsutil retention temp release gs://my-bucket/my-object

You can also provide a precondition on an object's meta-generation in order to avoid potential race conditions. You can use gsutil's '-h' option to specify preconditions. For example, the following specifies a precondition that checks an object's metageneration before setting the Event-Based hold on the object:

gsutil -h "x-goog-if-metageneration-match: 1" \
  retention temp set gs://my-bucket/my-object

If you want to (un)set a Temporary Hold on a large number of objects, then you might want to use the top-level '-m' option to perform a parallel update. For example, the following command sets a Temporary Hold on objects ending with .jpg in parallel, in the root folder:

gsutil -m retention temp set gs://bucket/*.jpg
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Storage
Need help? Visit our support page.