Use cross-bucket replication

This page describes how to usecross-bucket replication, which usesStorage Transfer Service to copy new and updated objects asynchronously from asource bucket to a destination bucket. When you use cross-bucket replication,you create and manage replication jobs, which are a type of job inStorage Transfer Service.

Before you begin

To use cross-bucket replication, you must complete prerequisite steps. Forinstructions, refer toBefore you begin in the Storage Transfer Servicedocumentation.

Create a replication job

Console

When you create a cross-bucket replication job using theGoogle Cloud console, the Storage Transfer Service service agent isautomatically granted thestorage.legacyBucketOwner role on the sourcebucket and thestorage.legacyBucketWriter role on the destinationbucket.

When using the Google Cloud console, you can create a replication job forexisting buckets or for new buckets during the bucket creation process.

To create a replication job for a new bucket, follow the instructions forcreating a new bucket.

To create a replication job for an existing bucket, complete the followingsteps:

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the source bucket whose objectsyou want to replicate.

  3. On theBucket details page, click theConfiguration tab.

  4. Locate theCross-bucket replication option and clickEdit.

  5. In theEdit cross-bucket replication pane that opens, clickAdd a destination.

  6. In theChoose a destination section, select a destination bucket,then clickNext.

  7. In theChoose replication settings section, do the following:

    • Optional: To filter objects to replicate by object name prefix, select theReplicate objects based on prefix checkbox in theChoose which objects to replicate section.

      • To include objects by prefix, enter a prefix in theInclude objects with prefix section, thenclickAdd a prefix.

      • To exclude objects by prefix, enter a prefix in theExclude objects with prefix section, then clickAdd a prefix.

    • Optional: To set a storage class for replicated objects, select astorage class from the menu in theSet storage class for replicated objects section.

      If you skip this step, replicated objects use the destination bucket'sstorage class by default.

    1. ClickSave.

Command line

For Google Cloud CLI instructions on how to create a replication job,refer toCreate a replication job using the Google Cloud CLI.

REST APIs

JSON API

For JSON API instructions on how to create a replication job,refer toCreate a replication job using the JSON API.

To check the status of the replication job,view Cloud Logging for Storage Transfer Service logs.

List replication jobs

Console

You cannot list replication jobs using the Google Cloud console. SeeView replication job for instructions on how to view a singlereplication job at a time.

Command line

For Google Cloud CLI instructions on how to list replication jobs,refer toList replication jobs using the Google Cloud CLI.

REST APIs

JSON API

For JSON API instructions on how to list replication jobs,refer toList replication jobs using the JSON API.

View a replication job

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the source bucket whosecross-bucket replication job you want to view.

  3. On theBucket details page, click theConfiguration tab.

  4. Locate theCross-bucket replication option and clickEdit.

    TheEdit cross-bucket replication pane appears, which displaysthe replication job for each destination bucket.

On theBuckets page, you can view theReplication column, whichdisplays whether a bucket has a Turbo replication job or a cross-bucketreplication job running. For instructions on displaying theReplicationcolumn, seeShow columns.

Command line

For Google Cloud CLI instructions on how to view a replication job,refer toView a replication job using the Google Cloud CLI.

REST APIs

JSON API

For JSON API instructions on how to view a replication job,refer toView a replication job using the JSON API.

Update a replication job

You can update the following fields of a replication job:

  • The description of the replication job

  • The configuration for running a replication job

  • The configuration of notifications published to Pub/Sub

  • The logging behavior for replication job operations

  • The status of the replication job (whether it's enabled, disabled, or deleted)

Console

When using the Google Cloud console, you can only update a replicationjob by pausing or unpausing the job.

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the source bucket thatyou want to pause or unpause replicating.

  3. On theBucket details page, click theConfiguration tab.

  4. Locate theCross-bucket replication option and clickEdit.

  5. In theEdit cross-bucket replication pane that appears, clickPause orUnpause next to thereplication job you want to update.

Command line

For Google Cloud CLI instructions on how to update a replication job,refer toUpdate a replication job using the Google Cloud CLI.

REST APIs

JSON API

For JSON API instructions on how to update a replication job,refer toUpdate a replication job using the JSON API.

Delete a replication job

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the source bucket youwant to stop replicating.

  3. On theBucket details page, click theConfiguration tab.

  4. Locate theCross-bucket replication option and clickEdit.

  5. In theEdit cross-bucket replication pane that appears, clickDelete next to thereplication job you want to delete.

  6. In the dialogue that appears, clickConfirm.

Command line

For Google Cloud CLI instructions on how to delete a replication job,refer toDelete a replication job using the Google Cloud CLI.

REST APIs

JSON API

For JSON API instructions on how to delete a replication job,refer toDelete a replication job using the JSON API.

What's next

Monitor your replicated objects.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.