New flag to set site replication to synchronous (#826)

Document new flag for `mc admin replicate update` to enable/disable
synchronous site replication. Continue to recommend default async
replication due to increased write latency with sync.

Adapt/reuse the existing description of async vs sync from bucket
replication as an include.

Staged

http://192.241.195.202:9000/staging/DOCS-790/linux/html/operations/install-deploy-manage/multi-site-replication.html#synchronous-vs-asynchronous-replication

http://192.241.195.202:9000/staging/DOCS-790/linux/html/reference/minio-mc-admin/mc-admin-replicate.html#syntax

http://192.241.195.202:9000/staging/DOCS-790/linux/html/administration/bucket-replication.html#synchronous-vs-asynchronous-replication

Fixes https://github.com/minio/docs/issues/790

source/administration/bucket-replication.rst

@@ -219,21 +219,9 @@ without the overhead of contacting technical support.
 Synchronous vs Asynchronous Replication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-MinIO supports specifying either asynchronous (default) or synchronous
-replication for a given remote target.
-
-With the default asynchronous replication, MinIO completes the originating
-``PUT`` operation *before* placing the object into a :ref:`replication queue
-<minio-replication-process>`. The originating client may therefore see a 
-successful ``PUT`` operation *before* the object is replicated. While
-this may result in stale or missing objects on the remote, it mitigates
-the risk of slow write operations due to replication load.
-  
-With synchronous replication, MinIO attempts to replicate the object *prior* to
-completing the originating ``PUT`` operation. MinIO returns a successful ``PUT``
-operation whether or not the replication attempts succeeds. While this may
-result in more reliable synchronization between the source and remote target,
-it may also increase the time of each write operation due to replication load.
+.. include:: /includes/common-replication.rst
+   :start-after: start-replication-sync-vs-async
+   :end-before: end-replication-sync-vs-async
 
 You must explicitly enable synchronous replication when configuring the remote
 target target using the :mc-cmd:`mc admin bucket remote add` command with the
@@ -310,4 +298,4 @@ The replication process generally has one of the following flows:
    /administration/bucket-replication/enable-server-side-one-way-bucket-replication
    /administration/bucket-replication/enable-server-side-two-way-bucket-replication
    /administration/bucket-replication/enable-server-side-multi-site-bucket-replication
-   /administration/bucket-replication/server-side-replication-resynchronize-remote   
+   /administration/bucket-replication/server-side-replication-resynchronize-remote   

source/includes/common-replication.rst

@@ -107,6 +107,20 @@ See :mc:`mc admin user`, :mc:`mc admin user svcacct`, and :mc:`mc admin policy`
 
 .. end-replication-required-permissions
 
+.. start-replication-sync-vs-async
+
+MinIO supports specifying either asynchronous (default) or synchronous replication for a given remote target.
+
+With asynchronous replication, MinIO completes the originating ``PUT`` operation *before* placing the object into a :ref:`replication queue <minio-replication-process>`.
+The originating client may therefore see a successful ``PUT`` operation *before* the object is replicated.
+While this may result in stale or missing objects on the remote, it mitigates the risk of slow write operations due to replication load.
+
+With synchronous replication, MinIO attempts to replicate the object *prior* to completing the originating ``PUT`` operation.
+MinIO returns a successful ``PUT`` operation whether or not the replication attempt succeeds.
+This reduces the risk of slow write operations at a possible cost of stale or missing objects on the remote location.
+
+.. end-replication-sync-vs-async
+
 .. start-mc-admin-replicate-what-replicates
 
 Each MinIO deployment ("peer site") synchronizes the following changes across the other peer sites:
@@ -143,4 +157,4 @@ When replicating to multi-node sites, use the URL or IP address of the site's lo
 
 Using a single node for configuring site replication creates a single point of failure, where that node being offline results in replication failure.
 
-.. end-mc-admin-replicate-load-balancing
+.. end-mc-admin-replicate-load-balancing

source/operations/install-deploy-manage/multi-site-replication.rst

@@ -139,6 +139,16 @@ Use :mc:`mc replicate rm` on the command line or the MinIO Console to remove buc
 Only one site can have data when setting up site replication.
 All other sites must be empty.
 
+Synchronous vs Asynchronous Replication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-replication.rst
+   :start-after: start-replication-sync-vs-async
+   :end-before: end-replication-sync-vs-async
+
+MinIO strongly recommends using the default asynchronous site replication.
+To configure synchronous site replication use :mc-cmd:`mc admin replicate update` with the :mc-cmd:`~mc admin replicate update --sync` option.
+
 Tutorials
 ---------
 

source/reference/minio-mc-admin/mc-admin-replicate.rst

@@ -80,6 +80,9 @@ Syntax
    :fullpath:
 
    Create or expand a site replication configuration.
+   The configuration uses asynchronous site replication by default, as MinIO recommends.
+
+   If your circumstances require synchronous site replication, complete the configuration, then use :mc-cmd:`mc admin replicate update --sync`.
 
    .. tab-set::
 
@@ -176,6 +179,13 @@ Syntax
       
       The new endpoint or URL to associate with the peer site.
 
+   .. mc-cmd:: --sync
+      :optional:
+
+      Enable or disable synchronous site replication.
+      Available values are ``enable`` and ``disable``.
+      If not defined, MInIO uses asynchronous site replication.
+
 .. mc-cmd:: rm
    :fullpath:
 
@@ -306,7 +316,7 @@ Syntax
                                 minio1          \
                                 --bucket images
 
-         Display the site repliction status for the setting for a user, ``janedoe``, across sites for a site replication configuration that contains the site ``minio1``.
+         Display the site replication status for the setting for a user, ``janedoe``, across sites for a site replication configuration that contains the site ``minio1``.
 
          .. code-block:: shell
 
@@ -348,7 +358,7 @@ Syntax
    .. mc-cmd:: --bucket
       :optional:
      
-      Display the replciation status of a specific buckt by inlcuding the bucket name after the flag.
+      Display the replication status of a specific bucket by including the bucket name after the flag.
 
    .. mc-cmd:: --groups
       :optional:
@@ -445,4 +455,4 @@ Global Flags
 
 .. include:: /includes/common-minio-mc.rst
    :start-after: start-minio-mc-globals
-   :end-before: end-minio-mc-globals
+   :end-before: end-minio-mc-globals