Enable and use object retention configurations

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 Use IAM with buckets. For information about granting roles on projects, see Manage access to projects.

Enable object retentions for a bucket

Enabling object retentions is only supported as part of creating the bucket, and if object retention is enabled on a bucket, it cannot be disabled. Use the following instructions to enable object retentions for a bucket:

Console

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.

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 object retentions are enabled for a bucket:

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. Click the name of the bucket whose status you want to check.

3. Click the Protection tab.

4. 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

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the JSON API with a GET Bucket request that includes the objectRetention field:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=objectRetention"

   Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

XML API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the XML API with a GET Bucket request scoped to ?object-lock:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME?object-lock"

   Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. 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.

3. Navigate to the object, which might be located in a folder.

4. Click the name of the object.

   The Object details page opens, which displays object metadata.

5. In the Protection section, click the Edit icon () associated with From object retention configuration.

   The Edit retention pane opens.

6. In the Object retention configuration section, click Enabled or Disabled.

   1. 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.

7. 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

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. 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.

3. 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

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. 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.

3. 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.

View an object's retention configuration

To view what, if any, retention configuration is set on an object:

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. 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.

3. Navigate to the object, which might be located in a folder.

4. 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

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the JSON API with a GET Object request that includes the retention field:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/OBJECT_NAME?fields=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.

XML API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the XML API with a GET Object request scoped to ?retention:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?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.

What's next

• Learn more about retention configurations.
• Learn about other features that protect your Cloud Storage data.
• Learn about Object Lifecycle Management, which can automatically delete files once they reach their retention period.