Managing object lifecycles

Go to concepts

This page describes how to enable Object Lifecycle Management and gives examples of lifecycle policies.

Setting up lifecycle management on a bucket

Warning: When you change your lifecycle configuration, Object Lifecycle Management may still perform actions based on the old configuration for up to 24 hours. For example, if you change an Age condition from 10 days to 20 days, an object that is 11 days old could be deleted by Object Lifecycle Management up to 24 hours later, based on the old configuration.

Note: Support for this feature through the Java Google Cloud Client Library is currently limited to DeleteRules. Full Java support for this feature is available through the Google API Client Library for Java.

Enabling Lifecycle Management

To enable lifecycle management for a bucket:

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the bucket list, find the bucket you want to enable, and click None in the Lifecycle column.

   The lifecycle rules page appears.

3. Click Add rule.

4. In the page that appears, specify a configuration.

   1. Select the condition(s) under which an action is taken.

   2. Click Continue.

   3. Select the action to take when an object meets the condition(s).

   4. Click Continue.

   5. Click Save.

gsutil

1. Create a .json file with the lifecycle configuration rules you would like to apply (see examples).

2. Use the lifecycle set command to apply the configuration:

   gsutil lifecycle set [LIFECYCLE_CONFIG_FILE] gs://[BUCKET_NAME]

   Where:

   • [LIFECYCLE_CONFIG_FILE] is the name of the file you created in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

Code samples

C++

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

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name) {
  gcs::BucketLifecycle bucket_lifecycle_rules = gcs::BucketLifecycle{
      {gcs::LifecycleRule(gcs::LifecycleRule::ConditionConjunction(
                              gcs::LifecycleRule::MaxAge(30),
                              gcs::LifecycleRule::IsLive(true)),
                          gcs::LifecycleRule::Delete())}};

  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetLifecycle(bucket_lifecycle_rules));

  if (!updated_metadata) {
    throw std::runtime_error(updated_metadata.status().message());
  }

  if (!updated_metadata->has_lifecycle() ||
      updated_metadata->lifecycle().rule.empty()) {
    std::cout << "Bucket lifecycle management is not enabled for bucket "
              << updated_metadata->name() << ".\n";
    return;
  }
  std::cout << "Successfully enabled bucket lifecycle management for bucket "
            << updated_metadata->name() << ".\n";
  std::cout << "The bucket lifecycle rules are";
  for (auto const& kv : updated_metadata->lifecycle().rule) {
    std::cout << "\n " << kv.condition() << ", " << kv.action();
  }
  std::cout << "\n";
}

Java

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

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo.LifecycleRule;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.ImmutableList;

public class EnableLifecycleManagement {
  public static void enableLifecycleManagement(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);

    // See the LifecycleRule documentation for additional info on what you can do with lifecycle
    // management rules. This one deletes objects that are over 100 days old.
    // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/BucketInfo.LifecycleRule.html
    bucket
        .toBuilder()
        .setLifecycleRules(
            ImmutableList.of(
                new LifecycleRule(
                    LifecycleRule.LifecycleAction.newDeleteAction(),
                    LifecycleRule.LifecycleCondition.newBuilder().setAge(100).build())))
        .build()
        .update();

    System.out.println("Lifecycle management was enabled and configured for bucket " + bucketName);
  }
}

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file with the lifecycle configuration rules you would like to apply (see examples).

3. Use cURL to call the JSON API with a PATCH Bucket request:

   curl -X PATCH --data-binary @[LIFECYCLE_CONFIG_FILE].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=lifecycle"

   Where:

   • [LIFECYCLE_CONFIG_FILE] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

XML API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .xml file with the lifecycle configuration rules you would like to apply (see examples).

3. Use cURL to call the XML API with a PUT Bucket request:

   curl -X PUT --data-binary @[XML_FILE].xml \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?lifecycle"

   Where:

   • [XML_FILE] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

Disabling Lifecycle Management

To disable lifecycle management for a bucket:

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the bucket list, find the bucket you want to disable, and click Enabled in the Lifecycle column.

   The lifecycle rules page appears.

3. Click Delete all.

4. In the confirmation window that appears, click Delete.

Note: You can delete individual rules by clicking on the Trash icon associated with the rule you wish to delete.

gsutil

1. Create a .json file with an empty lifecycle configuration:

   {}

2. Use the lifecycle set command:

   gsutil lifecycle set [LIFECYCLE_CONFIG_FILE] gs://[BUCKET_NAME]

   Where:

   • [LIFECYCLE_CONFIG_FILE] is the name of the file you created in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file with an empty lifecycle configuration:

   {}

3. Use cURL to call the JSON API with a PATCH Bucket request:

   curl -X PATCH --data-binary @[LIFECYCLE_CONFIG_FILE].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=lifecycle"

   Where:

   • [LIFECYCLE_CONFIG_FILE] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

XML API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .xml file with an empty lifecycle configuration:

   <LifecycleConfiguration/>

3. Use cURL to call the XML API with a PUT Bucket request:

   curl -X PUT --data-binary @[XML_FILE].xml \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?lifecycle"

   Where:

   • [XML_FILE] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

Checking Lifecycle Configuration

To check the lifecycle configuration set on a bucket:

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the bucket list, the lifecycle status of each bucket is found in the Lifecycle column.

   You can click on this status to add, view, edit, and delete rules.

gsutil

1. Use the lifecycle get command:

   gsutil lifecycle get gs://[BUCKET_NAME]

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

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a GET Bucket request:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=lifecycle"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

XML API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the XML API with a GET Bucket request:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?lifecycle"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the relevant bucket. For example, my-bucket.

Object lifecycle configuration examples

The following examples show specific lifecycle configurations that accomplish deleting objects and changing the storage class of objects when common criteria are met. For a detailed discussion of lifecycle configurations, including a list of available actions and conditions, see Object Lifecycle Management.

Delete an object

The following lifecycle configuration defines two rules:

1. Delete live versions of objects older than 30 days. Note that all of your objects are considered live unless you use object versioning.
2. Delete noncurrent versions of objects older than 10 days. Note that this rule is only ever met for buckets where you have - or previously had - used object versioning.

Warning: Once an object is deleted, it cannot be undeleted. Take care in setting up your lifecycle rules so that you do not cause more data to be deleted than you intend. It is recommended that you test your lifecycle rules on development data before applying to production, and observe the expiration time metadata to ensure your rule has the effect you intend.

Console

The following rule deletes live versions of objects older than 30 days:

The following rule deletes noncurrent versions of objects older than 10 days:

gsutil

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

{
"lifecycle": {
  "rule": [
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 30,
      "isLive": true
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 10,
      "isLive": false
    }
  }
]
}
}

For the generalized format of a lifecycle configuration file, see the bucket resource representation for JSON.

REST APIs

JSON API

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

{
"lifecycle": {
  "rule": [
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 30,
      "isLive": true
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 10,
      "isLive": false
    }
  }
]
}
}

For the generalized format of a lifecycle configuration file, see the bucket resource representation for JSON.

XML API

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

<?xml version="1.0" encoding="UTF-8" ?>
<LifecycleConfiguration>
    <Rule>
        <Action>
            <Delete/>
        </Action>
        <Condition>
            <IsLive>true</IsLive>
            <Age>30</Age>
        </Condition>
    </Rule>
    <Rule>
        <Action>
            <Delete/>
        </Action>
        <Condition>
            <IsLive>false</IsLive>
            <Age>10</Age>
        </Condition>
    </Rule>
</LifecycleConfiguration>

For the generalized format of a lifecycle configuration file, see the lifecycle configuration format for XML.

Change an object's storage class

The following lifecycle configuration defines two rules:

1. Change the storage class of an object to Nearline Storage if both its age is greater than 365 days (one year) and its current storage class is Standard Storage, Multi-Regional Storage, or Durable Reduced Availability (DRA) Storage.
2. Change the storage class of an object to Coldline Storage if both its age is greater than 1095 days (three years) and its current storage class is Nearline Storage.

Note: This lifecycle configuration applies to buckets in multi-region or dual-region location type. For buckets in region, replace MULTI_REGIONAL with REGIONAL.

Console

The following rule moves objects to Nearline 365 days after the object was created:

The following rule moves objects to Coldline 1095 days after the object was created:

gsutil

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

{
"lifecycle": {
  "rule": [
  {
    "action": {
      "type": "SetStorageClass",
      "storageClass": "NEARLINE"
    },
    "condition": {
      "age": 365,
      "matchesStorageClass": ["MULTI_REGIONAL", "STANDARD", "DURABLE_REDUCED_AVAILABILITY"]
    }
  },
  {
    "action": {
      "type": "SetStorageClass",
      "storageClass": "COLDLINE"
    },
    "condition": {
      "age": 1095,
      "matchesStorageClass": ["NEARLINE"]
    }
  }
]
}
}

For the generalized format of a lifecycle configuration file, see the bucket resource representation for JSON.

REST APIs

JSON API

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

{
"lifecycle": {
  "rule": [
  {
    "action": {
      "type": "SetStorageClass",
      "storageClass": "NEARLINE"
    },
    "condition": {
      "age": 365,
      "matchesStorageClass": ["MULTI_REGIONAL", "STANDARD", "DURABLE_REDUCED_AVAILABILITY"]
    }
  },
  {
    "action": {
      "type": "SetStorageClass",
      "storageClass": "COLDLINE"
    },
    "condition": {
      "age": 1095,
      "matchesStorageClass": ["NEARLINE"]
    }
  }
]
}
}

For the generalized format of a lifecycle configuration file, see the bucket resource representation for JSON.

XML API

The following lifecycle configuration can be applied to a bucket by enabling lifecycle management.

<?xml version="1.0" encoding="UTF-8" ?>
<LifecycleConfiguration>
    <Rule>
        <Action>
            <SetStorageClass>NEARLINE</SetStorageClass>
        </Action>
        <Condition>
            <Age>365</Age>
            <MatchesStorageClass>MULTI_REGIONAL</MatchesStorageClass>
            <MatchesStorageClass>STANDARD</MatchesStorageClass>
            <MatchesStorageClass>DURABLE_REDUCED_AVAILABILITY</MatchesStorageClass>
        </Condition>
    </Rule>
    <Rule>
        <Action>
            <SetStorageClass>COLDLINE</SetStorageClass>
        </Action>
        <Condition>
            <Age>1095</Age>
            <MatchesStorageClass>NEARLINE</MatchesStorageClass>
        </Condition>
    </Rule>
</LifecycleConfiguration>

For the generalized format of a lifecycle configuration file, see the lifecycle configuration format for XML.