Table of Contents
The procedure on this page creates a new bucket replication rule for one-way synchronization of objects between MinIO buckets.
To configure replication between arbitrary S3-compatible services, use mc mirror
.
To configure two-way “active-active” replication between MinIO clusters, see Enable Two-Way Server-Side Bucket Replication.
To configure multi-site “active-active” replication between MinIO clusters, see Enable Multi-Site Server-Side Bucket Replication
See also
Use the mc replicate edit
command to modify an existing replication rule.
Use the mc replicate edit
command with the --state "disable"
flag to disable an existing replication rule.
Use the mc replicate rm
command to remove an existing replication rule.
Bucket replication requires specific permissions on the source and destination deployments to configure and enable replication rules.
The following policy provides permissions for configuring and enabling replication on a deployment.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"admin:SetBucketTarget",
"admin:GetBucketTarget"
],
"Effect": "Allow",
"Sid": "EnableRemoteBucketConfiguration"
},
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:GetBucketLocation",
"s3:GetBucketVersioning",
"s3:GetObjectRetention",
"s3:GetObjectLegalHold",
"s3:PutReplicationConfiguration"
],
"Resource": [
"arn:aws:s3:::*"
],
"Sid": "EnableReplicationRuleConfiguration"
}
]
}
The "EnableRemoteBucketConfiguration"
statement grants permission for creating a remote target for supporting replication.
The "EnableReplicationRuleConfiguration"
statement grants permission for creating replication rules on a bucket. The "arn:aws:s3:::*
resource applies the replication permissions to any bucket on the source deployment. You can restrict the user policy to specific buckets as-needed.
The following code creates a MinIO-managed user with the necessary policy. Replace the TARGET
with the alias of the MinIO deployment on which you are configuring replication:
wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationAdminPolicy.json | \
mc admin policy add TARGET ReplicationAdminPolicy /dev/stdin
mc admin user add TARGET ReplicationAdmin LongRandomSecretKey
mc admin policy set TARGET ReplicationAdminPolicy user=ReplicationAdmin
MinIO deployments configured for Active Directory/LDAP or OpenID Connect user management should instead create a dedicated service account for bucket replication.
The following policy provides permissions for enabling synchronization of replicated data into the deployment.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:GetBucketLocation",
"s3:GetBucketVersioning",
"s3:GetBucketObjectLockConfiguration",
"s3:GetEncryptionConfiguration"
],
"Resource": [
"arn:aws:s3:::*"
],
"Sid": "EnableReplicationOnBucket"
},
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ReplicateTags",
"s3:AbortMultipartUpload",
"s3:GetObject",
"s3:GetObjectVersion",
"s3:GetObjectVersionTagging",
"s3:PutObject",
"s3:PutObjectRetention",
"s3:PutBucketObjectLockConfiguration",
"s3:PutObjectLegalHold",
"s3:DeleteObject",
"s3:ReplicateObject",
"s3:ReplicateDelete"
],
"Resource": [
"arn:aws:s3:::*"
],
"Sid": "EnableReplicatingDataIntoBucket"
}
]
}
The "EnableReplicationOnBucket"
statement grants permission for a remote target to retrieve bucket-level configuration for supporting replication operations on all buckets in the MinIO deployment. To restrict the policy to specific buckets, specify those buckets as an element in the Resource
array similar to "arn:aws:s3:::bucketName"
.
The "EnableReplicatingDataIntoBucket"
statement grants permission for a remote target to synchronize data into any bucket in the MinIO deployment. To restrict the policy to specific buckets, specify those buckets as an element in the Resource
array similar to "arn:aws:s3:::bucketName/*"
.
The following code creates a MinIO-managed user with the necessary policy. Replace the TARGET
with the alias of the MinIO deployment on which you are configuring replication:
wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationRemoteUserPolicy.json | \
mc admin policy add TARGET ReplicationRemoteUserPolicy /dev/stdin
mc admin user add TARGET ReplicationRemoteUser LongRandomSecretKey
mc admin policy set TARGET ReplicationRemoteUserPolicy user=ReplicationRemoteUser
MinIO deployments configured for Active Directory/LDAP or OpenID Connect user management should instead create a dedicated service account for bucket replication.
See mc admin user
, mc admin user svcacct
, and mc admin policy
for more complete documentation on adding users, service accounts, and policies to a MinIO deployment.
MinIO supports replication of objects encrypted using SSE-KMS and SSE-S3:
For objects encrypted using SSE-KMS, MinIO requires that the target bucket support SSE-KMS encryption of objects using the same key names used to encrypt objects on the source bucket.
For objects encrypted using SSE-S3, MinIO requires that the target bucket also support SSE-S3 encryption of objects regardless of key name.
As part of the replication process, MinIO decrypts the object on the source bucket and transmits the unencrypted object over the network. The destination MinIO deployment then re-encrypts the object using the encryption settings from the target. MinIO therefore strongly recommends enabling TLS on both source and destination deployments to ensure the safety of objects during transmission.
MinIO does not support replicating client-side encrypted objects (SSE-C).
MinIO server-side replication only works between MinIO deployments. Both the source and destination deployments must run MinIO.
To configure replication between arbitrary S3-compatible services,
use mc mirror
.
MinIO relies on the immutability protections provided by versioning to support replication and resynchronization.
Use mc version info
to validate the versioning status of both the healthy source and unhealthy target buckets. Use the mc version enable
command to enable versioning as necessary.
MinIO supports replicating objects held under WORM Locking. Both replication buckets must have object locking enabled for MinIO to replicate the locked object. For active-active configuration, MinIO recommends using the same retention rules on both buckets to ensure consistent behavior across sites.
You must enable object locking during bucket creation as per S3 behavior. You can then configure object retention rules at any time. Configure the necessary rules on the unhealthy target bucket prior to beginning this procedure.
MinIO supports automatically replicating existing objects in a bucket.
MinIO requires explicitly enabling replication of existing objects using the mc replicate add --replicate
or mc replicate edit --replicate
and including the existing-objects
replication feature flag. This procedure includes the required flags for enabling replication of existing objects.
MinIO supports replicating S3 DELETE
operations onto the target bucket. Specifically, MinIO can replicate versioning Delete Markers and the deletion of specific versioned objects:
For delete operations on an object, MinIO replication also creates the delete marker on the target bucket.
For delete operations on versions of an object, MinIO replication also deletes those versions on the target bucket.
MinIO requires explicitly enabling replication of delete operations using the mc replicate add --replicate
or mc replicate edit --replicate
. This procedure includes the required flags for enabling replication of delete operations and delete markers.
MinIO does not replicate delete operations resulting from the application of lifecycle management expiration rules.
See Replication of Delete Operations for more complete documentation.
MinIO supports configuring multiple remote targets per bucket or bucket prefix. For example, you can configure a bucket to replicate data to two or more remote MinIO deployments, where one deployment is a 1:1 copy (replication of all operations including deletions) and another is a full historical record (replication of only non-destructive write operations).
This procedure documents one-way replication to a single remote MinIO deployment. You can repeat this tutorial for multiple remote targets for a single bucket.
This procedure uses the aliases SOURCE
and REMOTE
to reference each MinIO deployment being configured for replication. Replace these values with the appropriate alias for your target MinIO deployments.
This procedure assumes each alias corresponds to a user with the necessary replication permissions.
Use the mc admin bucket remote add
command to create a replication target for the destination cluster. MinIO supports one remote target per destination bucket. You cannot create multiple remote targets for the same destination bucket.
mc admin bucket remote add SOURCE/BUCKET \
https://ReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/BUCKET \
--service "replication"
[--sync]
Replace BUCKET
with the name of the bucket on the SOURCE
deployment to use as the replication source. Replace SOURCE
with the alias of the MinIO deployment on which you are configuring replication.
Replace HOSTNAME
with the URL of the REMOTE
cluster.
Replace BUCKET
with the name of the bucket on the REMOTE
deployment to use as the replication destination.
Include the --sync
option to enable synchronous replication. Omit the option to use the default of asynchronous replication. See the reference documentation for mc admin bucket remote add
for more information on synchronous vs asynchronous replication before using this parameter.
The command returns an ARN similar to the following:
Role ARN = 'arn:minio:replication::<UUID>:BUCKET'
Copy the ARN string for use in the next step.
Use the mc replicate add
command to add the new server-side
replication rule to the source MinIO cluster.
mc replicate add SOURCE/BUCKET \
--remote-bucket 'arn:minio:replication::<UUID>:BUCKET' \
--replicate "delete,delete-marker,existing-objects"
Replace BUCKET
with the name of the bucket on the SOURCE
deployment to use as the replication source. Replace SOURCE
with the alias of the MinIO deployment on which you are configuring replication. The name must match the bucket specified when creating the remote target in the previous step.
Replace the --remote-bucket
value with the ARN returned in the previous step. Ensure you specify the ARN created on the SOURCE
deployment. You can use mc admin bucket remote ls
to list all remote ARNs configured on the deployment.
The --replicate "delete,delete-marker,existing-objects"
flag enables the following replication features:
See mc replicate add --replicate
for more complete documentation. Omit these fields to disable replication of delete operations or replication of existing objects respectively.
Specify any other supported optional arguments for mc replicate add
.
Use mc cp
to copy a new object to the source bucket.
mc cp ~/foo.txt SOURCE/BUCKET
Use mc ls
to verify the object exists on the destination bucket:
mc ls TARGET/BUCKET
This work is licensed under a Creative Commons Attribution 4.0 International License.
©2020-Present, MinIO, Inc.