Use object holds

Overview

You can help protect your Cloud Storage data from deletion or replacement by using object holds. These holds help you meet regulatory compliance or legal discovery requirements. You can apply event-based and temporary holds to individual objects. Additionally, you can configure buckets to apply event-based holds to new objects by default.

This page describes how to use object holds, including placing holds by default on new objects and placing holds on individual objects.

Required permissions

Before using this feature in Cloud Storage, you must have sufficient permission to view and update buckets and objects in Cloud Storage:

  • If you own the project that contains the bucket, you most likely have the necessary permissions.

  • If you use IAM, you should have storage.buckets.update, storage.buckets.get, storage.objects.update, and storage.objects.get permissions on the relevant bucket. See Using IAM Permissions for instructions on how to get a role, such as Storage Admin, that has these permissions.

  • If you use ACLs, you should have OWNER permission on the relevant bucket and on the objects within it. See Setting ACLs for instructions on how to do this.

Use the default event-based hold property

The following tasks show you how to set and view the default event-based hold property on a bucket. When this property is enabled, new objects added to the bucket automatically get an event-based hold placed on them.

Set the default event-based hold property

To enable or disable the default event-based hold property for a bucket:

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 you want to set the default event-based hold property for.

  3. Select the Protection tab near the top of the page.

    The current status for the bucket appears in the Default event-based hold option section.

  4. In the Default event-based hold option section, click the current status to change it.

    The status appears as either Enabled or Disabled.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.

Command line

Use the gcloud storage buckets update command with the appropriate flag:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Where:

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

  • FLAG is either --default-event-based-hold to enable default event-based object holds or --no-default-event-based-hold to disable them.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);
  if (!original) throw std::move