Managing turbo replication

Preview

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Go to concepts

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

Check a bucket's replication status

To check whether an existing bucket has turbo replication enabled, complete the following:

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.

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

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.

Enable turbo replication

To enable turbo replication on an existing dual-region bucket, complete the following:

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

3. Click the Configuration tab.

4. In the Replication row, next to Default, click Edit.

5. In the Enable turbo replication window, click Save.

gsutil

Use the gsutil rpo set ASYNC_TURBO command:

gsutil rpo set ASYNC_TURBO gs://BUCKET_NAME/

Where:

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

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": "ASYNC_TURBO"
   }

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

   curl -X PATCH --data-binary @JSON_FILE_NAME.json \
     -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 and name of the JSON 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.

   If the request is successful, no response is returned.

Disable turbo replication

To disable turbo replication on an existing dual-region bucket, complete the following:

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

3. Click the Configuration tab.

4. In the Replication row, next to Turbo, click Edit.

5. In the Disable turbo replication window, click Save.

gsutil

Use the gsutil rpo set DEFAULT command:

gsutil rpo set DEFAULT gs://BUCKET_NAME/

Where:

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

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": "DEFAULT"
   }

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

   curl -X PATCH --data-binary @JSON_FILE_NAME.json \
     -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 and name of the JSON 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.

   If the request is successful, no response is returned.

Create a dual-region bucket with turbo replication

Note: A bucket's name and geographic location are non-editable metadata. If you need to designate a specific geographic location, you must specify the location at bucket creation.

Complete the following steps to create a new dual-region bucket with turbo replication enabled:

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.

      Note: The Monthly cost estimate panel in the right pane estimates the bucket's monthly costs based on your selected storage class and location, as well as your expected data size and operations.

   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.

gsutil

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

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 specificed, 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.json \
    -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 name of the JSON file 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.

What's next

• Learn more about turbo replication.
• Learn more about turbo replication pricing or see a pricing example.
• Learn more about bandwidth monitoring.