# Use `PutBucketReplication` with an AWS SDK or CLI The following code examples show how to use `PutBucketReplication`. ------ #### [ CLI ] **AWS CLI** **To configure replication for an S3 bucket** The following `put-bucket-replication` example applies a replication configuration to the specified S3 bucket. ``` aws s3api put-bucket-replication \ --bucket amzn-s3-demo-bucket1 \ --replication-configuration file://replication.json ``` Contents of `replication.json`: ``` { "Role": "arn:aws:iam::123456789012:role/s3-replication-role", "Rules": [ { "Status": "Enabled", "Priority": 1, "DeleteMarkerReplication": { "Status": "Disabled" }, "Filter" : { "Prefix": ""}, "Destination": { "Bucket": "arn:aws:s3:::amzn-s3-demo-bucket2" } } ] } ``` The destination bucket must have versioning enabled. The specified role must have permission to write to the destination bucket and have a trust relationship that allows Amazon S3 to assume the role. Example role permission policy: ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetReplicationConfiguration", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket1" ] }, { "Effect": "Allow", "Action": [ "s3:GetObjectVersion", "s3:GetObjectVersionAcl", "s3:GetObjectVersionTagging" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket1/*" ] }, { "Effect": "Allow", "Action": [ "s3:ReplicateObject", "s3:ReplicateDelete", "s3:ReplicateTags" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket2/*" } ] } ``` Example trust relationship policy: ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` This command produces no output. For more information, see [This is the topic title](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/enable-replication.html) in the *Amazon Simple Storage Service Console User Guide*. + For API details, see [PutBucketReplication](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-bucket-replication.html) in *AWS CLI Command Reference*. ------ #### [ Java ] **SDK for Java 2.x** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3#code-examples). ``` /** * Sets the replication configuration for an Amazon S3 bucket. * * @param s3Client the S3Client instance to use for the operation * @param sourceBucketName the name of the source bucket * @param destBucketName the name of the destination bucket * @param destinationBucketARN the Amazon Resource Name (ARN) of the destination bucket * @param roleARN the ARN of the IAM role to use for the replication configuration */ public static void setReplication(S3Client s3Client, String sourceBucketName, String destBucketName, String destinationBucketARN, String roleARN) { try { Destination destination = Destination.builder() .bucket(destinationBucketARN) .storageClass(StorageClass.STANDARD) .build(); // Define a prefix filter for replication. ReplicationRuleFilter ruleFilter = ReplicationRuleFilter.builder() .prefix("documents/") .build(); // Define delete marker replication setting. DeleteMarkerReplication deleteMarkerReplication = DeleteMarkerReplication.builder() .status(DeleteMarkerReplicationStatus.DISABLED) .build(); // Create the replication rule. ReplicationRule replicationRule = ReplicationRule.builder() .priority(1) .filter(ruleFilter) .status(ReplicationRuleStatus.ENABLED) .deleteMarkerReplication(deleteMarkerReplication) .destination(destination) .build(); List replicationRuleList = new ArrayList<>(); replicationRuleList.add(replicationRule); // Define the replication configuration with IAM role. ReplicationConfiguration configuration = ReplicationConfiguration.builder() .role(roleARN) .rules(replicationRuleList) .build(); // Apply the replication configuration to the source bucket. PutBucketReplicationRequest replicationRequest = PutBucketReplicationRequest.builder() .bucket(sourceBucketName) .replicationConfiguration(configuration) .build(); s3Client.putBucketReplication(replicationRequest); System.out.println("Replication configuration set successfully."); } catch (IllegalArgumentException e) { System.err.println("Configuration error: " + e.getMessage()); } catch (S3Exception e) { System.err.println("S3 Exception: " + e.awsErrorDetails().errorMessage()); System.err.println("Status Code: " + e.statusCode()); System.err.println("Error Code: " + e.awsErrorDetails().errorCode()); } catch (SdkException e) { System.err.println("SDK Exception: " + e.getMessage()); } } ``` + For API details, see [PutBucketReplication](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutBucketReplication) in *AWS SDK for Java 2.x API Reference*. ------ #### [ PowerShell ] **Tools for PowerShell V4** **Example 1: This example sets a replication configuration with a single rule enabling replication to the 'amzn-s3-demo-bucket' bucket any new objects created with the key name prefix "TaxDocs" in the bucket 'amzn-s3-demo-bucket'.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Enabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1 } Write-S3BucketReplication @params ``` **Example 2: This example sets a replication configuration with multiple rules enabling replication to the 'amzn-s3-demo-bucket' bucket any new objects created with either the key name prefix "TaxDocs" or "OtherDocs". The key prefixes must not overlap.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Enabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $rule2 = New-Object Amazon.S3.Model.ReplicationRule $rule2.ID = "Rule-2" $rule2.Status = "Enabled" $rule2.Prefix = "OtherDocs" $rule2.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1,$rule2 } Write-S3BucketReplication @params ``` **Example 3: This example updates the replication configuration on the specified bucket to disable the rule controlling replication of objects with the key name prefix "TaxDocs" to the bucket 'amzn-s3-demo-bucket'.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Disabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1 } Write-S3BucketReplication @params ``` + For API details, see [PutBucketReplication](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*. **Tools for PowerShell V5** **Example 1: This example sets a replication configuration with a single rule enabling replication to the 'amzn-s3-demo-bucket' bucket any new objects created with the key name prefix "TaxDocs" in the bucket 'amzn-s3-demo-bucket'.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Enabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1 } Write-S3BucketReplication @params ``` **Example 2: This example sets a replication configuration with multiple rules enabling replication to the 'amzn-s3-demo-bucket' bucket any new objects created with either the key name prefix "TaxDocs" or "OtherDocs". The key prefixes must not overlap.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Enabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $rule2 = New-Object Amazon.S3.Model.ReplicationRule $rule2.ID = "Rule-2" $rule2.Status = "Enabled" $rule2.Prefix = "OtherDocs" $rule2.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1,$rule2 } Write-S3BucketReplication @params ``` **Example 3: This example updates the replication configuration on the specified bucket to disable the rule controlling replication of objects with the key name prefix "TaxDocs" to the bucket 'amzn-s3-demo-bucket'.** ``` $rule1 = New-Object Amazon.S3.Model.ReplicationRule $rule1.ID = "Rule-1" $rule1.Status = "Disabled" $rule1.Prefix = "TaxDocs" $rule1.Destination = @{ BucketArn = "arn:aws:s3:::amzn-s3-demo-destination-bucket" } $params = @{ BucketName = "amzn-s3-demo-bucket" Configuration_Role = "arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3" Configuration_Rule = $rule1 } Write-S3BucketReplication @params ``` + For API details, see [PutBucketReplication](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*. ------ For a complete list of AWS SDK developer guides and code examples, see [Developing with Amazon S3 using the AWS SDKs](sdk-general-information-section.md). This topic also includes information about getting started and details about previous SDK versions.