retention - Provides utilities to interact with Retention Policy feature.
Synopsis
gsutil retention set <retention_period> gs://<bucket_name>...
gsutil retention clear gs://<bucket_name>...
gsutil retention get gs://<bucket_name>...
gsutil retention lock gs://<bucket_name>...
gsutil retention event-default (set|release) gs://<bucket_name>...
gsutil retention event (set|release) gs://<bucket_name>/<object_name>...
gsutil retention temp (set|release) gs://<bucket_name>/<object_name>...
Description
Set
You can configure a data retention policy for a Cloud Storage bucket that governs how long objects in the bucket must be retained. You can also lock the data retention policy, permanently preventing the policy from being reduced or removed. For more information, see Bucket Lock.
The gsutil retention set
command allows you to set or update the
retention policy on one or more buckets.
To remove an unlocked retention policy from one or more
buckets, use the gsutil retention clear
command.
The set
sub-command can set a 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 periods as number of seconds. Durations provided in terms of days, months or years are 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.
Retention periods must be greater than 0 and less than 100 years. Retention durations must be in only one form (seconds, days, months, or years), and not a combination of them.
Note that while it is possible to specify retention durations shorter than a day (using seconds), enforcement of such retention periods is not guaranteed. Such durations may only be used for testing purposes.
Examples
Setting a retention policy with a duration of 1 year on a bucket:
gsutil retention set 1y gs://my-bucket
Setting a retention policy with a duration of 36 months on a bucket:
gsutil retention set 36m gs://some-bucket
You can also provide a precondition on a bucket's metageneration 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. You cannot remove or reduce the duration of a locked
retention policy.
Examples
Clearing an unlocked retention policy from a bucket:
gsutil retention clear gs://my-bucket
Get
The gsutil retention get
command retrieves the retention policy for a given
bucket and displays a human-readable representation of the configuration.
Lock
The gsutil retention lock
command PERMANENTLY locks an unlocked
retention policy on one or more buckets.
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 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 metageneration 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 default event-based hold on the bucket:
gsutil -h "x-goog-if-metageneration-match: 1" \
retention event-default set gs://my-bucket
Event
The gsutil retention event
command enables or disables an event-based
hold on an object.
Examples
Setting the event-based hold on an object:
gsutil retention event set gs://my-bucket/my-object
Releasing the event-based hold on an object:
gsutil retention event release gs://my-bucket/my-object
You can also provide a precondition on an object's metageneration 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 set or release 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 enables or disables a temporary hold
on an object.
Examples
Setting the temporary hold on an object:
gsutil retention temp set gs://my-bucket/my-object
Releasing the temporary hold on an object:
gsutil retention temp release gs://my-bucket/my-object
You can also provide a precondition on an object's metageneration 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 temporary hold on the object:
gsutil -h "x-goog-if-metageneration-match: 1" \
retention temp set gs://my-bucket/my-object
If you want to set or release 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