Skip to main content
Send feedback
Enable and use object retention configurations Stay organized with collections
Save and categorize content based on your preferences.
Overview
This page describes how to use the Object Retention Lock feature, including
enabling it for a bucket and setting retention configurations for objects
within the bucket.
Required roles
To get the permissions that you need to enable the Object Retention Lock feature
for a bucket and set retention configurations on objects, ask your administrator
to grant you the Storage Admin ( roles/storage.admin
) IAM role
on the bucket or the project that contains the bucket. This predefined role
contains the permissions
required to set and manage retention configurations. To see the exact
permissions that are required, expand the Required permissions section:
Required permissions
storage.buckets.create
storage.buckets.enableObjectRetention
storage.buckets.get
storage.buckets.list
This permission is only required if you plan on using the
Google Cloud console to perform the instructions on this page.
storage.objects.get
storage.objects.list
This permission is only required if you plan on using the
Google Cloud console to perform the instructions on this page.
storage.objects.overrideUnlockedRetention
This permission is only required if you plan on locking or shortening
an existing retention configuration.
storage.objects.setRetention
storage.objects.update
You might also be able to get these permissions with custom roles
.
For information about granting roles on buckets, see Set and manage IAM policies on buckets
. For information about granting
roles on projects, see Manage access to projects
.
Enable object retentions for a bucket
Important: Once the ability to set object retention configurations is enabled
on a bucket, it cannot be disabled.
Use the following instructions to allow retention configurations for objects in
a bucket. If you want to enable object retention configurations for an existing
bucket, you must follow the Google Cloud console instructions.
Console
To enable object retention configurations for a new bucket :
Create a bucket
as you normally would, and in the Choose how to
protect object data step, select Retention (For compliance) followed by Enable object retention .
To enable object retention configurations for an existing bucket :
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket for which you want
to enable object retentions.
Select the Protection tab near the top of the page.
The bucket's object retention status is displayed in the Object retention section.
In the Object retention section, click Object Retention Not Enabled .
In the dialog that appears, click Confirm .
Command line
Create a bucket
as you normally would, and include the --enable-per-object-retention
flag in the command.
REST APIs
JSON API
Create a bucket
as you normally would, and include the query
parameter enableObjectRetention=true
as part of the request.
XML API
Create a bucket
as you normally would, and include the header x-goog-bucket-object-lock-enabled: True
as part of the request.
View a bucket's object retention status
To see if retention configurations can be set for objects in a bucket:
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
Click the name of the bucket whose status you want to check.
Click the Protection tab.
The bucket's object retention status is displayed in the Object retention section.
Command line
Use the gcloud storage buckets describe
command with the --format
flag:
gcloud storage buckets describe gs:// BUCKET_NAME
--format="default(per_object_retention)"
Where BUCKET_NAME
is the name of the bucket
whose retention policy you want to view. For example, my-bucket
.
If successful and a retention policy exists for the bucket, the
response is similar to the following:
per_object_retention:
mode: Enabled
If successful and a retention policy does not exist for the bucket, the
response is similar to the following:
null
Client libraries
Rust
To view a bucket's object retention configuration, follow the instructions for displaying a bucket's metadata and look for
the object retention field in the response.
Set an object's retention configuration
Caution: Setting the mode of a retention configuration to Locked
( COMPLIANCE
in the XML API) is an irreversible action. If you do so: You cannot remove the retention configuration from the object.
You cannot decrease the retention time for the object.
In order to set a retention configuration for an object, the object must be
stored in a bucket for which object retentions are enabled
. To set a
retention configuration for an object:
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket that contains
the object whose retention configuration you want to set or modify.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which might be located in a folder.
Click the name of the object.
The Object details page opens, which displays object metadata.
In the Protection section, click the Edit icon
( edit
)
associated with From object retention configuration .
The Edit retention pane opens.
In the Object retention configuration section, click Enabled or Disabled .
If the retention configuration is enabled, select a date and time
for the configuration in the Retain until time section, and
click Unlocked or Locked in the Retention mode section.
Click Confirm .
Note: You can also set a retention configuration for an object at the time
the object is uploaded to the bucket. If the bucket you're uploading the
object to has the object retention feature enabled, a panel appears during
the upload that lets you specify a retention configuration for the object.
Command line
Use the gcloud storage objects update
command with the
appropriate flags. To add or modify a retention configuration, use the
following command. Note that you must additionally include the --override-unlocked-retention
flag if you are modifying an existing
configuration in a way that locks it or shortens its retain-until time:
gcloud storage objects update gs:// BUCKET_NAME
/ OBJECT_NAME
--retain-until= DATETIME
--retention-mode= STATE
Where:
BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
OBJECT_NAME
is the name of the relevant
object. For example, kitten.png
.
DATETIME
is the earliest date and time that
the object can be deleted. For example, 2028-02-15T05:30:00Z
.
STATE
is either Locked
or Unlocked
.
If successful, the response looks similar to the following example:
Updating gs://my-bucket/kitten.png...
Completed 1
To remove a retention configuration from an object, use the following
command:
gcloud storage objects update gs:// BUCKET_NAME
/ OBJECT_NAME
--clear-retention --override-unlocked-retention
Where:
BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
OBJECT_NAME
is the name of the relevant
object. For example, kitten.png
.
Note: You can also set a retention configuration for an object at the
time the object is written to the bucket. See command documentation,
such as gcloud storage cp
for more information.
REST APIs
JSON API
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Create a JSON file that contains the following information:
{
"retention"
:
{
"mode"
:
STATE
,
"retainUntilTime"
:
" DATETIME
" }
}
Where:
STATE
is either Locked
or Unlocked
.
DATETIME
is the earliest date and time
that the object can be deleted. For example, 2028-02-15T05:30:00Z
.
Use cURL
to call the JSON API with a PATCH
Object
request:
curl -X PATCH --data-binary @ JSON_FILE_NAME
\
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/o/ OBJECT_NAME
?overrideUnlockedRetention= BOOLEAN
"
Where:
JSON_FILE_NAME
is the path for the file
that you created in Step 2.
BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
OBJECT_NAME
is the URL-encoded name of the
relevant object. For example, pets/kitten.png
, URL-encoded as pets%2Fkitten.png
.
BOOLEAN
must be true
if the request
shortens, removes, or locks an existing retention configuration.
Otherwise, the overrideUnlockedRetention
parameter can be
excluded from the request entirely.
Note: You can also set a retention configuration for an object at the
time the object is written to the bucket. See request documentation,
such as Objects: Insert
for more information.
XML API
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Create an XML file that contains the following information:
<Retention>
<Mode> STATE
</Mode>
<RetainUntilDate> DATETIME
</RetainUntilDate>
</Retention>
Where:
STATE
is either GOVERNANCE
or COMPLIANCE
.
DATETIME
is the earliest date and time
that the object can be deleted. For example, 2028-02-15T05:30:00Z
.
Use cURL
to call the XML API with a PUT
Object
request scoped to ?retention
:
curl -X PUT --data-binary @ XML_FILE_NAME
\
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-bypass-governance-retention: BOOLEAN
" \
"https://storage.googleapis.com/ BUCKET_NAME
/ OBJECT_NAME
?retention"
Where:
XML_FILE_NAME
is the path for the XML
file that you created in Step 2.
BOOLEAN
must be true
if the request
shortens, removes, or locks an existing retention configuration.
Otherwise, the x-goog-bypass-governance-retention
header can be
excluded from the request entirely.
BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
OBJECT_NAME
is the URL-encoded name of the
relevant object. For example, pets/kitten.png
, URL-encoded as pets%2Fkitten.png
.
Note: You can also set a retention configuration for an object at the
time the object is written to the bucket. See request documentation,
such as PUT Object
for more information.
Set or update retention configurations in bulk
To set or update retention configurations for millions or billions of objects
with a single job, use storage batch operations
. To create a
job, specify the objects whose retention configuration you want to set or
update, either by providing a list of objects in a manifest file or by using
object prefixes. After you have specified the object list, create a
storage batch operations job
to set or update retention
configurations.
View an object's retention configuration
To view what, if any, retention configuration is set on an object:
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket that contains
the object whose retention configuration you want to view.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which might be located in a folder.
Click the name of the object.
The Object details page opens, which displays object metadata.
Information about any retention configuration the object has is shown
in the Protection section.
Command line
Use the gcloud storage objects describe
command with the --format
flag:
gcloud storage objects describe gs:// BUCKET_NAME
/ OBJECT_NAME
--format="default(retention_settings)"
Where:
BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
OBJECT_NAME
is the name of the relevant
object. For example, kitten.png
.
If successful and a retention configuration exists for the object, the
response is similar to the following:
retention_settings:
mode: Unlocked
retainUntilTime: '2028-11-30T14:11:14+00:00'
If successful and a retention configuration does not exist for the
object, the response is similar to the following:
null
Client libraries
Rust
To view an object's retention configuration, follow the instructions for displaying a object's metadata and look for
the retention field in the response.
What's next
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-05-29 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-05-29 UTC."],[],[]]
