storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/docs/bucket/replication/README.md (about) 1 # Bucket Replication Guide [](https://slack.min.io) [](https://hub.docker.com/r/minio/minio/) 2 3 Bucket replication is designed to replicate selected objects in a bucket to a destination bucket. 4 5 The contents of this page have been migrated to the new [MinIO Baremetal Documentation: Bucket Replication](https://docs.min.io/minio/baremetal/replication/replication-overview.html#) page. The [Bucket Replication](https://docs.min.io/minio/baremetal/replication/replication-overview.html#) section includes dedicated tutorials for configuring one-way "Active-Passive" and two-way "Active-Active" bucket replication. Please update your bookmarks to use the new MinIO documentation, as this legacy documentation will be deprecated and removed in the future. 6 7 To replicate objects in a bucket to a destination bucket on a target site either in the same cluster or a different cluster, start by enabling [versioning](https://docs.minio.io/docs/minio-bucket-versioning-guide.html) for both source and destination buckets. Finally, the target site and the destination bucket need to be configured on the source MinIO server. 8 9 ## Highlights 10 - Supports source and destination buckets to have the same name unlike AWS S3, addresses variety of usecases such as *Splunk*, *Veeam* site to site DR. 11 - Supports object locking/retention across source and destination buckets natively out of the box, unlike AWS S3. 12 - Simpler implementation than [AWS S3 Bucket Replication Config](https://docs.aws.amazon.com/AmazonS3/latest/dev/replication-add-config.html) with requirements such as IAM Role, AccessControlTranslation, Metrics and SourceSelectionCriteria are not needed with MinIO. 13 - Active-Active replication 14 15 ## How to use? 16 Ensure that versioning is enabled on the source and target buckets with `mc version` command. If object locking is required, the buckets should have been created with `mc mb --with-lock` 17 18 Create a replication target on the source cluster as shown below: 19 20 ``` 21 mc admin bucket remote add myminio/srcbucket https://accessKey:secretKey@replica-endpoint:9000/destbucket --service replication --region us-east-1 22 Role ARN = 'arn:minio:replication:us-east-1:c5be6b16-769d-432a-9ef1-4567081f3566:destbucket' 23 ``` 24 25 > The user running the above command needs *s3:GetReplicationConfiguration* and *s3:GetBucketVersioning* permission on the source cluster. We do not recommend running root credentials/super admin with replication, instead create a dedicated user. The access credentials used at the destination requires *s3:ReplicateObject* permission. 26 27 The following minimal permission policy is needed by admin user setting up replication on the `source`: 28 ``` 29 { 30 "Version": "2012-10-17", 31 "Statement": [ 32 { 33 "Action": [ 34 "admin:SetBucketTarget", 35 "admin:GetBucketTarget" 36 ], 37 "Effect": "Allow", 38 "Sid": "" 39 }, 40 { 41 "Effect": "Allow", 42 "Action": [ 43 "s3:GetReplicationConfiguration", 44 "s3:PutReplicationConfiguration", 45 "s3:ListBucket", 46 "s3:ListBucketMultipartUploads", 47 "s3:GetBucketLocation", 48 "s3:GetBucketVersioning" 49 ], 50 "Resource": [ 51 "arn:aws:s3:::srcbucket" 52 ] 53 } 54 ] 55 } 56 ``` 57 58 The access key provided for the replication *target* cluster should have these minimal permissions: 59 ``` 60 { 61 "Version": "2012-10-17", 62 "Statement": [ 63 { 64 "Effect": "Allow", 65 "Action": [ 66 "s3:GetReplicationConfiguration", 67 "s3:ListBucket", 68 "s3:ListBucketMultipartUploads", 69 "s3:GetBucketLocation", 70 "s3:GetBucketVersioning", 71 "s3:GetBucketObjectLockConfiguration" 72 ], 73 "Resource": [ 74 "arn:aws:s3:::destbucket" 75 ] 76 }, 77 { 78 "Effect": "Allow", 79 "Action": [ 80 "s3:GetReplicationConfiguration", 81 "s3:ReplicateTags", 82 "s3:AbortMultipartUpload", 83 "s3:GetObject", 84 "s3:GetObjectVersion", 85 "s3:GetObjectVersionTagging", 86 "s3:PutObject", 87 "s3:DeleteObject", 88 "s3:ReplicateObject", 89 "s3:ReplicateDelete" 90 ], 91 "Resource": [ 92 "arn:aws:s3:::destbucket/*" 93 ] 94 } 95 ] 96 } 97 ``` 98 Please note that the permissions required by the admin user on the target cluster can be more fine grained to exclude permissions like "s3:ReplicateDelete", "s3:GetBucketObjectLockConfiguration" etc depending on whether delete replication rules are set up or if object locking is disabled on `destbucket`. The above policies assume that replication of objects, tags and delete marker replication are all enabled on object lock enabled buckets. A sample script to setup replication is provided [here](https://github.com/minio/minio/blob/master/docs/bucket/replication/setup_replication.sh) 99 100 Once successfully created and authorized, the `mc admin bucket remote add` command generates a replication target ARN. This command lists all the currently authorized replication targets: 101 ``` 102 mc admin bucket remote ls myminio/srcbucket --service "replication" 103 Role ARN = 'arn:minio:replication:us-east-1:c5be6b16-769d-432a-9ef1-4567081f3566:destbucket' 104 ``` 105 106 The replication configuration can now be added to the source bucket by applying the json file with replication configuration. The Role ARN above is passed in as a json element in the configuration. 107 108 ```json 109 { 110 "Role" :"arn:minio:replication:us-east-1:c5be6b16-769d-432a-9ef1-4567081f3566:destbucket", 111 "Rules": [ 112 { 113 "Status": "Enabled", 114 "Priority": 1, 115 "DeleteMarkerReplication": { "Status": "Disabled" }, 116 "DeleteReplication": { "Status": "Disabled" }, 117 "Filter" : { 118 "And": { 119 "Prefix": "Tax", 120 "Tags": [ 121 { 122 "Key": "Year", 123 "Value": "2019" 124 }, 125 { 126 "Key": "Company", 127 "Value": "AcmeCorp" 128 } 129 ] 130 } 131 }, 132 "Destination": { 133 "Bucket": "arn:aws:s3:::destbucket", 134 "StorageClass": "STANDARD" 135 } 136 } 137 ] 138 } 139 ``` 140 141 The replication configuration follows [AWS S3 Spec](https://docs.aws.amazon.com/AmazonS3/latest/dev/replication-add-config.html). Any objects uploaded to the source bucket that meet replication criteria will now be automatically replicated by the MinIO server to the remote destination bucket. Replication can be disabled at any time by disabling specific rules in the configuration or deleting the replication configuration entirely. 142 143 When object locking is used in conjunction with replication, both source and destination buckets needs to have [object locking](https://docs.min.io/docs/minio-bucket-object-lock-guide.html) enabled. Similarly objects encrypted on the server side, will be replicated if destination also supports encryption. 144 145 Replication status can be seen in the metadata on the source and destination objects. On the source side, the `X-Amz-Replication-Status` changes from `PENDING` to `COMPLETED` or `FAILED` after replication attempt either succeeded or failed respectively. On the destination side, a `X-Amz-Replication-Status` status of `REPLICA` indicates that the object was replicated successfully. Any replication failures are automatically re-attempted during a periodic disk scanner cycle. 146 147 To perform bi-directional replication, repeat the above process on the target site - this time setting the source bucket as the replication target. It is recommended that replication be run in a system with atleast two CPU's available to the process, so that replication can run in its own thread. 148 149  150 151  152 153 ## MinIO Extension 154 ### Replicating Deletes 155 156 Delete marker replication is allowed in [AWS V1 Configuration](https://aws.amazon.com/blogs/storage/managing-delete-marker-replication-in-amazon-s3/) but not in V2 configuration. The MinIO implementation above is based on V2 configuration, however it has been extended to allow both DeleteMarker replication and replication of versioned deletes with the `DeleteMarkerReplication` and `DeleteReplication` fields in the replication configuration above. By default, this is set to `Disabled` unless the user specifies it while adding a replication rule. 157 158 When an object is deleted from the source bucket, the corresponding replica version will be marked deleted if delete marker replication is enabled in the replication configuration. Replication of deletes that specify a version id (a.k.a hard deletes) can be enabled by setting the `DeleteReplication` status to enabled in the replication configuration. This is a MinIO specific extension that can be enabled using the `mc replicate add` or `mc replicate edit` command with the --replicate "delete" flag. 159 160 Note that due to this extension behavior, AWS SDK's may not support the extension functionality pertaining to replicating versioned deletes. 161 162 To add a replication rule allowing both delete marker replication, versioned delete replication or both specify the --replicate flag with comma separated values as in the example below. 163 164 Additional permission of "s3:ReplicateDelete" action would need to be specified on the access key configured for the target cluster if Delete Marker replication or versioned delete replication is enabled. 165 ``` 166 mc replicate add myminio/srcbucket/Tax --priority 1 --arn "arn:minio:replication:us-east-1:c5be6b16-769d-432a-9ef1-4567081f3566:destbucket" --tags "Year=2019&Company=AcmeCorp" --storage-class "STANDARD" --remote-bucket "destbucket" --replicate "delete,delete-marker" 167 Replication configuration applied successfully to myminio/srcbucket. 168 ``` 169 170 > NOTE: Both source and target instance need to be upgraded to latest release to take advantage of Delete marker replication. 171 172 Status of delete marker replication can be viewed by doing a GET/HEAD on the object version - it will return a `X-Minio-Replication-DeleteMarker-Status` header and http response code of `405`. In the case of permanent deletes, if the delete replication is pending or failed to propagate to the target cluster, GET/HEAD will return additional `X-Minio-Replication-Delete-Status` header and a http response code of `405`. 173 174  175 176 The status of replication can be monitored by configuring event notifications on the source and target buckets using `mc event add`.On the source side, the `s3:PutObject`, `s3:Replication:OperationCompletedReplication` and `s3:Replication:OperationFailedReplication` events show the status of replication in the `X-Amz-Replication-Status` metadata. 177 178 On the target bucket, `s3:PutObject` event shows `X-Amz-Replication-Status` status of `REPLICA` in the metadata. Additional metrics to monitor backlog state for the purpose of bandwidth management and resource allocation are exposed via Prometheus - see https://github.com/minio/minio/blob/master/docs/metrics/prometheus/list.md for more details. 179 180 ### Sync/Async Replication 181 By default, replication is completed asynchronously. If synchronous replication is desired, set the --sync flag while adding a 182 remote replication target using the `mc admin bucket remote add` command 183 ``` 184 mc admin bucket remote add myminio/srcbucket https://accessKey:secretKey@replica-endpoint:9000/destbucket --service replication --region us-east-1 --sync --healthcheck-seconds 100 185 ``` 186 187 ## Explore Further 188 - [MinIO Bucket Replication Design](https://raw.githubusercontent.com/minio/minio/master/docs/bucket/replication/DESIGN.md) 189 - [MinIO Bucket Versioning Implementation](https://docs.minio.io/docs/minio-bucket-versioning-guide.html) 190 - [MinIO Client Quickstart Guide](https://docs.minio.io/docs/minio-client-quickstart-guide.html)