docs/source/replication/enable-server-side-two-way-bucket-replication.rst

Enable Two-Way Server-Side Bucket Replication

minio

Table of Contents

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 mc mirror.
• To configure one-way "active-passive" replication between MinIO clusters, see minio-bucket-replication-serverside-oneway.
• To configure multi-site "active-active" replication between MinIO clusters, see minio-bucket-replication-serverside-multi.

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 minio-bucket-replication-serverside-multi.

• Use the mc replicate edit command to modify an existing replication rule.
• Use the mc replicate edit command with the --state "disable" <mc replicate edit --state> flag to disable an existing replication rule.
• Use the mc replicate rm command to remove an existing replication rule.

Requirements

Install and Configure mc with Access to Both Clusters.

This procedure uses mc for performing operations on both the source and destination MinIO cluster. Install mc on a machine with network access to both source and destination clusters. See the mc Installation Quickstart <mc-install> for instructions on downloading and installing mc.

Use the mc alias command to create an alias for both MinIO clusters. Alias creation requires specifying an access key for a user on the cluster. This user must have permission to create and manage users and policies on the cluster. Specifically, ensure the user has at minimum:

• admin:CreateUser
• admin:ListUsers
• admin:GetUser
• admin:CreatePolicy
• admin:GetPolicy
• admin:AttachUserOrGroupPolicy

Required Permissions

Replication Requires Matching Object Encryption Settings

Replication Requires MinIO Deployments

Replication Requires Versioning

Replication Requires Matching Object Locking State

Considerations

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 edit --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 <versioning-workflows.html> 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 <minio-lifecycle-management-expiration>. Configure matching expiration rules on both the source and destination bucket to ensure consistent application of object expiration.

See minio-replication-behavior-delete for more complete documentation.

Multi-Site Replication

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 minio-bucket-replication-serverside-multi.

Procedure

This procedure uses the aliases <alias> ALPHA and BAKER 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 <minio-bucket-replication-serverside-twoway-permissions>.

1) Create the Replication Remote Target

Use the mc admin bucket remote add command to create a replication target for the each deployment. MinIO supports one remote target per destination bucket. You cannot create multiple remote targets for the same destination bucket.

mc admin bucket remote add ALPHA/BUCKET \
   https://ReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/BUCKET \
   --service "replication"

• Replace BUCKET with the name of the bucket on the ALPHA deployment to use as the replication source. Replace ALPHA with the alias <alias> of the MinIO deployment on which you are configuring replication.
• Replace HOSTNAME with the URL of the BAKER deployment.
• Replace BUCKET with the name of the bucket on the REMOTE deployment to use as the replication destination.

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, noting the MinIO deployment on which it was created.

Repeat this step on the second MinIO deployment, replacing the ALPHA alias with the BAKER alias and the HOSTNAME with the URL of the ALPHA deployment.

You should have two ARNs at the conclusion of this step - one created on ALPHA/BUCKET pointing at BAKER/BUCKET, and one created on BAKER/BUCKET pointing at ALPHA/BUCKET. Use the mc admin bucket remote ls command to verify the created replication remote targets before proceeding.

2) Create a New Bucket Replication Rule

Use the mc replicate add command to add the new server-side replication rule to the each MinIO deployment.

mc replicate add ALPHA/BUCKET \
   --remote-bucket 'arn:minio:replication::<UUID>:BUCKET' \
   --replicate "delete,delete-marker,existing-objects"

• Replace BUCKET with the name of the bucket on the ALPHA deployment to use as the replication source. Replace ALPHA with the alias <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 ALPHA 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:

  • Replication of Deletes <minio-replication-behavior-delete>
  • Replication of existing Objects <minio-replication-behavior-existing-objects>

  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.

Repeat this step on the second MinIO deployment, replacing the ALPHA alias with the BAKER alias and the HOSTNAME with the URL of the ALPHA deployment.

You should have two replication rules configured at the conclusion of this step - one created on ALPHA/BUCKET and one created on BAKER/BUCKET. Use the mc replicate ls command to verify the created replication rules.

3) Validate the Replication Configuration

Use mc cp to copy a new object to the ALPHA/BUCKET bucket.

mc cp ~/foo.txt ALPHA/BUCKET

Use mc ls to verify the object exists on the destination bucket:

mc ls BAKER/BUCKET

Repeat this test by copying a new object to the Baker source bucket.

mc cp ~/otherfoo.txt BAKER/BUCKET

Use mc ls to verify the object exists on the destination bucket:

mc ls ALPHA/BUCKET