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

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.

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.


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.

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.

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.

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

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)
{
    // $bucketName = 'my-bucket';

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

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.

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. For instructions, see API authentication.
  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. For instructions, see API authentication.
  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.

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.

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.


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.

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.

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.

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

use Google\Cloud\Storage\StorageClient;

/**
 * Disable bucket lifecycle management.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 */
function disable_bucket_lifecycle_management($bucketName)
{
    // $bucketName = 'my-bucket';

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

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.

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. For instructions, see API authentication.
  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. For instructions, see API authentication.
  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.

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.

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.
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.
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.
// 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.
use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 */
function get_bucket_metadata($bucketName)
{
    // $bucketName = 'my-bucket';

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

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(f"ID: {bucket.id}")
    print(f"Name: {bucket.name}")
    print(f"Storage Class: {bucket.storage_class}")
    print(f"Location: {bucket.location}")
    print(f"Location Type: {bucket.location_type}")
    print(f"Cors: {bucket.cors}")
    print(f"Default Event Based Hold: {bucket.default_event_based_hold}")
    print(f"Default KMS Key Name: {bucket.default_kms_key_name}")
    print(f"Metageneration: {bucket.metageneration}")
    print(
        f"Public Access Prevention: {bucket.iam_configuration.public_access_prevention}"
    )
    print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
    print(f"Retention Period: {bucket.retention_period}")
    print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
    print(f"Requester Pays: {bucket.requester_pays}")
    print(f"Self Link: {bucket.self_link}")
    print(f"Time Created: {bucket.time_created}")
    print(f"Versioning Enabled: {bucket.versioning_enabled}")
    print(f"Labels: {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.
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. For instructions, see API authentication.
  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. For instructions, see API authentication.
  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 older object versions

The following lifecycle configuration defines two rules. Note that these rules are applicable only when using Object Versioning on the bucket:

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

  2. Delete noncurrent versions of objects after they've been noncurrent for 7 days. Objects subject to this rule are permanently deleted and cannot be recovered.

The combined effect of these two rules in buckets that use Object Versioning is that live objects have a window of time in which they can be recovered if they get overwritten or deleted: such an object remains in the bucket in a noncurrent state for seven days or until 2 newer versions of the object exist in the bucket.

Console

These settings use the instructions found in the enable section.

  1. To delete noncurrent versions of objects if there is a newer version:

    1. Select the Delete object action.
    2. Select the Live state condition, and select the Noncurrent radio button.
    3. Select the Number of newer versions condition, and enter a value of 2.
  2. To delete noncurrent versions of objects after they're been noncurrent for 7 days:

    1. Select the Delete object action.
    2. Select the Days since becoming noncurrent condition, and enter a value of 7.

gsutil

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

{
"lifecycle": {
  "rule": [
  {
    "action": {"type": "Delete"},
    "condition": {
      "numNewerVersions": 2,
      "isLive": false
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "daysSinceNoncurrentTime": 7
    }
  }
]
}
}

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": {
      "numNewerVersions": 2,
      "isLive": false
    }
  },
  {
    "action": {"type": "Delete"},
    "condition": {
      "daysSinceNoncurrentTime": 7
    }
  }
]
}
}

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>false</IsLive>
            <NumberOfNewerVersions>2</Age>
        </Condition>
    </Rule>
    <Rule>
        <Action>
            <Delete/>
        </Action>
        <Condition>
            <DaysSinceNoncurrentTime>7</DaysSinceNoncurrentTime>
        </Condition>
    </Rule>
</LifecycleConfiguration>

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

Configuration modifications

Depending on your goals, there are several modifications you could make to this example configuration:

  • If you wanted to protect your data from accidental deletion but not accidental overwrite, set the number of newer versions to 1, which also reduces storage costs, because you retain fewer versions of an object.

  • If your data is stored as Nearline Storage, Coldline Storage, or Archive Storage, add an Age condition or use a larger value for DaysSinceNoncurrent to avoid early deletion fees. Note that even with such changes, you might incur early deletion fees, depending on how frequently you overwrite and delete your objects.

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.

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