minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-11-03 05:13:12 +03:00
Code Activity
Files
f2b64d3ae6710dc1da8e3d4b7fd0ba60e401ef93
docs/source/replication/enable-server-side-two-way-bucket-replication.rst

21 KiB
Raw Blame History

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.

Active-Active Replication synchronizes data between two remote clusters.

  • 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.

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 (new in VERSION).

  • 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

Replication Requires MinIO Remote Targets

MinIO server-side replication only works between MinIO clusters. Both the source and destination clusters must run MinIO.

To configure replication between arbitrary S3-compatible services, use mc mirror.

Replication Requires Versioning

MinIO relies on the immutability protections provided by versioning to synchronize objects between the source and replication target.

Use the mc version enable command to enable versioning on both the source and destination bucket before starting this procedure:

mc version enable ALIAS/PATH
  • Replace ALIAS <mc version enable TARGET> with the alias <mc alias> of the MinIO cluster.
  • Replace PATH <mc version enable TARGET> with the bucket on which to enable versioning.

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

Bucket replication requires specific permissions on the source and destination clusters to configure and enable replication rules.

Replication Admin

The following policy provides permissions for configuring and enabling replication on a cluster.

/extra/examples/ReplicationAdminPolicy.json

  • 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 cluster. You can restrict the user policy to specific buckets as-needed.

Use the mc admin policy add to add this policy to both clusters. You can then create a user on both clusters using mc admin user add and associate the policy to those users with mc admin policy set.

Replication Remote User

The following policy provides permissions for enabling synchronization of replicated data into the cluster. Use the mc admin policy add to add this policy to both clusters.

/extra/examples/ReplicationRemoteUserPolicy.json

  • The "EnableReplicationOnBucket" statement grants permission for a remote target to retrieve bucket-level configuration for supporting replication operations on all buckets in the MinIO cluster. 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 cluster. To restrict the policy to specific buckets, specify those buckets as an element in the Resource array similar to "arn:aws:s3:::bucketName/*".

Use the mc admin policy add to add this policy to both clusters. You can then create a user on both clusters using mc admin user add and associate the policy to those users with mc admin policy set.

MinIO strongly recommends creating users specifically for supporting bucket replication operations. See mc admin user and mc admin policy for more complete documentation on adding users and policies to a MinIO cluster.

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

Starting with mc RELEASE.2021-06-13T17-48-22Z <mc/releases/tag/RELEASE.2021-06-13T17-48-22Z> and minio RELEASE.2021-06-07T21-40-51Z <minio/releases/tag/RELEASE.2021-06-07T21-40-51Z>, 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.

Replication of Encrypted Objects

MinIO supports replicating objects encrypted with automatic Server-Side Encryption (SSE-S3). Both the source and destination buckets must have automatic SSE-S3 enabled for MinIO to replicate an encrypted object.

As part of the replication process, MinIO decrypts the object on the source bucket and transmits the unencrypted object. The destination MinIO cluster then re-encrypts the object using the destination bucket SSE-S3 configuration. MinIO strongly recommends enabling TLS <minio-TLS> on both source and destination clusters to ensure the safety of objects during transmission.

MinIO does not support replicating client-side encrypted objects (SSE-C).

Replication of Locked Objects

MinIO supports replicating objects held under WORM Locking <minio-object-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. Object locking requires versioning <minio-bucket-versioning> and enables the feature implicitly.

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.

MinIO multi-site replication requires MinIO server RELEASE.2021-09-23T04-46-24Z and mc RELEASE.2021-09-23T05-44-03Z and later.

Procedure

1) Configure User Accounts and Policies for Replication

This step creates multiple users and policies on both MinIO clusters for supporting replication operations. You can skip this step if both clusters already have users with the necessary permissions <minio-bucket-replication-serverside-twoway-permissions>.

The following examples use Alpha and Baker as placeholder aliases <mc alias> for each MinIO cluster. You should replace these values with the appropriate aliases for the MinIO clusters on which you are configuring bucket replication. These examples assume that the specified aliases have the necessary permissions for creating policies and users on both clusters. See minio-users and MinIO Policy Based Access Control <minio-policy> for more complete documentation on MinIO users and policies respectively.

A) Create Replication Administrators

The following code creates policies and users for supporting configuring replication on the Alpha and Baker clusters. Replace the password LongRandomSecretKey with a long, random, and secure secret key as per your organizations best practices for password generation.

wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationAdminPolicy.json | \
mc admin policy add Alpha ReplicationAdminPolicy /dev/stdin
mc admin user add Alpha alphaReplicationAdmin LongRandomSecretKey
mc admin policy set Alpha ReplicationAdminPolicy user=alphaReplicationAdmin

wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationAdminPolicy.json | \
mc admin policy add Baker ReplicationAdminPolicy /dev/stdin
mc admin user add Baker bakerReplicationAdmin LongRandomSecretKey
mc admin policy set baker ReplicationAdminPolicy user=bakerReplicationAdmin
B) Create Remote Replication User

The following code creates policies and users for supporting synchronizing data to the Alpha and Baker clusters. Replace the password LongRandomSecretKey with a long, random, and secure secret key as per your organizations best practices for password generation.

wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationRemoteUserPolicy.json | \
mc admin policy add Alpha ReplicationRemoteUserPolicy /dev/stdin
mc admin user add Alpha alphaReplicationRemoteUser LongRandomSecretKey
mc admin policy set Alpha ReplicationRemoteUserPolicy user=alphaReplicationRemoteUser

wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationRemoteUserPolicy.json | \
mc admin policy add Baker ReplicationRemoteUserPolicy /dev/stdin
mc admin user add Baker bakerReplicationRemoteUser LongRandomSecretKey
mc admin policy set Baker ReplicationRemoteUserPolicy user=bakerReplicationRemoteUser

2) Configure mc Access to the Remote Clusters

Use the mc alias set command to add a replication-specific alias for both remote clusters:

mc alias set AlphaReplication HOSTNAME AlphaReplicationAdmin LongRandomSecretKey
mc alias set BakerReplication HOSTNAME BakerReplicationAdmin LongRandomSecretKey

3) Create a Replication Target for Each Cluster

Use the mc admin bucket remote command to create a replication target for the destination cluster. For Active-Active replication, you must issue this command on both clusters to create a remote in both directions

A) Create a Replication Target for Alpha -> Baker

The following command operates on the Alpha cluster to create a remote replication target on the Baker cluster:

mc admin bucket remote add AlphaReplication/SOURCEBUCKET \
   https://bakerReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/DESTINATIONBUCKET \
   --service "replication" \
   [--sync]
  • Replace SOURCEBUCKET with the name of the source bucket on the Alpha cluster.
  • Replace HOSTNAME with the URL of the Baker cluster.
  • Replace DESTINATIONBUCKET with the name of the target bucket on the Baker cluster.
  • Specify the ~mc admin bucket remote add 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 sync for more information on synchronous vs asynchronous replication.

The command returns an ARN similar to the following. Copy this ARN for use in the following step. Note the ARN as associated to the Alpha cluster.

Role ARN = 'arn:minio:replication::<UUID>:DESTINATIONBUCKET'
B) Create a Replication Target for Baker -> Alpha

The following command operates on the Baker cluster to create a remote replication target on the Alpha cluster:

mc admin bucket remote add BakerReplication/SOURCEBUCKET \
   https://AlphaReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/DESTINATIONBUCKET \
   --service "replication: \
   [--sync]
  • Replace SOURCEBUCKET with the name of the source bucket on the Baker cluster.
  • Replace HOSTNAME with the URL of the Alpha cluster.
  • Replace DESTINATIONBUCKET with the name of the remote replication target on the Alpha cluster.
  • Specify the ~mc admin bucket remote add 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 sync for more information on synchronous vs asynchronous replication.

The command returns an ARN similar to the following. Copy this ARN for use in the following step. Note the ARN as associated to the Baker cluster.

Role ARN = 'arn:minio:replication::<UUID>:DESTINATIONBUCKET'

4) Create a New Bucket Replication Rule

Use the mc replicate add command to add the new server-side replication rule to the MinIO bucket. For Active-Active replication, you must issue this command on both clusters to enable replication in both directions.

A) Create Replication Rule on Alpha

The following command operates on the Alpha cluster to create a replication rule for synchronizing data to the Baker cluster. This command uses the ARN generated in the previous step:

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

  • Replace SOURCEBUCKET with the name of the bucket from which Alpha replicates data. The name must match the bucket specified when creating the remote target in the previous step.

  • Replace the DESTINATIONBUCKET with the name of the Baker bucket to which Alpha replicates data. The name must match the bucket specified when creating the remote target in the previous step.

  • Replace the --arn value with the ARN returned in the previous step. Ensure you specify the ARN created on the Alpha cluster. You can use mc admin bucket remote ls to list all remote ARNs configured on the cluster.

  • 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.

B) Create Replication Rule on Baker

The following command operates on the Baker cluster to create a replication rule for synchronizing data to the Alpha cluster. This command uses the ARN generated in the previous step:

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

  • Replace SOURCEBUCKET with the name of the bucket from which Baker replicates data. The name must match the bucket specified when creating the remote target in the previous step.

  • Replace the DESTINATIONBUCKET with the name of the Alpha bucket to which Baker replicates data. The name must match the bucket specified when creating the remote target in the previous step.

  • Replace the --arn value with the ARN returned in the previous step. Ensure you specify the ARN created on the Alpha cluster. You can use mc admin bucket remote ls to list all remote ARNs configured on the cluster.

  • 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 fof existing objects respectively.

Specify any other supported optional arguments for mc replicate add.

Specify any other supported optional arguments for mc replicate add.

5) Validate the Replication Configuration

Use mc cp to copy a new object to the Alpha source bucket.

mc cp ~/foo.txt Alpha/SOURCEBUCKET

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

mc ls Baker/DESTINATIONBUCKET

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

mc cp ~/otherfoo.txt Baker/SOURCEBUCKET

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

mc ls Alpha/DESTINATIONBUCKET

If the remote target was configured without the ~mc admin bucket remote add sync option, the destination bucket may have some delay before it receives the new object.