Managing object lifecycles

Go to concepts

This page describes how to enable Object Lifecycle Management and gives examples of lifecycle configurations. Lifecycle configurations are managed at the bucket level and apply to all current and future objects in the bucket.

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. In the Google Cloud Console, go to the Cloud Storage Browser page.
   

   Go to Browser

2. In the bucket list, find the bucket you want to enable, and click on the bucket's name.

3. Click on the Lifecycle tab.

   The lifecycle rules page appears.

4. Click Add a rule.

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

   1. Select the action to take when an object meets the conditions.

   2. Click Continue.

   3. Select the conditions under which an action is taken.

   4. Click Continue.

   5. Click Create.

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

gsutil

1. Create a .json file with the lifecycle configuration rules you would like to apply. See configuration examples for sample .json files.

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 const& 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";
}

C#

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

View on GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class EnableBucketLifecycleManagementSample
{
    public Bucket EnableBucketLifecycleManagement(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);
        bucket.Lifecycle = new Bucket.LifecycleData
        {
            Rule = new List<Bucket.LifecycleData.RuleData>
            {
                new Bucket.LifecycleData.RuleData
                {
                    Condition = new Bucket.LifecycleData.RuleData.ConditionData { Age = 100 },
                    Action = new Bucket.LifecycleData.RuleData.ActionData { Type = "Delete" }
                }
            }
        };
        bucket = storage.UpdateBucket(bucket);

        Console.WriteLine($"Lifecycle management is enabled for bucket {bucketName} and the rules are:");
        foreach (var rule in bucket.Lifecycle.Rule)
        {
            Console.WriteLine("Action:");
            Console.WriteLine($"Type: {rule.Action.Type}");
            Console.WriteLine($"Storage Class: {rule.Action.StorageClass}");

            Console.WriteLine("Condition:");
            Console.WriteLine($"Age: \t{rule.Condition.Age}");
            Console.WriteLine($"Created Before: \t{rule.Condition.CreatedBefore}");
            Console.WriteLine($"Time Before: \t{rule.Condition.CustomTimeBefore}");
            Console.WriteLine($"Days Since Custom Time: \t{rule.Condition.DaysSinceCustomTime}");
            Console.WriteLine($"Days Since Non-current Time: \t{rule.Condition.DaysSinceNoncurrentTime}");
            Console.WriteLine($"IsLive: \t{rule.Condition.IsLive}");
            Console.WriteLine($"Pattern: \t{rule.Condition.MatchesPattern}");
            Console.WriteLine($"Storage Class: \t{rule.Condition.MatchesStorageClass}");
            Console.WriteLine($"Noncurrent Time Before: \t{rule.Condition.NoncurrentTimeBefore}");
            Console.WriteLine($"Newer Versions: \t{rule.Condition.NumNewerVersions}");
        }
        return bucket;
    }
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// enableBucketLifecycleManagement adds a lifecycle delete rule with the
// condition that the object is 100 days old.
func enableBucketLifecycleManagement(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		Lifecycle: &storage.Lifecycle{
			Rules: []storage.LifecycleRule{
				{
					Action: storage.LifecycleAction{Type: "Delete"},
					Condition: storage.LifecycleCondition{
						AgeInDays: 100,
					},
				},
			},
		},
	}

	attrs, err := bucket.Update(ctx, bucketAttrsToUpdate)
	if err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Lifecycle management is enabled for bucket %v\n and the rules are:\n", bucketName)
	for _, rule := range attrs.Lifecycle.Rules {
		fmt.Fprintf(w, "Action: %v\n", rule.Action)
		fmt.Fprintf(w, "Condition: %v\n", rule.Condition)
	}

	return nil
}

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);
  }
}

Node.js

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

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableBucketLifecycleManagement() {
  const [metadata] = await storage.bucket(bucketName).addLifecycleRule({
    action: 'delete',
    condition: {age: 100},
  });

  console.log(
    `Lifecycle management is enabled for bucket ${bucketName} and the rules are:`
  );

  console.log(metadata.lifecycle.rule);
}

enableBucketLifecycleManagement().catch(console.error);

PHP

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

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;
use Google\Cloud\Storage\Bucket;

/**
 * Enable bucket lifecycle management.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function enable_bucket_lifecycle_management($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $lifecycle = Bucket::lifecycle()
        ->addDeleteRule([
            'age' => 100
        ]);

    $bucket->update([
        'lifecycle' => $lifecycle
    ]);

    $lifecycle = $bucket->currentLifecycle();

    printf('Lifecycle management is enabled for bucket %s and the rules are:' . PHP_EOL, $bucketName);
    foreach ($lifecycle as $rule) {
        print_r($rule);
        print(PHP_EOL);
    }
}

Python

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

View on GitHub Feedback

from google.cloud import storage


def enable_bucket_lifecycle_management(bucket_name):
    """Enable lifecycle management for a bucket"""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    rules = bucket.lifecycle_rules

    print("Lifecycle management rules for bucket {} are {}".format(bucket_name, list(rules)))
    bucket.add_lifecycle_delete_rule(age=2)
    bucket.patch()

    rules = bucket.lifecycle_rules
    print("Lifecycle management is enable for bucket {} and the rules are {}".format(bucket_name, list(rules)))

    return bucket

Ruby

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

View on GitHub Feedback

def enable_bucket_lifecycle_management bucket_name:
  # Enable lifecycle management for a bucket
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  rules = bucket.lifecycle do |l|
    l.add_delete_rule age: 2
  end

  puts "Lifecycle management is enabled for bucket #{bucket_name} and the rules are #{rules}"
end

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 configuration examples for sample .json files.

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 configuration examples for sample .xml files.

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. In the Google Cloud Console, go to the Cloud Storage Browser page.
   

   Go to Browser

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

   The lifecycle rules page appears.

3. Click Delete all.

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

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

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

gsutil

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

   {
     "lifecycle": {
       "rule": []
     }
   }

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.

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 const& bucket_name) {
  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().ResetLifecycle());

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

  std::cout << "Successfully disabled bucket lifecycle management for bucket "
            << updated_metadata->name() << ".\n";
}

C#

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

View on GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class DisableBucketLifecycleManagementSample
{
    public Bucket DisableBucketLifecycleManagement(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);
        bucket.Lifecycle = null;
        bucket = storage.UpdateBucket(bucket);

        Console.WriteLine($"Lifecycle management is disabled for bucket {bucketName}.");
        return bucket;
    }
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// disableBucketLifecycleManagement removes all existing lifecycle rules
// from the bucket.
func disableBucketLifecycleManagement(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		Lifecycle: &storage.Lifecycle{},
	}

	_, err = bucket.Update(ctx, bucketAttrsToUpdate)
	if err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Lifecycle management is disabled for bucket %v.\n", bucketName)

	return nil
}

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.Storage;
import com.google.cloud.storage.StorageOptions;

public class DisableLifecycleManagement {
  public static void disableLifecycleManagement(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);
    bucket.toBuilder().deleteLifecycleRules().build().update();

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

Node.js

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

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function disableBucketLifecycleManagement() {
  await storage.bucket(bucketName).setMetadata({lifecycle: null});

  console.log(`Lifecycle management is disabled for bucket ${bucketName}`);
}

disableBucketLifecycleManagement().catch(console.error);

PHP

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

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;
use Google\Cloud\Storage\Bucket;

/**
 * Disable bucket lifecycle management.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function disable_bucket_lifecycle_management($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $bucket->update([
        'lifecycle' => null
    ]);

    printf('Lifecycle management is disabled for bucket %s.' . PHP_EOL, $bucketName);
}

Python

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

View on GitHub Feedback

from google.cloud import storage


def disable_bucket_lifecycle_management(bucket_name):
    """Disable lifecycle management for a bucket"""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.clear_lifecyle_rules()
    bucket.patch()
    rules = bucket.lifecycle_rules

    print("Lifecycle management is disable for bucket {} and the rules are {}".format(bucket_name, list(rules)))
    return bucket

Ruby

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

View on GitHub Feedback

def disable_bucket_lifecycle_management bucket_name:
  # Disable lifecycle management for a bucket
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  bucket.lifecycle do |l|
    l.clear
  end

  puts "Lifecycle management is disabled for bucket #{bucket_name}"
end

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:

   {
     "lifecycle": {
       "rule": []
     }
   }

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. In the Google Cloud Console, go to the Cloud Storage Browser page.
   

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

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

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.

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 const& bucket_name) {
  StatusOr<gcs::BucketMetadata> updated_metadata =
      client.GetBucketMetadata(bucket_name);

  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 << "Bucket lifecycle management is enabled 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";
}

C#

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class GetBucketMetadataSample
{
    public Bucket GetBucketMetadata(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{bucket.Name}");
        Console.WriteLine($"Acl:\t{bucket.Acl}");
        Console.WriteLine($"Billing:\t{bucket.Billing}");
        Console.WriteLine($"Cors:\t{bucket.Cors}");
        Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
        Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
        Console.WriteLine($"Encryption:\t{bucket.Encryption}");
        if (bucket.Encryption != null)
        {
            Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
        }
        Console.WriteLine($"Id:\t{bucket.Id}");
        Console.WriteLine($"Kind:\t{bucket.Kind}");
        Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
        Console.WriteLine($"Location:\t{bucket.Location}");
        Console.WriteLine($"LocationType:\t{bucket.LocationType}");
        Console.WriteLine($"Logging:\t{bucket.Logging}");
        Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
        Console.WriteLine($"Owner:\t{bucket.Owner}");
        Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
        Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
        Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
        Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
        Console.WriteLine($"Updated:\t{bucket.Updated}");
        Console.WriteLine($"Versioning:\t{bucket.Versioning}");
        Console.WriteLine($"Website:\t{bucket.Website}");
        if (bucket.Labels != null)
        {
            Console.WriteLine("Labels:");
            foreach (var label in bucket.Labels)
            {
                Console.WriteLine($"{label.Key}:\t{label.Value}");
            }
        }
        return bucket;
    }
}

Go

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// getBucketMetadata gets the bucket metadata.
func getBucketMetadata(w io.Writer, bucketName string) (*storage.BucketAttrs, error) {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	attrs, err := client.Bucket(bucketName).Attrs(ctx)
	if err != nil {
		return nil, fmt.Errorf("Bucket(%q).Attrs: %v", bucketName, err)
	}
	fmt.Fprintf(w, "BucketName: %v\n", attrs.Name)
	fmt.Fprintf(w, "Location: %v\n", attrs.Location)
	fmt.Fprintf(w, "LocationType: %v\n", attrs.LocationType)
	fmt.Fprintf(w, "StorageClass: %v\n", attrs.StorageClass)
	fmt.Fprintf(w, "TimeCreated: %v\n", attrs.Created)
	fmt.Fprintf(w, "Metageneration: %v\n", attrs.MetaGeneration)
	fmt.Fprintf(w, "PredefinedACL: %v\n", attrs.PredefinedACL)
	if attrs.Encryption != nil {
		fmt.Fprintf(w, "DefaultKmsKeyName: %v\n", attrs.Encryption.DefaultKMSKeyName)
	}
	if attrs.Website != nil {
		fmt.Fprintf(w, "IndexPage: %v\n", attrs.Website.MainPageSuffix)
		fmt.Fprintf(w, "NotFoundPage: %v\n", attrs.Website.NotFoundPage)
	}
	fmt.Fprintf(w, "DefaultEventBasedHold: %v\n", attrs.DefaultEventBasedHold)
	if attrs.RetentionPolicy != nil {
		fmt.Fprintf(w, "RetentionEffectiveTime: %v\n", attrs.RetentionPolicy.EffectiveTime)
		fmt.Fprintf(w, "RetentionPeriod: %v\n", attrs.RetentionPolicy.RetentionPeriod)
		fmt.Fprintf(w, "RetentionPolicyIsLocked: %v\n", attrs.RetentionPolicy.IsLocked)
	}
	fmt.Fprintf(w, "RequesterPays: %v\n", attrs.RequesterPays)
	fmt.Fprintf(w, "VersioningEnabled: %v\n", attrs.VersioningEnabled)
	if attrs.Logging != nil {
		fmt.Fprintf(w, "LogBucket: %v\n", attrs.Logging.LogBucket)
		fmt.Fprintf(w, "LogObjectPrefix: %v\n", attrs.Logging.LogObjectPrefix)
	}
	if attrs.CORS != nil {
		fmt.Fprintln(w, "CORS:")
		for _, v := range attrs.CORS {
			fmt.Fprintf(w, "\tMaxAge: %v\n", v.MaxAge)
			fmt.Fprintf(w, "\tMethods: %v\n", v.Methods)
			fmt.Fprintf(w, "\tOrigins: %v\n", v.Origins)
			fmt.Fprintf(w, "\tResponseHeaders: %v\n", v.ResponseHeaders)
		}
	}
	if attrs.Labels != nil {
		fmt.Fprintf(w, "\n\n\nLabels:")
		for key, value := range attrs.Labels {
			fmt.Fprintf(w, "\t%v = %v\n", key, value)
		}
	}
	return attrs, nil
}

Java

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetBucketMetadata {
  public static void getBucketMetadata(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();

    // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
    Bucket bucket =
        storage.get(bucketName, Storage.BucketGetOption.fields(Storage.BucketField.values()));

    // Print bucket metadata
    System.out.println("BucketName: " + bucket.getName());
    System.out.println("DefaultEventBasedHold: " + bucket.getDefaultEventBasedHold());
    System.out.println("DefaultKmsKeyName: " + bucket.getDefaultKmsKeyName());
    System.out.println("Id: " + bucket.getGeneratedId());
    System.out.println("IndexPage: " + bucket.getIndexPage());
    System.out.println("Location: " + bucket.getLocation());
    System.out.println("LocationType: " + bucket.getLocationType());
    System.out.println("Metageneration: " + bucket.getMetageneration());
    System.out.println("NotFoundPage: " + bucket.getNotFoundPage());
    System.out.println("RetentionEffectiveTime: " + bucket.getRetentionEffectiveTime());
    System.out.println("RetentionPeriod: " + bucket.getRetentionPeriod());
    System.out.println("RetentionPolicyIsLocked: " + bucket.retentionPolicyIsLocked());
    System.out.println("RequesterPays: " + bucket.requesterPays());
    System.out.println("SelfLink: " + bucket.getSelfLink());
    System.out.println("StorageClass: " + bucket.getStorageClass().name());
    System.out.println("TimeCreated: " + bucket.getCreateTime());
    System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
    if (bucket.getLabels() != null) {
      System.out.println("\n\n\nLabels:");
      for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
        System.out.println(label.getKey() + "=" + label.getValue());
      }
    }
    if (bucket.getLifecycleRules() != null) {
      System.out.println("\n\n\nLifecycle Rules:");
      for (BucketInfo.LifecycleRule rule : bucket.getLifecycleRules()) {
        System.out.println(rule);
      }
    }
  }
}

Node.js

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function getBucketMetadata() {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // Get Bucket Metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  for (const [key, value] of Object.entries(metadata)) {
    console.log(`${key}: ${value}`);
  }
}

PHP

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 *
 * @return void
 */
function get_bucket_metadata($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();

    printf("Bucket Metadata: %s" . PHP_EOL, print_r($info));
}

Python

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

from google.cloud import storage


def bucket_metadata(bucket_name):
    """Prints out a bucket's metadata."""
    # bucket_name = 'your-bucket-name'

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    print("ID: {}".format(bucket.id))
    print("Name: {}".format(bucket.name))
    print("Storage Class: {}".format(bucket.storage_class))
    print("Location: {}".format(bucket.location))
    print("Location Type: {}".format(bucket.location_type))
    print("Cors: {}".format(bucket.cors))
    print(
        "Default Event Based Hold: {}".format(bucket.default_event_based_hold)
    )
    print("Default KMS Key Name: {}".format(bucket.default_kms_key_name))
    print("Metageneration: {}".format(bucket.metageneration))
    print(
        "Retention Effective Time: {}".format(
            bucket.retention_policy_effective_time
        )
    )
    print("Retention Period: {}".format(bucket.retention_period))
    print("Retention Policy Locked: {}".format(bucket.retention_policy_locked))
    print("Requester Pays: {}".format(bucket.requester_pays))
    print("Self Link: {}".format(bucket.self_link))
    print("Time Created: {}".format(bucket.time_created))
    print("Versioning Enabled: {}".format(bucket.versioning_enabled))
    print("Labels:")
    print(bucket.labels)

Ruby

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

To view the bucket's lifecycle policies, follow the instructions for displaying a bucket's metadata and look for the lifecycle policy fields in the response.

View on GitHub Feedback

def get_bucket_metadata bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  puts "ID:                       #{bucket.id}"
  puts "Name:                     #{bucket.name}"
  puts "Storage Class:            #{bucket.storage_class}"
  puts "Location:                 #{bucket.location}"
  puts "Location Type:            #{bucket.location_type}"
  puts "Cors:                     #{bucket.cors}"
  puts "Default Event Based Hold: #{bucket.default_event_based_hold?}"
  puts "Default KMS Key Name:     #{bucket.default_kms_key}"
  puts "Logging Bucket:           #{bucket.logging_bucket}"
  puts "Logging Prefix:           #{bucket.logging_prefix}"
  puts "Metageneration:           #{bucket.metageneration}"
  puts "Retention Effective Time: #{bucket.retention_effective_at}"
  puts "Retention Period:         #{bucket.retention_period}"
  puts "Retention Policy Locked:  #{bucket.retention_policy_locked?}"
  puts "Requester Pays:           #{bucket.requester_pays}"
  puts "Self Link:                #{bucket.api_url}"
  puts "Time Created:             #{bucket.created_at}"
  puts "Versioning Enabled:       #{bucket.versioning?}"
  puts "Index Page:               #{bucket.website_main}"
  puts "Not Found Page:           #{bucket.website_404}"
  puts "Labels:"
  bucket.labels.each do |key, value|
    puts " - #{key} = #{value}"
  end
  puts "Lifecycle Rules:"
  bucket.lifecycle.each do |rule|
    puts "#{rule.action} - #{rule.storage_class} - #{rule.age} - #{rule.matches_storage_class}"
  end
end

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 perform lifecycle actions when common lifecycle conditions are met. These configurations apply to all current and future objects in the configured bucket.

Delete an object

Warning: This example involves deleting data. Once permanently deleted, objects cannot be recovered. Take care in setting up your lifecycle rules so that you do not cause more data to be deleted than you intend. You should test your lifecycle rules on development data before applying to production to ensure your rules have the effect you intend.

The following lifecycle configuration defines three rules. Note that the second and third rules are applicable only when using Object Versioning on the bucket:

1. Delete live versions of objects older than 30 days.

   • If the bucket uses Object Versioning, such objects become noncurrent and are subject to the other two rules.

   • If the bucket does not use Object Versioning, such objects are permanently deleted and cannot be recovered.

2. Delete noncurrent versions of objects if there are 2 newer versions of the object in the bucket. Objects subject to this rule are permanently deleted and cannot be recovered.

3. Delete noncurrent versions of objects older than 35 days. Objects subject to this rule are permanently deleted and cannot be recovered.

The combined effect of these three rules is that objects are subject to permanent deletion after a maximum of 35 days in the bucket: 30 days as a live version and 5 days as a noncurrent version. For live object versions replaced or deleted outside the scope of this configuration, they become subject to permanent deletion sooner: either 5 days from the time they became noncurrent or whenever there is more than one newer version of the object in the bucket.

Console

These settings use the instructions found in the enable section.

1. To delete live versions of objects older than 30 days:

   1. Select the Delete object action.
   2. Select the Age condition, and enter a value of 30.
   3. Select the Live state condition, and choose the Live option.

2. To delete noncurrent versions of objects if there are 2 newer versions:

   1. Select the Delete object action.
   2. Select the Number of newer versions condition, and enter a value of 2.

3. To delete noncurrent versions of objects older than 35 days:

   1. Select the Delete object action.
   2. Select the Age condition, and enter a value of 35.
   3. Select the Live state condition, and choose the Noncurrent option.

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": {
      "numNewerVersions": 2
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 35,
      "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": {
      "numNewerVersions": 2
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "age": 35,
      "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>
            <NumberOfNewerVersions>2</Age>
        </Condition>
    </Rule>
    <Rule>
        <Action>
            <Delete/>
        </Action>
        <Condition>
            <IsLive>false</IsLive>
            <Age>35</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

These settings use the instructions found in the enable section.

1. To move objects to Cloud Storage Nearline 365 days after they were created:

   1. Select the Set storage class to Nearline action.
   2. Select the Age condition, and enter a value of 365.
   3. Select the Storage class matches condition, and choose the Standard, Multi-Regional, and Durable Reduced Availability options.

2. To move objects to Cloud Storage Coldline 1095 days after they were created:

   1. Select the Set storage class to Coldline action.
   2. Select the Age condition, and enter a value of 1095.
   3. Select the Storage class matches condition, and choose the Nearline option.

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.

What's next

• Learn more about Object Lifecycle Management, including the available lifecycle actions and lifecycle conditions.