minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

DOCS-386: Update replication docs for multi-site replication

Browse Source
This commit is contained in:
ravindk89
2021-09-22 20:00:26 -04:00
committed by Ravind Kumar
parent 441a1f8495
commit f2b64d3ae6
10 changed files with 637 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
source/_static/css/main.css
View File

@ -47,8 +47,7 @@ a {
abbr[title] {
border-bottom: none;
text-decoration: underline;
-webkit-text-decoration: underline dotted;
text-decoration: underline dotted; }
text-decoration: underline dotted; }
b,
strong {

2
source/_static/css/main.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
source/images/replication/active-active-multi-replication.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 173 KiB

1
source/images/replication/active-active-twoway-replication.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 102 KiB

1
source/images/replication/active-passive-oneway-replication.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

227
source/reference/minio-cli/minio-mc/mc-replicate.rst
View File

@ -30,8 +30,8 @@ Create Remote Target Before Configuring Replication
Server-Side Replication Requires MinIO Source and Destination
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO server-side replication only works between MinIO clusters. Both the
source and destination clusters *must* run MinIO.
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-cmd:`mc mirror`.
@ -51,7 +51,7 @@ Use the :mc-cmd:`mc version enable` command to enable versioning on
mc version enable ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version enable TARGET>` with the
:mc:`alias <mc alias>` of the MinIO cluster.
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc version enable TARGET>` with the bucket on which
to enable versioning.
@ -59,108 +59,62 @@ Use the :mc-cmd:`mc version enable` command to enable versioning on
Required Permissions
~~~~~~~~~~~~~~~~~~~~
Bucket Replication requires at minimum the following permissions on the
source and destination clusters:
.. tab-set::
.. tab-item:: Source Policy
The source cluster *must* have a user with *at minimum* following attached
*or* inherited policy:
.. code-block:: shell
:class: copyable
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"admin:SetBucketTarget",
"admin:GetBucketTarget"
],
"Effect": "Allow",
"Sid": ""
},
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:GetBucketLocation",
"s3:GetBucketVersioning"
],
"Resource": [
"arn:aws:s3:::SOURCEBUCKETNAME"
]
}
]
}
Replace ``SOURCEBUCKETNAME`` with the name of the source bucket from which
MinIO replicates objects.
Use the :mc-cmd:`mc admin policy set` command to associate the policy to
a user on the source MinIO cluster.
.. tab-item:: Destination Policy
The destination cluster *must* have a user with *at minimum* the
following attached *or* inherited policy:
.. code-block:: shell
:class: copyable
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:GetBucketLocation",
"s3:GetBucketVersioning",
"s3:GetBucketObjectLockConfiguration"
],
"Resource": [
"arn:aws:s3:::DESTINATIONBUCKETNAME"
]
},
{
"Effect": "Allow",
"Action": [
"s3:GetReplicationConfiguration",
"s3:ReplicateTags",
"s3:AbortMultipartUpload",
"s3:GetObject",
"s3:GetObjectVersion",
"s3:GetObjectVersionTagging",
"s3:PutObject",
"s3:DeleteObject",
"s3:ReplicateObject",
"s3:ReplicateDelete"
],
"Resource": [
"arn:aws:s3:::DESTINATIONBUCKETNAME/*"
]
}
]
}
Replace ``DESTINATIONBUCKETNAME`` with the name of the target bucket to
which MinIO replicates objects.
Use the :mc-cmd:`mc admin policy set` command to associate the policy
to a user on the target MinIO cluster.
MinIO strongly recommends creating users specifically for supporting
bucket replication operations. See
:mc:`mc admin user` and :mc:`mc admin policy` for more complete
documentation on adding users and policies to a MinIO cluster.
documentation on adding users and policies to a MinIO deployment.
.. tab-set::
.. tab-item:: Replication Admin
The following policy provides permissions for configuring and enabling
replication on a deployment.
.. literalinclude:: /extra/examples/ReplicationAdminPolicy.json
:class: copyable
:language: 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 deployment. You can restrict the user policy to specific buckets
as-needed.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication source. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
.. tab-item:: Replication Remote User
The following policy provides permissions for enabling synchronization of
replicated data *into* the deployment.
.. literalinclude:: /extra/examples/ReplicationRemoteUserPolicy.json
:class: copyable
:language: 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 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/*"``.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication target. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
Replication of Existing Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -242,10 +196,10 @@ 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
bucket and transmits the unencrypted object. The destination MinIO deployment then
re-encrypts the object using the destination bucket SSE-S3 configuration. MinIO
*strongly recommends* :ref:`enabling TLS <minio-TLS>` on both source and
destination clusters to ensure the safety of objects during transmission.
destination deployments to ensure the safety of objects during transmission.
MinIO does *not* support replicating client-side encrypted objects
(SSE-C).
@ -274,7 +228,7 @@ prefix. :mc:`mc replicate` depends on the ARN resource returned by
[--FLAGS]
- Replace :mc-cmd:`ALIAS <mc replicate add SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO cluster.
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate add SOURCE>` with the path to the
bucket or bucket prefix on which to add the new rule.
@ -301,7 +255,7 @@ Use :mc-cmd:`mc replicate edit` to modify an existing replication rule.
[--FLAGS]
- Replace :mc-cmd:`ALIAS <mc replicate edit SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO cluster.
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
@ -333,7 +287,7 @@ replication rule.
--state "disabled"|"enabled"
- Replace :mc-cmd:`ALIAS <mc replicate edit SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO cluster.
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
@ -365,7 +319,7 @@ Use :mc-cmd:`mc replicate rm` to remove an existing replication rule:
mc replicate rm ALIAS/PATH --id ID
- Replace :mc-cmd:`ALIAS <mc replicate rm SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO cluster.
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate rm SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
@ -416,33 +370,32 @@ Syntax
mc replicate add play/mybucket
.. mc-cmd:: arn
:option:
*Required*
Specify the ARN for the destination cluster and bucket. You can
retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination cluster.
- Use the :mc-cmd:`mc admin bucket remote add` to create an ARN for
the bucket on the destination cluster.
The specified ARN bucket *must* match the value specified to
:mc-cmd-option:`~mc replicate add remote-bucket`.
*Deprecated in* :mc-release:`RELEASE.2021-09-23T05-44-03Z`.
:mc-cmd-option:`mc replicate add remote-bucket` supersedes all
functionality provided by this option.
.. mc-cmd:: remote-bucket
:option:
*Required*
Specify the name of the bucket on the destination cluster. The
name *must* match the ARN specified to
:mc-cmd-option:`~mc replicate add arn`.
Specify the ARN for the destination deployment and bucket. You can
retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination deployment.
- Use the :mc-cmd:`mc admin bucket remote add` to create a replication ARN
for the bucket on the destination deployment.
The specified ARN bucket *must* match the value specified to
:mc-cmd-option:`~mc replicate add remote-bucket`.
*Added in* :mc-release:`RELEASE.2021-09-23T05-44-03Z`. Requires
MinIO server :minio-release:`RELEASE.2021-09-23T04-46-24Z`.
.. mc-cmd:: replicate
@ -513,8 +466,8 @@ Syntax
*Optional*
Disables verification of the destination cluster's TLS certificate.
This option may be required if the destination cluster uses a
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
@ -576,7 +529,7 @@ Syntax
*Optional*
Specify the name of the bucket on the destination cluster. The
Specify the name of the bucket on the destination deployment. The
name *must* match the replication rule ARN. Use
:mc-cmd:`mc replicate ls` to validate the ARN for each configured
replication rule on the bucket.
@ -651,8 +604,8 @@ Syntax
*Optional*
Disables verification of the destination cluster's TLS certificate.
This option may be required if the destination cluster uses a
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
@ -707,8 +660,8 @@ Syntax
*Optional*
Disables verification of the destination cluster's TLS certificate.
This option may be required if the destination cluster uses a
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
@ -760,8 +713,8 @@ Syntax
*Optional*
Disables verification of the destination cluster's TLS certificate.
This option may be required if the destination cluster uses a
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
@ -806,8 +759,8 @@ Syntax
*Optional*
Disables verification of the destination cluster's TLS certificate.
This option may be required if the destination cluster uses a
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.

464
source/replication/enable-server-side-multi-site-bucket-replication.rst Normal file
View File

@ -0,0 +1,464 @@
.. _minio-bucket-replication-serverside-multi:
================================================
Enable Multi-Site Server-Side Bucket Replication
================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The procedure on this page configures automatic server-side bucket
replication between multiple MinIO deployments. Multi-Site Active-Active
replication builds on the
:ref:`minio-bucket-replication-serverside-twoway` procedure with additional
considerations required to ensure predictable replication behavior across
all sites.
.. image:: /images/replication/active-active-multi-replication.svg
:width: 600px
:alt: Active-Active Replication synchronizes data between multiple remote deployments.
:align: center
- To configure replication between arbitrary S3-compatible services, use
:mc-cmd:`mc mirror`.
- To configure one-way "active-active" replication between two MinIO
deployments, see :ref:`minio-bucket-replication-serverside-oneway`.
- To configure one-way "active-passive" replication between MinIO deployments,
see :ref:`minio-bucket-replication-serverside-oneway`.
Multi-Site Active-Active replication configurations can span multiple
racks, datacenters, or geographic locations. Complexity of configuring and
maintaining multi-site configurations generally increase with the number of
sites and size of each site. Enterprises looking to implement
multi-site replication should consider leveraging `MinIO SUBNET
<https://min.io/pricing?ref=docs>`__ support to access the expertise, planning,
and engineering resources required for addressing that use case.
MinIO multi-site replication requires MinIO server
:minio-release:`RELEASE.2021-09-23T04-46-24Z` and :mc:`mc`
:mc-release:`RELEASE.2021-09-23T05-44-03Z` and later.
.. seealso::
- Use the :mc-cmd:`mc replicate edit` command to modify an existing
replication rule.
- Use the :mc-cmd-option:`mc replicate edit` command with the
:mc-cmd-option:`--state "disable" <mc replicate edit state>` flag to
disable an existing replication rule.
- Use the :mc-cmd:`mc replicate rm` command to remove an existing replication
rule.
.. _minio-bucket-replication-serverside-multi-requirements:
Requirements
------------
Replication Requires MinIO Remote Targets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO server-side replication only works between MinIO deployments. All
deployments participating in the multi-site replication configuration
*must* run MinIO. MinIO strongly recommends using the *same* MinIO server
version across all sites.
To configure replication between arbitrary S3-compatible services,
use :mc-cmd:`mc mirror`.
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO relies on the immutability protections provided by versioning to
synchronize objects as part of replication.
Use the :mc-cmd:`mc version enable` command to enable versioning for the bucket
across *all* MinIO deployments participating in the multi-site replication
configuration.
.. code-block:: shell
:class: copyable
mc version enable ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version enable TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`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:`mc` for performing operations on both the source and
destination MinIO cluster. Install :mc:`mc` on a machine with network access to
both source and destination deployments. See the ``mc``
:ref:`Installation Quickstart <mc-install>` for instructions on downloading and
installing ``mc``.
Use the :mc:`mc alias` command to create an alias for both MinIO deployments.
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*:
- :policy-action:`admin:CreateUser`
- :policy-action:`admin:ListUsers`
- :policy-action:`admin:GetUser`
- :policy-action:`admin:CreatePolicy`
- :policy-action:`admin:GetPolicy`
- :policy-action:`admin:AttachUserOrGroupPolicy`
.. _minio-bucket-replication-serverside-multi-permissions:
Required Permissions
~~~~~~~~~~~~~~~~~~~~
Bucket replication requires specific permissions on the source and
destination deployments to configure and enable replication rules.
.. tab-set::
.. tab-item:: Replication Admin
The following policy provides permissions for configuring and enabling
replication on a cluster.
.. literalinclude:: /extra/examples/ReplicationAdminPolicy.json
:class: copyable
:language: 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-cmd:`mc admin policy add` to add this policy to *both*
deployments. You can then create a user on both deployments using
:mc-cmd:`mc admin user add` and associate the policy to those users
with :mc-cmd:`mc admin policy set`.
.. tab-item:: Replication Remote User
The following policy provides permissions for enabling synchronization of
replicated data *into* the cluster. Use the :mc-cmd:`mc admin policy add`
to add this policy to *both* deployments.
.. literalinclude:: /extra/examples/ReplicationRemoteUserPolicy.json
:class: copyable
:language: 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-cmd:`mc admin policy add` to add this policy to *both*
deployments. You can then create a user on both deployments using
:mc-cmd:`mc admin user add` and associate the policy to those users
with :mc-cmd:`mc admin policy set`.
MinIO strongly recommends creating users specifically for supporting
bucket replication operations. See
:mc:`mc admin user` and :mc:`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 all MinIO
deployments participating in multi-site replication use the *same* replication
behaviors to ensure consistent and predictable synchronization of objects.
Replication of Existing Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Starting with :mc:`mc` :minio-git:`RELEASE.2021-06-13T17-48-22Z
<mc/releases/tag/RELEASE.2021-06-13T17-48-22Z>` and :mc:`minio`
:minio-git:`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-cmd-option:`mc replicate add replicate` or
:mc-cmd-option:`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
:s3-docs:`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-cmd-option:`mc replicate add replicate` or
:mc-cmd-option:`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* :ref:`enabling TLS <minio-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).
Replication of Locked Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports replicating objects held under
:ref:`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 :ref:`versioning <minio-bucket-versioning>` and
enables the feature implicitly.
Procedure
---------
This procedure requires repeating steps for each MinIO deployment participating
in the multi-site replication configuration. Depending on the number of
deployments, this procedure may require significant time and care in
implementation. MinIO recommends reading through the procedure *before*
attempting to implement the documented steps.
1) Create Replication Administrator Users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example creates a replication administrator policy and
associates that policy to a user on the MinIO deployment. Replace the
password ``LongRandomSecretKey`` with a long, random, and secure secret key
as per your organizations best practices for password generation
.. code-block:: shell
:class: copyable
wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationAdminPolicy.json | \
mc admin policy add ALIAS ReplicationAdminPolicy /dev/stdin
mc admin user add ALIAS ReplicationAdmin LongRandomSecretKey
mc admin policy set ALIAS ReplicationAdminPolicy user=ReplicationAdmin
The ``ReplicationAdminPolicy.json`` contains the limited set of
:ref:`permissions <minio-bucket-replication-serverside-multi-permissions>`
required for configuring replication rules. Replace the
``LongRandomSecretKey``
Repeat this step for each MinIO deployment participating in the multi-site
replication configuration. For example, a configuration with three MinIO
deployments should repeat this step three times.
The example assumes that the specified aliases have the necessary permissions
for creating policies and users on both deployments. See :ref:`minio-users` and
:ref:`MinIO Policy Based Access Control <minio-policy>` for more complete
documentation on MinIO users and policies respectively.
2) Create Replication Remote Users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example creates a replication remote policy and
associates that policy to a user on the MinIO deployment. Replace the
password ``LongRandomSecretKey`` with a long, random, and secure secret key
as per your organizations best practices for password generation.
.. code-block:: shell
:class: copyable
wget -O - https://docs.min.io/minio/baremetal/examples/ReplicationRemoteUserPolicy.json | \
mc admin policy add ALIAS ReplicationRemoteUserPolicy /dev/stdin
mc admin user add ALIAS ReplicationRemoteUser LongRandomSecretKey
mc admin policy set ALIAS ReplicationRemoteUserPolicy user=ReplicationRemoteUser
The ``ReplicationRemoteUserPolicy.json`` contains the limited set of
:ref:`permissions <minio-bucket-replication-serverside-multi-permissions>`
required for configuring replication rules.
Repeat this step for each MinIO deployment participating in the multi-site
replication configuration. For example, a configuration with three MinIO
deployments should repeat this step three times.
The example assumes that the specified aliases have the necessary permissions
for creating policies and users on both deployments. See :ref:`minio-users` and
:ref:`MinIO Policy Based Access Control <minio-policy>` for more complete
documentation on MinIO users and policies respectively.
3) Configure Replication Administrative Access to Each Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc alias set` command to add a replication-specific alias for
each remote deployment
.. code-block:: shell
:class: copyable
mc alias set ALIAS-Replication HOSTNAME ReplicationAdmin LongRandomSecretKey
Repeat this step for each MinIO deployment participating in the multi-site
replication configuration. Replace the ``ALIAS`` prefix to match the
actual alias for that deployment.
For example, a multi-site replication configuration consisting of MinIO
deployments ``Alpha``, ``Baker``, and ``Charlie`` would resemble the following:
.. code-block:: shell
:class: copyable
mc alias set Alpha-Replication https://alpha-minio.example.net ReplicationAdmin LongRandomSecretKey
mc alias set Baker-Replication https://baker-minio.example.net ReplicationAdmin LongRandomSecretKey
mc alias set Charlie-Replication https://charlie-minio.example.net ReplicationAdmin LongRandomSecretKey
4) Create the Replication Rule on each Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc admin bucket remote` command to create a remote target
for each MinIO deployment participating in the multi-site replication
configuration.
.. code-block:: shell
:class: copyable
mc admin bucket remote add ALIAS-Replication/BUCKET \
https://ReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/BUCKET \
--service "replication" \
[--sync]
- Replace ``BUCKET`` with the name of the bucket on which you are
configuring multi-site replication.
- Replace ``HOSTNAME`` with the URL of the remote MinIO deployment
- (Optional) Specify the :mc-cmd-option:`~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-cmd-option:`~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
following steps.
.. code-block:: shell
Role ARN = 'arn:minio:replication::<UUID>:BUCKET'
Use the :mc-cmd:`mc replicate add` command to create the replication rule using
the remote as a target:
.. code-block:: shell
:class: copyable
mc replicate add ALIAS-Replication/BUCKET \
--remote-bucket 'arn:minio:replication::<UUID>:BUCKET' \
--replicate "delete,delete-marker,existing-objects"
--priority 1
- Replace ``BUCKET`` with the name of the bucket on which you are
configuring multi-site replication. The name *must* match the bucket
specified when creating the remote target.
- Replace the ``--remote-bucket`` value with the ARN returned in the previous
step.
- The ``--replicate "delete,delete-marker,existing-objects"`` flag enables
the following replication features:
- :ref:`Replication of Deletes <minio-replication-behavior-delete>`
- :ref:`Replication of existing Objects <minio-replication-behavior-existing-objects>`
See :mc-cmd-option:`mc replicate add replicate` for more complete
documentation. Omit these fields to disable replication of delete operations
or replication of existing objects respectively.
You *must* specify the same set of replication features for all
MinIO deployments participating in this bucket's multi-site replication.
- Replace ``--priority`` with a unique value for the bucket. If the bucket
has multiple replication rules, you may need to use
:mc-cmd:`mc replicate ls` to identify an unused priority value.
Repeat these commands for each remote MinIO deployment participating in the
multi-site replication configuration. For example, a multi-site replication
configuration consisting of MinIO deployments ``Alpha``, ``Baker``, and
``Charlie`` would require repeating this step on each deployment for each
remote. Specifically:
- The ``Alpha`` deployment would perform this step once for
``Baker`` and once for ``Charlie``.
- The ``Baker`` deployment would perform this step once for ``Alpha`` and
once for ``Charlie``.
- The ``Charlie`` deployment would perform this step once for ``Baker`` and
once for ``Alpha``.
5) Validate the Replication Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc cp` to copy a new object the bucket on any of the deployments:
.. code-block:: shell
:class: copyable
mc cp ~/foo.txt ALIAS/BUCKET
Use :mc-cmd:`mc ls` to verify the object exists on each deployment:
.. code-block:: shell
:class: copyable
mc ls ALIAS/BUCKET
Repeat this test on each of the deployments by copying a new unique file and
checking the other deployments for that file.
You can also use :mc-cmd:`mc stat` to check the file to check the
current :ref:`replication stage <minio-replication-process>` of the object.

22
source/replication/enable-server-side-one-way-bucket-replication.rst
View File

@ -14,14 +14,11 @@ Enable One-Way Server-Side Bucket Replication
The procedure on this page creates a new bucket replication rule for
one-way synchronization of objects between MinIO buckets.
.. image:: /images/active-passive-replication.svg
.. image:: /images/replication/active-passive-oneway-replication.svg
:width: 600px
:alt: Active-Passive Replication synchronizes data from a source MinIO cluster to a remote MinIO cluster.
:align: center
MinIO server-side replication supports at most *two* MinIO clusters. Both
clusters *must* run MinIO.
- To configure replication between arbitrary S3-compatible services, use
:mc-cmd:`mc mirror`.
@ -226,6 +223,23 @@ You can then configure object retention rules at any time.
Object locking requires :ref:`versioning <minio-bucket-versioning>` and
enables the feature implicitly.
Multi-Site Replication
~~~~~~~~~~~~~~~~~~~~~~
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.
MinIO multi-site replication requires MinIO server
:minio-release:`RELEASE.2021-09-23T04-46-24Z` and :mc:`mc`
:mc-release:`RELEASE.2021-09-23T05-44-03Z` and later.
Procedure
---------

60
source/replication/enable-server-side-two-way-bucket-replication.rst
View File

@ -14,26 +14,21 @@ Enable Two-Way Server-Side Bucket Replication
The procedure on this page creates a new bucket replication rule for two-way
"active-active" synchronization of objects between MinIO buckets.
.. image:: /images/active-active-replication.svg
.. image:: /images/replication/active-active-twoway-replication.svg
:width: 600px
:alt: Active-Active Replication synchronizes data between two remote clusters.
:align: center
MinIO server-side replication supports at most *two* MinIO clusters. Both
clusters *must* run MinIO.
- To configure replication between arbitrary S3-compatible services, use
:mc-cmd:`mc mirror`.
- To configure one-way "active-passive" replication between MinIO clusters,
see :ref:`minio-bucket-replication-serverside-oneway`.
MinIO Active-Active replication is designed for synchronizing objects between
two MinIO clusters. MinIO does not support Active-Active replication between
more than two clusters (multi-site). Enterprises looking to implement multi-site
replication should consider leveraging `MinIO SUBNET
<https://min.io/pricing?ref=docs>`__ support to access the expertise, planning,
and engineering resources required for addressing that use case.
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 :ref:`minio-bucket-replication-serverside-multi`
(new in VERSION).
.. seealso::
@ -52,8 +47,17 @@ and engineering resources required for addressing that use case.
Requirements
------------
Enable Versioning on Source and Destination Buckets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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-cmd:`mc mirror`.
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO relies on the immutability protections provided by versioning to
synchronize objects between the source and replication target.
@ -162,6 +166,22 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -227,6 +247,22 @@ You can then configure object retention rules at any time.
Object locking requires :ref:`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
:ref:`minio-bucket-replication-serverside-multi`.
MinIO multi-site replication requires MinIO server
:minio-release:`RELEASE.2021-09-23T04-46-24Z` and :mc:`mc`
:mc-release:`RELEASE.2021-09-23T05-44-03Z` and later.
Procedure
---------

15
source/replication/replication-overview.rst
View File

@ -11,8 +11,7 @@ Bucket Replication
:depth: 2
MinIO supports server-side and client-side replication of objects between source
and destination buckets. MinIO offers both active-passive (one-way) and
active-active (two-way) flavors of the following replication types:
and destination buckets.
:ref:`Server-Side Bucket Replication <minio-bucket-replication-serverside>`
Configure per-bucket rules for automatically synchronizing objects between
@ -61,6 +60,9 @@ replication while adding the following MinIO-only features:
- Active-Active (Two-Way) replication of objects between source and destination
buckets.
- Multi-Site replication of objects between three or more MinIO deployments
(New in :minio-release:`RELEASE.2021-09-23T04-46-24Z`).
.. _minio-replication-process:
Replication Process
@ -88,6 +90,10 @@ replication state of the object:
bucket. MinIO continuously scans for ``PENDING`` objects not yet in the
replication queue and adds them to the queue as space is available.
For multi-site replication, objects remain
in the ``PENDING`` state until replicated to *all* configured
remotes for that bucket or bucket prefix.
* - ``COMPLETED``
- The object has successfully replicated to the remote cluster.
@ -270,7 +276,9 @@ overall cluster load, and the size of the namespace (all objects in the bucket).
MinIO does not synchronize existing unversioned objects. Specifically, the
bucket *must* have :ref:`versioning <minio-bucket-versioning>` enabled when the
object was created.
object was created. You can use the :mc-cmd:`mc cp` command to create a
"versioned" copy of that object. Once that object replicates successfully,
you can delete the unversioned object (versionid = ``null``).
MinIO existing object replication
implements functionality similar to
@ -285,6 +293,7 @@ without the overhead of contacting technical support.
/replication/enable-server-side-one-way-bucket-replication
/replication/enable-server-side-two-way-bucket-replication
/replication/enable-server-side-multi-site-bucket-replication
.. _minio-bucket-replication-clientside: