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
- In the Google Cloud console, go to the Cloud Storage Browser page.
In the bucket list, click the name of the bucket you want to verify.
Click the Configuration tab.
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
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- 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.
Use
cURL
to call the JSON API with aGET
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 valueASYNC_TURBO
indicates that turbo replication is enabled.DEFAULT
indicates that default replication is applied. Therpo
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
- In the Google Cloud console, go to the Cloud Storage Browser page.
In the bucket list, click the name of the desired bucket.
Click the Configuration tab.
In the Replication row, click
Edit.The window that appears indicates whether you are about to Enable turbo replication or Disable turbo replication.
Click Save to confirm the new setting.
Command line
Use the gsutil rpo set
command:
gsutil rpo set STATE gs://BUCKET_NAME/
Where:
STATE
isASYNC_TURBO
for enabling Turbo Replication orDEFAULT
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
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample enables turbo replication on a bucket: The following sample enables default replication on a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- 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.
Create a JSON file that contains the following information:
{ "rpo": "STATE" }
Where
STATE
isASYNC_TURBO
for enabling Turbo Replication orDEFAULT
for disabling Turbo Replication.Use
cURL
to call the JSON API with aPATCH
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
- In the Google Cloud console, go to the Cloud Storage Browser page.
Click Create bucket.
On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
For Name your bucket, enter a name that meets the bucket naming requirements.
For Choose where to store your data, next to Location type, choose Dual-region and select the Add turbo replication checkbox.
For Location, select one of the available dual-regions.
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.
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.
For Advanced settings (optional), add bucket labels, set a retention policy, and choose an encryption method.
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. TheDEFAULT
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, useASYNC_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
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- 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.
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. TheDEFAULT
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, useASYNC_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
.
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
- In the Google Cloud console, go to the Cloud Storage Browser page.
In the bucket list, click the name of the desired bucket.
Click the Configuration tab.
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
- Learn more about turbo replication.
- Learn more about turbo replication pricing or see a pricing example.