minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

Docs Multiplatform Slice

Browse Source
This commit is contained in:
Ravind Kumar
2022-05-06 16:44:42 -04:00
parent df33ddee6a
commit b99c20a16f
134 changed files with 3689 additions and 2200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -0,0 +1,230 @@
.. _minio-bucket-replication-serverside-multi:
================================================
Enable Multi-Site Server-Side Bucket Replication
================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
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-twoway`.
- 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.
.. seealso::
- Use the :mc-cmd:`mc replicate edit` command to modify an existing replication rule.
- Use the :mc-cmd:`mc replicate edit` command with the :mc-cmd:`--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
------------
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
~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-required-permissions
:end-before: end-replication-required-permissions
Replication Requires Matching Object Encryption Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-encrypted-objects
:end-before: end-replication-encrypted-objects
Replication Requires MinIO Deployments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-minio-only
:end-before: end-replication-minio-only
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-versioning
:end-before: end-replication-requires-versioning
Replication Requires Matching Object Locking State
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-object-locking
:end-before: end-replication-requires-object-locking
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports automatically replicating existing objects in a bucket.
MinIO requires explicitly enabling replication of existing objects using the :mc-cmd:`mc replicate add --replicate` or :mc-cmd:`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:`mc replicate add --replicate` or :mc-cmd:`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 :ref:`lifecycle management expiration rules <minio-lifecycle-management-expiration>`. Configure matching expiration rules for the bucket on all replication sites to ensure consistent application of object expiration.
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.
This procedure uses the placeholder ``ALIAS`` to reference the :ref:`alias <alias>` each MinIO deployment being configured for replication. Replace these values with the appropriate alias for each MinIO deployment.
This procedure assumes each alias corresponds to a user with the :ref:`necessary replication permissions <minio-bucket-replication-serverside-multi-permissions>`.
1) Create the Replication Remote Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`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.
.. code-block:: shell
:class: copyable
mc admin bucket remote add ALIAS/BUCKET \
https://ReplicationRemoteUser:LongRandomSecretKey@HOSTNAME/BUCKET \
--service "replication"
- Replace ``BUCKET`` with the name of the bucket on the ``ALIAS`` deployment to use as the replication source. Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO deployment on which you are configuring replication.
- Replace ``HOSTNAME`` with the URL of the remote MinIO 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:
.. code-block:: shell
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 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``.
2) Create a New Bucket Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc replicate add` command to add the new server-side
replication rule to the each MinIO deployment.
.. code-block:: shell
:class: copyable
mc replicate add ALIAS/BUCKET \
--remote-bucket 'arn:minio:replication::<UUID>:BUCKET' \
--replicate "delete,delete-marker,existing-objects"
- Replace ``BUCKET`` with the name of the bucket on the ``ALIAS`` deployment to use as the replication source. Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO deployment on which you are configuring replication.
- Replace the ``--remote-bucket`` value with the ARN returned in the previous step. Ensure you specify the ARN created on the ``ALIAS`` deployment. You can use :mc-cmd:`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:
- :ref:`Replication of Deletes <minio-replication-behavior-delete>`
- :ref:`Replication of existing Objects <minio-replication-behavior-existing-objects>`
See :mc-cmd:`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-cmd:`mc replicate add`.
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``.
3) 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 remote deployment:
.. code-block:: shell
:class: copyable
mc ls REMOTE/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.

186
source/administration/bucket-replication/enable-server-side-one-way-bucket-replication.rst Normal file
View File

@ -0,0 +1,186 @@
.. _minio-bucket-replication-serverside-oneway:
=============================================
Enable One-Way Server-Side Bucket Replication
=============================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
The procedure on this page creates a new bucket replication rule for one-way synchronization of objects between MinIO buckets.
.. image:: /images/replication/active-passive-oneway-replication.svg
:width: 450px
:alt: Active-Passive Replication synchronizes data from a source MinIO cluster to a remote MinIO cluster.
:align: center
- To configure replication between arbitrary S3-compatible services, use :mc-cmd:`mc mirror`.
- To configure two-way "active-active" replication between MinIO clusters, see :ref:`minio-bucket-replication-serverside-twoway`.
- To configure multi-site "active-active" replication between MinIO clusters, see :ref:`minio-bucket-replication-serverside-multi`
.. seealso::
- Use the :mc-cmd:`mc replicate edit` command to modify an existing replication rule.
- Use the :mc-cmd:`mc replicate edit` command with the :mc-cmd:`--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-oneway-requirements:
Requirements
------------
.. _minio-bucket-replication-serverside-oneway-permissions:
Required Permissions
~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-required-permissions
:end-before: end-replication-required-permissions
Replication Requires Matching Object Encryption Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-encrypted-objects
:end-before: end-replication-encrypted-objects
Replication Requires MinIO Deployments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-minio-only
:end-before: end-replication-minio-only
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-versioning
:end-before: end-replication-requires-versioning
Replication Requires Matching Object Locking State
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-object-locking
:end-before: end-replication-requires-object-locking
Considerations
--------------
Replication of Existing Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports automatically replicating existing objects in a bucket.
MinIO requires explicitly enabling replication of existing objects using the :mc-cmd:`mc replicate add --replicate` or :mc-cmd:`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 S3 ``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:`mc replicate add --replicate` or :mc-cmd:`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 :ref:`lifecycle management expiration rules <minio-lifecycle-management-expiration>`.
See :ref:`minio-replication-behavior-delete` for more complete documentation.
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.
Procedure
---------
This procedure uses the :ref:`aliases <alias>` ``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 :ref:`necessary replication permissions <minio-bucket-replication-serverside-oneway-permissions>`.
1) Create the Replication Remote Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`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.
.. code-block:: shell
:class: copyable
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 :ref:`alias <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 :mc-cmd:`~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:`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:
.. code-block:: shell
Role ARN = 'arn:minio:replication::<UUID>:BUCKET'
Copy the ARN string for use in the next step.
2) Create a New Bucket Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc replicate add` command to add the new server-side
replication rule to the source MinIO cluster.
.. code-block:: shell
:class: copyable
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 :ref:`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 ``SOURCE`` deployment. You can use :mc-cmd:`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:
- :ref:`Replication of Deletes <minio-replication-behavior-delete>`
- :ref:`Replication of existing Objects <minio-replication-behavior-existing-objects>`
See :mc-cmd:`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-cmd:`mc replicate add`.
3) Validate the Replication Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc cp` to copy a new object to the source bucket.
.. code-block:: shell
:class: copyable
mc cp ~/foo.txt SOURCE/BUCKET
Use :mc-cmd:`mc ls` to verify the object exists on the destination bucket:
.. code-block:: shell
:class: copyable
mc ls TARGET/BUCKET

235
source/administration/bucket-replication/enable-server-side-two-way-bucket-replication.rst Normal file
View File

@ -0,0 +1,235 @@
.. _minio-bucket-replication-serverside-twoway:
=============================================
Enable Two-Way Server-Side Bucket Replication
=============================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
The procedure on this page creates a new bucket replication rule for two-way "active-active" synchronization of objects between MinIO buckets.
.. image:: /images/replication/active-active-twoway-replication.svg
:width: 600px
:alt: Active-Active Replication synchronizes data between two remote clusters.
:align: center
- 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`.
- To configure multi-site "active-active" replication between MinIO clusters, see :ref:`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 :ref:`minio-bucket-replication-serverside-multi`.
.. seealso::
- Use the :mc-cmd:`mc replicate edit` command to modify an existing
replication rule.
- Use the :mc-cmd:`mc replicate edit` command with the :mc-cmd:`--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-twoway-requirements:
Requirements
------------
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 clusters. 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 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*:
- :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-twoway-permissions:
Required Permissions
~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-required-permissions
:end-before: end-replication-required-permissions
Replication Requires Matching Object Encryption Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-encrypted-objects
:end-before: end-replication-encrypted-objects
Replication Requires MinIO Deployments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-minio-only
:end-before: end-replication-minio-only
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-versioning
:end-before: end-replication-requires-versioning
Replication Requires Matching Object Locking State
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-object-locking
:end-before: end-replication-requires-object-locking
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-cmd:`mc replicate add --replicate` or :mc-cmd:`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:`mc replicate add --replicate` or :mc-cmd:`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 :ref:`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 :ref:`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 :ref:`minio-bucket-replication-serverside-multi`.
Procedure
---------
This procedure uses the :ref:`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 :ref:`necessary replication permissions <minio-bucket-replication-serverside-twoway-permissions>`.
1) Create the Replication Remote Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`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.
.. code-block:: shell
:class: copyable
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 :ref:`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:
.. code-block:: shell
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-cmd:`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-cmd:`mc replicate add` command to add the new server-side
replication rule to the each MinIO deployment.
.. code-block:: shell
:class: copyable
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 :ref:`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-cmd:`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:
- :ref:`Replication of Deletes <minio-replication-behavior-delete>`
- :ref:`Replication of existing Objects <minio-replication-behavior-existing-objects>`
See :mc-cmd:`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-cmd:`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-cmd:`mc replicate ls` command to verify the created replication rules.
3) Validate the Replication Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc cp` to copy a new object to the ``ALPHA/BUCKET`` bucket.
.. code-block:: shell
:class: copyable
mc cp ~/foo.txt ALPHA/BUCKET
Use :mc-cmd:`mc ls` to verify the object exists on the destination bucket:
.. code-block:: shell
:class: copyable
mc ls BAKER/BUCKET
Repeat this test by copying a new object to the ``Baker`` source bucket.
.. code-block:: shell
:class: copyable
mc cp ~/otherfoo.txt BAKER/BUCKET
Use :mc-cmd:`mc ls` to verify the object exists on the destination bucket:
.. code-block:: shell
:class: copyable
mc ls ALPHA/BUCKET

182
source/administration/bucket-replication/server-side-replication-resynchronize-remote.rst Normal file
View File

@ -0,0 +1,182 @@
.. _minio-bucket-replication-resynchronize:
========================================
Resynchronize Bucket from Remote Replica
========================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
The procedure on this page resynchronizes the contents of a MinIO bucket using a healthy replication remote. Resynchronization supports recovery after partial or total loss of data on a MinIO deployment in a replica configuration.
For example, consider a MinIO active-active replication configuration similar to the following:
.. image:: /images/replication/active-active-twoway-replication.svg
:width: 600px
:alt: Active-Active Replication synchronizes data between two remote deployments.
:align: center
Resynchronization allows using the healthy data on one of the participating MinIO deployments as the source for rebuilding the other deployment.
Resynchronization is a per-bucket process. You must repeat resynchronization for each bucket on the remote which suffered partial or total data loss.
.. admonition:: Professional Support during BC/DR Operations
:class: important
`MinIO SUBNET <https://min.io/pricing?jmp=docs>`__ users can `log in <https://subnet.min.io/>`__ and create a new issue related to resynchronization. Coordination with MinIO Engineering via SUBNET can ensure successful resynchronization and restoration of normal operations, including performance testing and health diagnostics.
Community users can seek support on the `MinIO Community Slack <https://minio.slack.com>`__. Community Support is best-effort only and has no SLAs around responsiveness.
.. _minio-bucket-replication-serverside-resynchronize-requirements:
Requirements
------------
MinIO Deployments Must Be Online
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resynchronization requires both the source and target deployments be online and able to accept read and write operations. The source *must* have complete network connectivity to the remote.
The remote deployment may be "unhealthy" in that it has suffered partial or total data loss. Resynchronization addresses the data loss as long as both source and destination maintain connectivity.
Resynchronization Requires Existing Replication Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resynchronization requires the healthy source deployment have an existing replication configuration for the unhealthy target bucket. Additionally, resynchronization only applies to those replication rules created with the :ref:`existing object replication <minio-replication-behavior-existing-objects>` option.
- Use :mc-cmd:`mc admin bucket remote ls` to review the configured remote targets on the healthy source bucket.
- Use :mc-cmd:`mc replicate ls` to review the configured replication rules on the healthy source bucket.
Replication Requires Matching Object Encryption Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-encrypted-objects
:end-before: end-replication-encrypted-objects
Replication Requires MinIO Deployments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-minio-only
:end-before: end-replication-minio-only
Replication Requires Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-versioning
:end-before: end-replication-requires-versioning
Replication Requires Matching Object Locking State
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-replication.rst
:start-after: start-replication-requires-object-locking
:end-before: end-replication-requires-object-locking
Considerations
--------------
Resynchronization Requires Time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resynchronization is a background processes that continually checks objects in the source MinIO bucket and copies them to the remote as-needed. The time required for replication to complete may vary depending on the number and size of objects, the throughput to the remote MinIO deployment, and the load on the source MinIO deployment. Total time for completion is generally not predictable due to these variables.
MinIO recommends configuring load balancers or proxies to direct traffic only to the healthy cluster until synchronization completes. The following commands can provide insight into the resynchronization status:
- :mc-cmd:`mc replicate resync status` on the source to track the resynchronization progress.
- :mc-cmd:`mc replicate status` on the source and remote to track normal replication data.
- Run ``mc ls -r --versions ALIAS/BUCKET | wc -l`` against both source and remote to validate the total number of objects and object versions on each.
Resynchronize Objects after Data Loss
-------------------------------------
This procedure uses an existing :ref:`MinIO replication configuration <minio-bucket-replication-serverside>` to restore missing data to one of the MinIO deployments participating in that configuration. Specifically, a healthy MinIO deployment (the ``SOURCE``) synchronizes it's existing data to the unhealthy MinIO deployment (the ``TARGET``).
This procedure assumes an existing :ref:`alias <alias>` for the ``SOURCE`` that has the :ref:`necessary permissions <minio-bucket-replication-serverside-twoway-permissions>` for configuring replication.
You can repeat this procedure for each bucket that requires resynchronization. You can have no more than one replication job running per bucket.
1) List the Configured Replication Targets on the Healthy Source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run the :mc-cmd:`mc admin bucket remote ls` command to list the configured remote targets on the healthy ``SOURCE`` deployment for the ``BUCKET`` that requires resynchronization.
.. code-block:: shell
:class: copyable
mc admin bucket remote ls SOURCE/BUCKET
- Replace ``SOURCE`` with the :ref:`alias <alias>` of the source MinIO deployment.
- Replace ``BUCKET`` with the name of the bucket to use as the source for resynchronization.
The output resembles the following:
.. code-block:: shell
Remote URL Source->Target ARN SYNC PROXY
https://minio-2.example.net:9000 data ->data arn:minio:replication::UUID:BUCKET proxy
Identify the ARN associated to the ``BUCKET`` on the unhealthy ``TARGET`` MinIO deployment for use in the next step.
2) Start the Resynchronization Procedure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run the :mc-cmd:`mc replicate resync start` command to begin the resynchronization process:
.. code-block:: shell
:class: copyable
mc replicate resync start --remote-bucket "arn:minio:replication::UUID:BUCKET" SOURCE/BUCKET
- Replace the ``--remote-bucket`` value with the ARN of the unhealthy ``BUCKET`` on the ``TARGET`` MinIO deployment.
- Replaced ``SOURCE`` with the :ref:`alias <alias>` of the source MinIO deployment.
- Replace the ``BUCKET`` with the name of the bucket on the healthy ``SOURCE`` MinIO
deployment.
The command returns a resynchronization job ID indicating that the process has begun.
3) Monitor Resynchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc replicate resync status` command on the source deployment to track the received replication data:
.. code-block:: shell
:class: copyable
mc replicate resync status ALIAS/BUCKET
The output resembles the following:
.. code-block:: shell
mc replicate resync status /data
Resync status summary:
● arn:minio:replication::6593d572-4dc3-4bb9-8d90-7f79cc612f01:data
Status: Ongoing
Replication Status | Size (Bytes) | Count
Replicated | 2.3 GiB | 18
Failed | 0 B | 0
The :guilabel:`Status` updates to ``Completed`` once the resynchronization
process completes.
4) Next Steps
~~~~~~~~~~~~~
- If the ``TARGET`` bucket damage extends to replication rules, you must recreate those rules to match the previous replication configuration. See :ref:`minio-bucket-replication-serverside-twoway` for additional guidance.
- Perform basic validation that all buckets in the replication configuration show similar results for commands such as :mc-cmd:`mc ls` and :mc-cmd:`mc stat`.
- After restoring any replication rules and verifying replication between sites, you can configure the reverse proxy, load balancer, or other network control plane managing connections to resume sending traffic to the resynchronized deployment.