Managing turbo replication

Go to concepts

This page describes how to use the turbo replication feature on a dual-region bucket.

Prerequisites

Prerequisites can vary based on the tool used:

Console

In order to complete this guide using the Google Cloud console, you must have the proper IAM permissions. To use this feature, you must have or intend to create a bucket in a dual-region location. If the bucket you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.

For a list of permissions required for specific actions, see IAM permissions for the Google Cloud console.

For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.

Command line

In order to complete this guide using a command-line utility, you must have the proper IAM permissions. To use this feature, you must have or intend to create a bucket in a dual-region location. If the bucket you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.

For a list of permissions required for specific actions, see IAM permissions for gsutil commands.

For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.

Code samples

In order to complete this guide using the Cloud Storage client libraries, you must have the proper IAM permissions. To use this feature, you must have or intend to create a bucket in a dual-region location. If the bucket you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions. Unless otherwise noted, client library requests are made through the JSON API.

For a list of permissions required for specific actions, see IAM permissions for JSON methods.

For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.

REST APIs

JSON API

In order to complete this guide using the JSON API, you must have the proper IAM permissions. To use this feature, you must have or intend to create a bucket in a dual-region location. If the bucket you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.

For a list of permissions required for specific actions, see IAM permissions for JSON methods.

For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.

XML API

This feature cannot be managed through the XML API. Use the JSON API instead.

Check a bucket's replication status

To check the recovery point objective (RPO) or replication status of a bucket, complete the following instructions:

Console

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

    Go to Browser

  2. In the bucket list, click the name of the bucket you want to verify.

  3. Click the Configuration tab.

  4. If turbo replication is enabled on the bucket, Replication is set to Turbo.

Command line

Use the gsutil rpo get command:

gsutil rpo get gs://BUCKET_NAME/

Where:

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

If successful, the response looks like the following example:

gs://my-bucket: ASYNC_TURBO

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) {
  auto metadata = client.GetBucketMetadata(bucket_name);
  if (!metadata) throw std::runtime_error(metadata.status().message());

  std::cout << "RPO is " << metadata->rpo() << " for bucket "
            << metadata->name() << "\n";
}

C#

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


using System;
using Google.Cloud.Storage.V1;

public class GetRpoSample
{
    public string GetRpo(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var rpo = storage.GetBucket(bucketName).Rpo;
        Console.WriteLine($"The RPO Setting of bucket {bucketName} is {rpo}.");

        return rpo;
    }
}

Go

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

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

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

// getRPO gets the current RPO (Recovery Point Objective) setting
// for the bucket, either "DEFAULT" or "ASYNC_TURBO".
func getRPO(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()

	attrs, err := client.Bucket(bucketName).Attrs(ctx)
	if err != nil {
		return fmt.Errorf("Bucket(%q).Attrs: %v", bucketName, err)
	}
	fmt.Fprintf(w, "RPO is %s for %v", attrs.RPO, 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 GetBucketRpo {
  public static void getBucketRpo(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);
    String rpo = bucket.getRpo().toString();

    System.out.println("The RPO setting of bucket " + bucketName + " is " + rpo);
  }
}

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 name of your GCS bucket in a dual-region
// const bucketName = 'Name of a bucket, e.g. my-bucket';

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

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

async function getRPO() {
  // Gets Bucket Metadata and prints RPO value (either 'default' or 'async_turbo').
  // If RPO is undefined, the bucket is a single region bucket
  const [metadata] = await storage.bucket(bucketName).getMetadata();
  console.log(`RPO is ${metadata.rpo} for ${bucketName}.`);
}

getRPO();

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Get the bucket's recovery point objective (RPO) setting.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function get_rpo($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    printf(
        'The bucket\'s RPO value is: %s.' . PHP_EOL,
        $bucket->info()['rpo']
    );
}

Python

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


from google.cloud import storage
from google.cloud.storage.constants import RPO_DEFAULT


def get_rpo(bucket_name):
    """Gets the RPO of the bucket"""
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"

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

    bucket.rpo = RPO_DEFAULT
    rpo = bucket.rpo

    print(f"RPO for {bucket.name} is {rpo}.")

Ruby

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

def get_rpo 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 "The RPO setting of bucket '#{bucket_name}' is #{bucket.rpo}."
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=rpo"

    Where:

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

    The response looks like the following example:

    {
  "name": "my-bucket",
  "projectNumber": "234...",
  ...
  "rpo": "ASYNC_TURBO"
}

    Notice the rpo key. The value ASYNC_TURBO indicates that turbo replication is enabled. DEFAULT indicates that default replication is applied. The rpo field is always present for dual- and multi-region buckets, but is absent from single-region buckets.

XML API

This feature cannot be managed through the XML API. Use the JSON API instead.

Set turbo replication

To enable or disable turbo replication on an existing bucket, complete the following instructions:

Console

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

    Go to Browser

  2. In the bucket list, click the name of the desired bucket.

  3. Click the Configuration tab.

  4. In the Replication row, click Edit.

    The window that appears indicates whether you are about to Enable turbo replication or Disable turbo replication.

  5. Click Save to confirm the new setting.

Command line

Use the gsutil rpo set command:

gsutil rpo set STATE gs://BUCKET_NAME/

Where:

  • STATE is ASYNC_TURBO for enabling Turbo Replication or DEFAULT for disabling Turbo Replication.

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

If successful, a response is not returned. The change takes effect immediately.

Code samples

C++

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

The following sample enables turbo replication on a bucket:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  auto updated = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetRpo(gcs::RpoAsyncTurbo()));
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "RPO is set to 'ASYNC_TURBO' for " << updated->name() << "\n";
}

The following sample enables default replication on a bucket:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  auto updated = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetRpo(gcs::RpoDefault()));
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "RPO is set to 'default' for " << updated->name() << "\n";
}

C#

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

The following sample enables turbo replication on a bucket:

// Copyright 2021 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


using System;
using Google.Cloud.Storage.V1;

public class SetRpoAsyncTurboSample
{
    public void SetRpoAsyncTurbo(string bucketName = "your-unique-bucket-name")
    {
        // Enabling turbo replication requires a bucket with dual-region configuration
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);
        bucket.Rpo = "ASYNC_TURBO";
        storage.UpdateBucket(bucket);

        Console.WriteLine($"Turbo replication enabled for bucket {bucketName}");
    }
}

The following sample enables default replication on a bucket:

// Copyright 2021 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


using System;
using Google.Cloud.Storage.V1;

public class SetRpoDefaultSample
{
    public void SetRpoDefault(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);
        bucket.Rpo = "DEFAULT";
        storage.UpdateBucket(bucket);

        Console.WriteLine($"Turbo replication disabled for bucket {bucketName}");
    }
}

Go

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

The following sample enables turbo replication on a bucket:

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package buckets

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

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

// setRPOAsyncTurbo enables turbo replication for the bucket by setting RPO to
// "ASYNC_TURBO". The bucket must be dual-region to use this feature.
func setRPOAsyncTurbo(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)
	setRPO := storage.BucketAttrsToUpdate{
		RPO: storage.RPOAsyncTurbo,
	}
	if _, err := bucket.Update(ctx, setRPO); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Turbo replication enabled for %v", bucketName)
	return nil
}

The following sample enables default replication on a bucket:

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package buckets

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

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

// setRPODefault disables turbo replication for the bucket by setting RPO to
// "DEFAULT".
func setRPODefault(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)
	setRPO := storage.BucketAttrsToUpdate{
		RPO: storage.RPODefault,
	}
	if _, err := bucket.Update(ctx, setRPO); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Turbo replication disabled for %v", bucketName)
	return nil
}

Java

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

The following sample enables turbo replication on a bucket:

/*
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.storage.bucket;

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Rpo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetAsyncTurboRpo {
  public static void setAsyncTurboRpo(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().setRpo(Rpo.ASYNC_TURBO).build().update();

    System.out.println("Turbo replication was enabled for " + bucketName);
  }
}

The following sample enables default replication on a bucket:

/*
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.storage.bucket;

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Rpo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetDefaultRpo {
  public static void setDefaultRpo(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().setRpo(Rpo.DEFAULT).build().update();

    System.out.println("Replication was set to default for " + bucketName);
  }
}

Node.js

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

The following sample enables turbo replication on a bucket:

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * This application demonstrates how to perform basic operations on buckets with
 * the Google Cloud Storage API.
 *
 * For more information, see the README.md under /storage and the documentation
 * at https://cloud.google.com/storage/docs.
 */

function main(bucketName = 'my-bucket') {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The name of your GCS bucket in a dual-region
  // const bucketName = 'Name of a bucket, e.g. my-bucket';

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

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

  // Enable turbo replication for the bucket by setting rpo to ASYNC_TURBO.
  // The bucket must be a dual-region bucket.
  async function setRPOAsyncTurbo() {
    await storage.bucket(bucketName).setMetadata({
      rpo: 'ASYNC_TURBO',
    });

    console.log(`Turbo replication enabled for ${bucketName}.`);
  }

  setRPOAsyncTurbo();
}

process.on('unhandledRejection', err => {
  console.error(err.message);
  process.exitCode = 1;
});
main(...process.argv.slice(2));

The following sample enables default replication on a bucket:

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * This application demonstrates how to perform basic operations on buckets with
 * the Google Cloud Storage API.
 *
 * For more information, see the README.md under /storage and the documentation
 * at https://cloud.google.com/storage/docs.
 */

function main(bucketName = 'my-bucket') {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The name of your GCS bucket in a dual-region
  // const bucketName = 'Name of a bucket, e.g. my-bucket';

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

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

  // Disable turbo replication for the bucket by setting RPO to default.
  // The bucket must be a dual-region bucket.
  async function setRPODefault() {
    await storage.bucket(bucketName).setMetadata({
      rpo: 'DEFAULT',
    });

    console.log(`Turbo replication disabled for ${bucketName}.`);
  }

  setRPODefault();
}

process.on('unhandledRejection', err => {
  console.error(err.message);
  process.exitCode = 1;
});
main(...process.argv.slice(2));

PHP

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

The following sample enables turbo replication on a bucket:

<?php
/**
 * Copyright 2021 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * For instructions on how to run the full sample:
 *
 * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/master/storage/README.md
 */

namespace Google\Cloud\Samples\Storage;

use Google\Cloud\Storage\StorageClient;

/**
 * Set the bucket's Turbo Replication(rpo) setting to `ASYNC_TURBO`.
 * The bucket must be a dual-region bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function set_rpo_async_turbo($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $rpo = 'ASYNC_TURBO';

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

    printf(
        'The replication behavior or recovery point objective (RPO) has been set to ASYNC_TURBO for %s.' . PHP_EOL,
        $bucketName
    );
}

// The following 2 lines are only needed to run the samples
require_once __DIR__ . '/../../testing/sample_helpers.php';
\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

The following sample enables default replication on a bucket:

<?php
/**
 * Copyright 2021 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * For instructions on how to run the full sample:
 *
 * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/master/storage/README.md
 */

namespace Google\Cloud\Samples\Storage;

use Google\Cloud\Storage\StorageClient;

/**
 * Set the bucket's replication behavior or recovery point objective (RPO) to `DEFAULT`.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function set_rpo_default($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $rpo = 'DEFAULT';

    // Updating the rpo value of a multi-region bucket to DEFAULT has no effect
    // and updating the rpo value of a regional bucket will throw an exception.
    $bucket->update([
        'rpo' => $rpo
    ]);

    printf(
        'The replication behavior or recovery point objective (RPO) has been set to DEFAULT for %s.' . PHP_EOL,
        $bucketName
    );
}

// The following 2 lines are only needed to run the samples
require_once __DIR__ . '/../../testing/sample_helpers.php';
\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

Python

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

The following sample enables turbo replication on a bucket:

#!/usr/bin/env python

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the 'License');
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import sys

"""Sample that sets RPO (Recovery Point Objective) to ASYNC_TURBO
This sample is used on this page:
    https://cloud.google.com/storage/docs/managing-turbo-replication
For more information, see README.md.
"""


from google.cloud import storage
from google.cloud.storage.constants import RPO_ASYNC_TURBO


def set_rpo_async_turbo(bucket_name):
    """Sets the RPO to ASYNC_TURBO, enabling the turbo replication feature"""
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"

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

    bucket.rpo = RPO_ASYNC_TURBO
    bucket.patch()

    print(f"RPO is set to ASYNC_TURBO for {bucket.name}.")



if __name__ == "__main__":
    set_rpo_async_turbo(bucket_name=sys.argv[1])

The following sample enables default replication on a bucket:

#!/usr/bin/env python

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the 'License');
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import sys

"""Sample that sets the replication behavior or recovery point objective (RPO) to default.
This sample is used on this page:
    https://cloud.google.com/storage/docs/managing-turbo-replication
For more information, see README.md.
"""


from google.cloud import storage
from google.cloud.storage.constants import RPO_DEFAULT


def set_rpo_default(bucket_name):
    """Sets the RPO to DEFAULT, disabling the turbo replication feature"""
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"

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

    bucket.rpo = RPO_DEFAULT
    bucket.patch()

    print(f"RPO is set to DEFAULT for {bucket.name}.")



if __name__ == "__main__":
    set_rpo_default(bucket_name=sys.argv[1])

Ruby

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

The following sample enables turbo replication on a bucket:

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

def set_rpo_async_turbo 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,
                           location: "ASIA"

  bucket.rpo = :ASYNC_TURBO

  puts "Turbo replication is enabled for #{bucket_name}."
end

set_rpo_async_turbo bucket_name: ARGV.shift if $PROGRAM_NAME == __FILE__

The following sample enables default replication on a bucket:

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

def set_rpo_default 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

  bucket.rpo = :DEFAULT

  puts "The replication behavior or recovery point objective (RPO) for #{bucket_name} is set to default."
end

set_rpo_default bucket_name: ARGV.shift if $PROGRAM_NAME == __FILE__

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 that contains the following information:

    {
  "rpo": "STATE"
}

    Where STATE is ASYNC_TURBO for enabling Turbo Replication or DEFAULT for disabling Turbo Replication.

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

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

    Where:

    • JSON_FILE_NAME is the path for the JSON file that 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.

    If the request is successful, no response is returned.

XML API

This feature cannot be managed through the XML API. Use the JSON API instead.

Create a dual-region bucket with turbo replication

To create a new dual-region bucket with turbo replication enabled, complete the following instructions:

Console

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

    Go to Browser

  2. Click Create bucket.

  3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.

    1. For Name your bucket, enter a name that meets the bucket naming requirements.

    2. For Choose where to store your data, next to Location type, choose Dual-region and select the Add turbo replication checkbox.

    3. For Location, select one of the available dual-regions.

    4. For Choose a default storage class for your data, select a storage class for the bucket. The default storage class is assigned by default to all objects uploaded to the bucket.

    5. For Choose how to control access to objects, select an Access control option. The access control model determines how you control access to the bucket's objects.

    6. For Advanced settings (optional), add bucket labels, set a retention policy, and choose an encryption method.

  4. Click Create.

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

Command line

Use the gsutil mb --rpo command:

gsutil mb -l LOCATION -c CLASS --rpo REPLICATION_TYPE gs://BUCKET_NAME/

Where:

  • LOCATION specifies the geographic location of your bucket. If no location is specified, US multi-region is the default. For the purposes of this example, specify a dual-region. For example, nam4.

  • CLASS specifies the storage class. For example, NEARLINE.

  • REPLICATION_TYPE specifies the replication setting for dual- and multi-region buckets. The DEFAULT value represents default replication and is a valid option for dual- or multi-region buckets. ASYNC_TURBO represents turbo replication and is a valid option for many dual-region buckets. If not specified, default replication is the default replication setting. For the purposes of this example, use ASYNC_TURBO.

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

    If the request is successful, the command returns the following message:

    Creating gs://BUCKET_NAME/...

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) {
  auto bucket =
      client.CreateBucket(bucket_name, gcs::BucketMetadata()
                                           .set_rpo(gcs::RpoAsyncTurbo())
                                           .set_location("NAM4"));
  if (!bucket) throw std::runtime_error(bucket.status().message());

  std::cout << "Created bucket " << bucket->name() << " with RPO set to "
            << bucket->rpo() << " in " << bucket->location() << ".\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 CreateBucketWithTurboReplicationSample
{
    public Bucket CreateBucketWithTurboReplication(
        string projectId = "your-project-id",
        string location = "your-bucket-location",
        string bucketName = "bucket-name")
    {
        var storage = StorageClient.Create();
        // Enabling turbo replication requires a bucket with dual-region configuration
        var bucket = storage.CreateBucket(projectId, new Bucket { Name = bucketName , Location = location, Rpo = "ASYNC_TURBO" });

        Console.WriteLine($"Created {bucket.Name} in {bucket.Location} with RPO Setting {bucket.Rpo}.");
        return bucket;
    }

}

Go

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

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

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

// createBucketTurboReplication creates a new dual-region bucket with
// turbo replication enabled.
func createBucketTurboReplication(w io.Writer, projectID, bucketName, location string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"
	// location := "NAM4" // the name of a dual-region location
	// See this documentation for other valid locations:
	// https://cloud.google.com/storage/docs/locations#location-dr

	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*30)
	defer cancel()

	storageLocationAndRPO := &storage.BucketAttrs{
		Location: location,
		RPO:      storage.RPOAsyncTurbo,
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, storageLocationAndRPO); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v with turbo replication in %v\n", bucketName, storageLocationAndRPO.Location)
	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;
import com.google.cloud.storage.Rpo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

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

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

    // The dual-region location to create your bucket in
    // String location = "NAM4"

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Bucket bucket =
        storage.create(
            BucketInfo.newBuilder(bucketName)
                .setLocation(location)
                .setRpo(Rpo.ASYNC_TURBO)
                .build());

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " in "
            + bucket.getLocation()
            + " with RPO setting"
            + bucket.getRpo());
  }
}

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';

// The name of a dual-region location
// See this documentation for other valid locations:
// https://cloud.google.com/storage/docs/locations#location-dr
// const location = 'NAM4';

// Flag to enable turbo replication for this bucket
const rpo = 'ASYNC_TURBO';

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithTurboReplication() {
  // For default values see: https://cloud.google.com/storage/docs/locations and
  // https://cloud.google.com/storage/docs/storage-classes
  const [bucket] = await storage.createBucket(bucketName, {
    location,
    rpo,
  });

  console.log(
    `${bucket.name} created with the recovery point objective (RPO) set to ${rpo} in ${location}.`
  );
}

createBucketWithTurboReplication();

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Create a Cloud Storage bucket with the recovery point objective (RPO) set to `ASYNC_TURBO`.
 * The bucket must be a dual-region bucket for this setting to take effect.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 * @param string $location The Dual-Region location where you want your bucket to reside (e.g. "US-CENTRAL1+US-WEST1").
                                           Read more at https://cloud.google.com/storage/docs/locations#location-dr
 */
function create_bucket_turbo_replication($bucketName, $location = 'nam4')
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $rpo = 'ASYNC_TURBO';

    // providing a location which is a dual-region location
    // makes sure the locationType is set to 'dual-region' implicitly
    // we can pass 'locationType' => 'dual-region'
    // to make it explicit
    $bucket = $storage->createBucket($bucketName, [
        'location' => $location,
        'rpo' => $rpo
    ]);
    printf('Bucket with recovery point objective (RPO) set to \'ASYNC_TURBO\' created: %s' . PHP_EOL, $bucket->name());
}

Python

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


from google.cloud import storage
from google.cloud.storage.constants import RPO_ASYNC_TURBO


def create_bucket_turbo_replication(bucket_name):
    """Creates dual-region bucket with turbo replication enabled."""
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    bucket.location = "NAM4"
    bucket.rpo = RPO_ASYNC_TURBO
    bucket.create()

    print(f"{bucket.name} created with the recovery point objective (RPO) set to {bucket.rpo} in {bucket.location}.")

Ruby

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

def create_bucket_turbo_replication bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.create_bucket bucket_name,
                                  location: "ASIA1",
                                  rpo:      "ASYNC_TURBO"

  puts "Created bucket #{bucket.name} in #{bucket.location} with "
  + "the recovery point objective (RPO) set to #{bucket.rpo}."
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 that contains the settings for the bucket, which must include a name for the bucket. See the Buckets:Insert documentation for a complete list of settings. The following are common settings to include:

    {
  "name": "BUCKET_NAME",
  "rpo": "REPLICATION_TYPE",
  "location": "BUCKET_LOCATION",
  "storageClass": "STORAGE_CLASS",
  "iamConfiguration": {
    "uniformBucketLevelAccess": {
      "enabled": true
    },
  }
}

    Where:

    • BUCKET_NAME is the name you want to give your bucket, subject to naming requirements. For example, my-bucket.
    • REPLICATION_TYPE specifies the replication setting for dual- and multi-region buckets. The DEFAULT value represents default replication and is a valid option for dual- or multi-region buckets. ASYNC_TURBO represents turbo replication and is a valid option for most dual-region buckets. If not specified, default replication is the default replication setting. For the purposes of this example, use ASYNC_TURBO.
    • BUCKET_LOCATION is the location where you want to store your bucket's object data. Since you're creating a bucket with turbo replication enabled, and because a bucket's geographic location is immutable once created, specify a dual-region. For example, NAM4.
    • STORAGE_CLASS is the default storage class of your bucket. For example, NEARLINE.

  3. Use cURL to call the JSON API:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer OAUTH2_TOKEN" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b?project=PROJECT_ID"

    Where:

    • JSON_FILE_NAME is the path for the JSON file that you created in Step 2.
    • OAUTH2_TOKEN is the access token you generated in Step 1.
    • PROJECT_ID is the ID of the project with which your bucket will be associated. For example, my-project.

XML API

This feature cannot be managed through the XML API. Use the JSON API instead.

Monitor a bucket's turbo replication performance

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

    Go to Browser

  2. In the bucket list, click the name of the desired bucket.

  3. Click the Configuration tab.

  4. In the Replication row, click View replication metrics.

    If an object took longer than 15 minutes to replicate, the extra minutes are aggregated and displayed in the console as Number of minutes missing RPO. The console also tracks the number of completed object replications, shown as Object replications with turbo.

    For more information, see Understanding RTO and RPO.

What's next