The procedure on this page creates a new bucket replication rule for two-way “active-active” synchronization of objects between MinIO buckets.
To configure replication between arbitrary S3-compatible services, use
To configure one-way “active-passive” replication between MinIO clusters, see Enable One-Way Server-Side Bucket Replication.
To configure multi-site “active-active” replication between MinIO clusters, see Enable Multi-Site Server-Side Bucket Replication.
This tutorial covers configuring Active-Active replication between two MinIO clusters. For a tutorial on multi-site replication between three or more MinIO clusters, see Enable Multi-Site Server-Side Bucket Replication.
You must meet all of the basic requirements for bucket replication described in Bucket Replication Requirements.
In addition, to set up active-active bucket replication, you must meet the following additional requirements:
You must have network access and login credentials with required permissions to both deployment to set up active-active bucket replication.
If using the command line, use the
mc alias set command to create an alias for both MinIO deployments.
Alias creation requires specifying an access key for a user on the deployment.
This user must have permission to create and manage users and policies on the deployment.
Specifically, ensure the user has at minimum:
Use Consistent Replication Settings
MinIO supports customizing the replication configuration to enable or disable the following replication behaviors:
Replication of delete operations
Replication of delete markers
Replication of existing objects
Replication of metadata-only changes
When configuring replication rules for a bucket, ensure that both MinIO deployments participating in active-active replication use the same replication behaviors to ensure consistent and predictable synchronization of objects.
Replication of Existing Objects
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 update --replicate and including the
existing-objects replication feature flag.
This procedure includes the required flags for enabling replication of existing objects.
Replication of Delete Operations
MinIO supports replicating 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 update --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. Configure matching expiration rules on both the source and destination bucket to ensure consistent application of object expiration.
See Replication of Delete Operations for more complete documentation.
MinIO supports configuring multiple remote targets per bucket or bucket prefix. This enables configuring multi-site active-active replication between MinIO deployments.
This procedure covers active-active replication between two MinIO sites. You can repeat this procedure for each “pair” of MinIO deployments in the replication mesh. For a dedicated tutorial, see Enable Multi-Site Server-Side Bucket Replication.
Log in to the MinIO Console for the deployment
Select the Manage button for the bucket to replicate
Select the Replication section
Select Add Replication Rule +
Complete the requested information:
Enter a number value to indicate the order in which to process replication rules for the bucket. 1 indicates the highest importance.
The URL of the deployment to replicate data to.
Leave the toggle in the ON position if the destination deployment uses TLS. Otherwise, move the toggle to the OFF position.
The user name to use on the destination deployment. The user must have write access to the bucket to replicate to.
The password for the provided Access Key.
The bucket at the destination to write the data to. The target bucket may have the same name as the origin bucket, depending on the destination bucket location.
The AWS resource region location of the destination deployment.
Leave the default selection of Asynchronous to allow MinIO to replicate data after the write operation completes on the origin ment. Select Synchronous to attempt to complete the replication of the object during its write operation.
While synchronous replication may result in more reliable synchronization between the origin and destination buckets, it may also increase the time of each write operation.
Specify the maximum amount of bandwidth the replication process can use while replicating data. Enter a number and select a data unit.
Health Check Duration
The maximum length of time in seconds MinIO should spend verifying the health of the replicated data on the destination bucket.
The class of storage to use on the destination deployment for the replicated data. Valid values are either
Limit which objects to replicate from the bucket by Prefix or tags. If you enter multiple tags, the objects must match all tag values.
Leave selected to also replicate the object’s metadata file. Otherwise, move the toggle to the Off position.
Leave selected to also replicate MinIO’s indication that an object has been deleted and should also be marked deleted at the action bucket. Otherwise, move the toggle to the Off position to prevent marking the object as deleted in the destination bucket.
Leave selected to allow replication of the deletion of versions of an object. Otherwise, move the toggle to the Off position to not replicate deletion of object versions.
Select Save to finish adding the replication rule
Repeat the above steps to create a rule in the other direction.
Go to the Console for the destination deployment used above.
Create a replication rule from the second deployment back to the first deployment. The first deployment becomes the target deployment for the rule on the second deployment.
Go to the Buckets section of the MinIO Console
Select the Browse button for the bucket you added replication to
Select the Upload button to add a new object to the bucket
Select Upload File
Use the interface to add a new object to the bucket
Go to the other deployment’s console and select the destination bucket defined in the replication
This procedure creates two-way, active-active replication between two MinIO deployments.
This procedure assumes you have already defined an alias for each deployment as a user with the necessary replication permissions.
Changed in version RELEASE.2022-12-24T15-21-38Z:
mc replicate add automatically creates the necessary replication targets, removing the need for using the deprecated
mc admin remote bucket add command.
This procedure only documents the procedure as of that release.
mc replicate add command to add a new replication rule to each MinIO deployment.
mc replicate add ALIAS/BUCKET \ --remote-bucket 'https://USER:PASSWORD@HOSTNAME:PORT/BUCKET' \ --replicate "delete,delete-marker,existing-objects"
ALIASwith the alias of the origin MinIO deployment. The name must match the bucket specified when creating the remote target in the previous step.
BUCKETwith the name of the bucket to replicate from on the origin deployment.
--remote-bucketto specify the remote MinIO deployment and bucket to which the
USER:PASSWORDmust correspond to a user on the remote deployment with the necessary replication permissions.
HOSTNAME:PORTmust resolve to a reachable MinIO instance on the remote deployment. The
BUCKETmust exist and otherwise meet all other replication requirements.
--replicate "delete,delete-marker,existing-objects"flag enables the following replication features:
mc replicate add --replicatefor more complete documentation. Omit any field to disable replication of that component.
Specify any other supported optional arguments for
mc replicate add.
Repeat this step on the other MinIO deployment.
--remote-bucket values to correspond to the first deployment.
You should have two replication rules configured at the conclusion of this step - one created on each deployment that points to the bucket on the other deployment.
mc replicate ls command to verify the created replication rules.
mc cp to copy a new object to the replicated bucket on one of the deployments.
mc cp ~/foo.txt ALIAS/BUCKET
mc ls to verify the object exists on the destination bucket:
mc ls ALIAS/BUCKET
Repeat this test by copying another object to the second deployment and verifying the object replicates to the first deployment.
Once both objects exist on both deployments, you have successfully set up two-way, active-active replication between MinIO buckets.