This page describes how to use the turbo replication feature on a dual-region bucket.
Required permissions
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.
Client libraries
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 and require permissions as listed in IAM permissions for JSON methods. To see which JSON API methods are invoked when you make requests using a client library, log the raw requests.
For a list of relevant IAM 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.
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 Buckets 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
gcloud
Use the gcloud storage buckets update
command with the --rpo
flag:
gcloud storage buckets update gs://BUCKET_NAME --rpo=STATE
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.STATE
isASYNC_TURBO
for enabling Turbo Replication orDEFAULT
for disabling Turbo Replication.
If successful, the response looks like:
Updating gs://my-bucket/... Completed 1
gsutil
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.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
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 Buckets 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
gcloud
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(rpo)"
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
If successful, the response looks like the following example:
rpo: ASYNC_TURBO
gsutil
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
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
Monitor a bucket's turbo replication performance
- In the Google Cloud console, go to the Cloud Storage Buckets 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 Google Cloud console as Number of minutes missing RPO. The Google Cloud console also tracks the number of completed object replications, shown as Object replications with turbo.
For more information, see Turbo replication performance monitoring.
What's next
- Learn more about turbo replication.
- Learn more about turbo replication pricing or see a pricing example.