diff --git a/source/images/minio-console/console-settings-site-replication-add.png b/source/images/minio-console/console-settings-site-replication-add.png new file mode 100644 index 00000000..ab2e9b29 Binary files /dev/null and b/source/images/minio-console/console-settings-site-replication-add.png differ diff --git a/source/images/minio-console/console-settings-site-replication-confirm-delete.png b/source/images/minio-console/console-settings-site-replication-confirm-delete.png new file mode 100644 index 00000000..4c9108be Binary files /dev/null and b/source/images/minio-console/console-settings-site-replication-confirm-delete.png differ diff --git a/source/images/minio-console/console-settings-site-replication-edit-endpoint.png b/source/images/minio-console/console-settings-site-replication-edit-endpoint.png new file mode 100644 index 00000000..337eefa6 Binary files /dev/null and b/source/images/minio-console/console-settings-site-replication-edit-endpoint.png differ diff --git a/source/images/minio-console/console-settings-site-replication-status-item.png b/source/images/minio-console/console-settings-site-replication-status-item.png new file mode 100644 index 00000000..ee47ede2 Binary files /dev/null and b/source/images/minio-console/console-settings-site-replication-status-item.png differ diff --git a/source/images/minio-console/console-settings-site-replication-status-summary.png b/source/images/minio-console/console-settings-site-replication-status-summary.png new file mode 100644 index 00000000..a8d93752 Binary files /dev/null and b/source/images/minio-console/console-settings-site-replication-status-summary.png differ diff --git a/source/images/minio-console/console-site-replication-delete-button.png b/source/images/minio-console/console-site-replication-delete-button.png new file mode 100644 index 00000000..3cdae00d Binary files /dev/null and b/source/images/minio-console/console-site-replication-delete-button.png differ diff --git a/source/images/minio-console/console-site-replication-edit-button.png b/source/images/minio-console/console-site-replication-edit-button.png new file mode 100644 index 00000000..00124903 Binary files /dev/null and b/source/images/minio-console/console-site-replication-edit-button.png differ diff --git a/source/images/minio-console/console-site-replication-list-of-sites.png b/source/images/minio-console/console-site-replication-list-of-sites.png new file mode 100644 index 00000000..0e37cc19 Binary files /dev/null and b/source/images/minio-console/console-site-replication-list-of-sites.png differ diff --git a/source/images/replication/site-relication-command-line-status-all.png b/source/images/replication/site-relication-command-line-status-all.png new file mode 100644 index 00000000..48996b87 Binary files /dev/null and b/source/images/replication/site-relication-command-line-status-all.png differ diff --git a/source/includes/common-replication.rst b/source/includes/common-replication.rst index 64512c7b..8d3380f5 100644 --- a/source/includes/common-replication.rst +++ b/source/includes/common-replication.rst @@ -94,4 +94,34 @@ Bucket replication requires specific permissions on the source and destination d See :mc:`mc admin user`, :mc:`mc admin user svcacct`, and :mc:`mc admin policy` for more complete documentation on adding users, service accounts, and policies to a MinIO deployment. -.. end-replication-required-permissions \ No newline at end of file +.. end-replication-required-permissions + +.. start-mc-admin-replicate-what-replicates + +Each MinIO deployment ("peer site") synchronizes the following changes across the other peer sites: + +- Creation, modification, and deletion of buckets and objects, including + + - Bucket and Object Configurations + - :ref:`Policies ` + - :mc-cmd:`mc tag set` + - :ref:`Locks `, including retention and legal hold configurations + - :ref:`Encryption settings ` + +- Creation and deletion of IAM users, groups, policies, and policy mappings to users or groups (for LDAP users or groups) +- Creation of Security Token Service (STS) credentials for session tokens verifiable from the local ``root`` credentials +- Creation and deletion of :ref:`service accounts ` (except those owned by the ``root`` user) + +Site replication enables :ref:`bucket versioning ` for all new and existing buckets on all replicated sites. + +.. end-mc-admin-replicate-what-replicates + +.. start-mc-admin-replicate-what-does-not-replicate + +MinIO deployments in a site replication configuration do *not* replicate the creation or modification of the following items: + +- :ref:`Bucket notifications ` +- :ref:`Lifecycle management (ILM) configurations ` +- :ref:`Site configuration settings ` + +.. end-mc-admin-replicate-what-does-not-replicate \ No newline at end of file diff --git a/source/reference/minio-mc-admin.rst b/source/reference/minio-mc-admin.rst index e4860f10..a1dd4637 100644 --- a/source/reference/minio-mc-admin.rst +++ b/source/reference/minio-mc-admin.rst @@ -90,6 +90,11 @@ The following table lists :mc-cmd:`mc admin` commands: :start-after: start-mc-admin-prometheus-desc :end-before: end-mc-admin-prometheus-desc + * - :mc:`mc admin replicate` + - .. include:: /reference/minio-mc-admin/mc-admin-replicate.rst + :start-after: start-mc-admin-replicate-desc + :end-before: end-mc-admin-replicate-desc + * - :mc:`mc admin service` - .. include:: /reference/minio-mc-admin/mc-admin-service.rst :start-after: start-mc-admin-service-desc diff --git a/source/reference/minio-mc-admin/mc-admin-replicate.rst b/source/reference/minio-mc-admin/mc-admin-replicate.rst new file mode 100644 index 00000000..9a810854 --- /dev/null +++ b/source/reference/minio-mc-admin/mc-admin-replicate.rst @@ -0,0 +1,372 @@ +.. _minio-mc-admin-replicate: + +====================== +``mc admin replicate`` +====================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc admin replicate + +Description +----------- + +.. start-mc-admin-replicate-desc + +The :mc:`mc admin replicate` command creates and manages :ref:`site replication ` for a set of MinIO peer sites. + +Site replication mimics an active-active bucket replication, but for multiple MinIO deployments. +Wherever a change occurs to IAM settings, buckets, or objects across the set of sites, the change replicates across all sites in the site replication group. + +.. end-mc-admin-replicate-desc + +Where :ref:`bucket replication ` manages the mirroring of particular buckets or objects from one location to another within a deployment or across deployments, site replication continuously mirrors an entire MinIO site to other sites. + +:mc:`mc admin replicate` only supports site replication for :ref:`distributed deployments ` when configuring site replication. + +Only one deployment can have any data when initiating a new site replication configuration. + +Site replication enforces :ref:`bucket versioning ` on all buckets, including existing buckets and any buckets added after initiating site replication. + +.. admonition:: Use ``mc admin`` on MinIO Deployments Only + :class: note + + .. include:: /includes/facts-mc-admin.rst + :start-after: start-minio-only + :end-before: end-minio-only + + +The :mc:`mc admin replicate` command has the following subcommands: + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Subcommand + - Description + + * - :mc-cmd:`mc admin replicate add` + - Create a new site replication configuration or expand an existing configuration. + + * - :mc-cmd:`mc admin replicate edit` + - Edits the endpoint of the specified peer site in the site replication configuration. + + * - :mc-cmd:`mc admin replicate info` + - Returns information about site replication configuration. + + * - :mc-cmd:`mc admin replicate remove` + - Removes an entire site replication configuration or one or more peer sites from participating in site replication. + + * - :mc-cmd:`mc admin replicate status` + - Displays the status for :ref:`replicable data ` across participating sites. + +Syntax +------ + +.. mc-cmd:: add + :fullpath: + + Create or expand a site replication configuration. + + .. tab-set:: + + .. tab-item:: EXAMPLES + + Consider a multi-site MinIO topology with three separate MinIO deployments using the following :ref:`aliases `: ``minio1``, ``minio2``, and ``minio3``. + All three sites have complete bidirectional network access and low latency between sites. + + .. code-block:: shell + :class: copyable + + mc admin replicate add minio1 minio2 minio3 + + The following command explands an existing site replication that includes peer site ``minio1`` to an additional peer site, ``minio5``. + ``minio5`` contains no data. + + .. code-block:: shell + :class: copyable + + mc admin replicate add minio1 minio5 + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] admin replicate add \ + ALIAS1 \ + ALIAS2 \ + [ALIAS3 ...] + + .. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of a MinIO deployment to include in site replication. + + At least two MinIO deployment aliases are required to create a site replication. + Only the first alias can have buckets or objects. + The first site can also be empty. + + To expand an existing site replication to one more new replication sites, the first :ref:`alias ` must be a peer site in the site replication set to expand. + Then include one or more additional :ref:`aliases ` to add to the existing site replication. + The deployments to add must be empty. + + +.. mc-cmd:: edit + :fullpath: + + Modifies the endpoint used for an existing peer site participating in site replication. + + .. tab-set:: + + .. tab-item:: EXAMPLE + + .. code-block:: shell + :class: copyable + + mc admin replicate edit \ + minio2 \ + --deployment-id c1758167-4426-454f-9aae-5c3dfdf6df64 \ + --endpoint https://minio2:9000 + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + + mc [GLOBALFLAGS] admin replicate edit \ + ALIAS \ + --deployment-id [deploymentID] \ + --endpoint [newEndpoint] + + .. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + + .. mc-cmd:: --deployment-id + :required: + + The unique id of the deployment to change. + + The deployment ID can be found by running :mc-cmd:`mc admin replicate info ALIAS` + + .. mc-cmd:: --endpoint + :required: + + The new endpoint or URL to associate with the peer site. + +.. mc-cmd:: remove + :fullpath: + + Removes one or more sites from a site replication configuration. + + Remember, if you intend to re-add the site to a site replication configuration in the future, it must be empty of :ref:`replicable data `. + + .. tab-set:: + + .. tab-item:: EXAMPLES + + Remove site replication for all connected sites for an existing site replication configuration that includes `minio2`. + This deletes the site replication configuration for all participating sites. + + .. code-block:: shell + :class: copyable + + mc admin replicate remove \ + minio2 \ + --all \ + --force + + Remove the sites with alias names ``minio5`` and ``minio6`` from an existing site replication configuration that includes `minio2` + + .. code-block:: shell + :class: copyable + + mc admin replicate remove \ + minio2 \ + minio5 \ + minio6 \ + --force \ + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + + mc [GLOBALFLAGS] admin remove \ + TARGET \ + ALIAS1 \ + [ALIAS2...] \ + --all \ + --force + + .. mc-cmd:: TARGET + :required: + + The :ref:`alias ` of an active MinIO deployment participating in the site replication to target. + Do not use an alias of a deployment to be removed, unless removing all sites from site replication. + + .. mc-cmd:: ALIAS + :optional: + + The :ref:`alias ` of an active MinIO deployment to remove from a site replication configuration. + May be repeated to remove additional sites. + + .. mc-cmd:: --all + :optional: + + Include this flag to remove all sites configured for site replication and end the site replication configuration. + + .. mc-cmd:: --force + :required: + + This flag forces the removal of the specified peer site(s) from the site replication configuration. + + +.. mc-cmd:: info + :fullpath: + + Returns information about the sites in the site replication configuration. + + .. tab-set:: + + .. tab-item:: EXAMPLE + + .. code-block:: shell + :class: copyable + + mc admin replicate info minio1 + + .. tab-item:: SYNTAX + + .. code-block:: shell + + mc [GLOBALFLAGS] admin replicate info ALIAS + + .. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of an active MinIO deployment in the site replication configuration. + + +.. mc-cmd:: status + :fullpath: + + Displays the status of the sites, buckets, users, groups, or policies for a site replication configuration. + + .. tab-set:: + + .. tab-item:: EXAMPLES + + Display the overall replication status for a site replication configuration that includes the site ``minio1``. + + .. code-block:: shell + + mc admin replicate status minio1 + + Display the replication status of buckets across sites for a site replication configuration that includes the site ``minio1``. + + .. code-block:: shell + + mc admin replicate status \ + minio1 \ + --buckets + + Display the site replication status of a bucket called ``images`` across sites for a site replication configuration that contains the site ``minio1``. + + .. code-block:: shell + + mc admin replicate status \ + 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``. + + .. code-block:: shell + + mc admin replicate status \ + minio1 \ + --user janedoe + + .. tab-item:: SYNTAX + + .. code-block:: shell + + mc [GLOBALFLAGS] admin replicate status \ + TARGET \ + [--all] \ + [--buckets] \ + [--bucket nameOfBucket] \ + [--groups] \ + [--group nameOfGroup] \ + [--policies] \ + [--policy nameOfPolicy] \ + [--users] \ + [--user accessKey] + + .. mc-cmd:: TARGET + :required: + + The :ref:`alias ` of an active MinIO deployment in the site replication configuration. + + .. mc-cmd:: --all + :optional: + + Display all available site replication status information. + + .. mc-cmd:: --buckets + :optional: + + Display the replication status of all buckets. + + .. mc-cmd:: --bucket + :optional: + + Display the replciation status of a specific buckt by inlcuding the bucket name after the flag. + + .. mc-cmd:: --groups + :optional: + + Display the replication status of all groups. + + .. mc-cmd:: --group + :optional: + + Display the replication status of a specific group by including the group name after the flag. + + .. mc-cmd:: --policies + :optional: + + Display the replication status of all policies. + + .. mc-cmd:: --policy + :optional: + + Display the replication status of a specific policy by including the policy name after the flag. + + .. mc-cmd:: --users + :optional: + + Display the replication status of all users. + + .. mc-cmd:: --user + :optional: + + Display the replication status of a specific user by including the user name after the flag. + + +Global Flags +------------ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals \ No newline at end of file diff --git a/source/reference/minio-mc-admin/mc-admin-user-svcacct.rst b/source/reference/minio-mc-admin/mc-admin-user-svcacct.rst index 0fcc6a8c..100ca76e 100644 --- a/source/reference/minio-mc-admin/mc-admin-user-svcacct.rst +++ b/source/reference/minio-mc-admin/mc-admin-user-svcacct.rst @@ -1,3 +1,5 @@ +.. _minio-mc-admin-user-svcacct: + ========================= ``mc admin user svcacct`` ========================= diff --git a/source/reference/minio-mc-admin/mc-admin.config.rst b/source/reference/minio-mc-admin/mc-admin.config.rst index c6bb7bac..f617d42a 100644 --- a/source/reference/minio-mc-admin/mc-admin.config.rst +++ b/source/reference/minio-mc-admin/mc-admin.config.rst @@ -1,3 +1,5 @@ +.. _minio-mc-admin-config: + =================== ``mc admin config`` =================== diff --git a/source/replication/bucket-replication-overview.rst b/source/replication/bucket-replication-overview.rst new file mode 100644 index 00000000..9675b1b2 --- /dev/null +++ b/source/replication/bucket-replication-overview.rst @@ -0,0 +1,313 @@ +.. _minio-bucket-replication: + +================== +Bucket Replication +================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +MinIO supports server-side and client-side replication of objects between source +and destination buckets. + +:ref:`Server-Side Bucket Replication ` + Configure per-bucket rules for automatically synchronizing objects between + buckets within the same MinIO cluster *or* between two independent MinIO + Clusters. MinIO applies rules as part of object write operations + (e.g. ``PUT``) and automatically synchronizes new objects *and* object + mutations, such as new object versions or changes to object metadata. + + MinIO server-side bucket replication only supports MinIO clusters for the + remote replication target. + +:ref:`Client-side Bucket Replication ` + Use The command process to synchronize objects between buckets + within the same S3-compatible cluster *or* between two independent + S3-compatible clusters. Client-side replication using :mc-cmd:`mc mirror` + supports MinIO-to-S3 and similar replication configurations. + +.. _minio-bucket-replication-serverside: + +Server-Side Bucket Replication +------------------------------ + +MinIO server-side bucket replication is an automatic bucket-level configuration +that synchronizes objects between a source and destination bucket. MinIO +server-side replication *requires* the source and destination bucket be two separate MinIO +clusters. + +For each write operation to the bucket, MinIO checks all configured replication +rules for the bucket and applies the matching rule with highest configured +priority. MinIO synchronizes new objects *and* object mutations, such as +new object versions or changes to object metadata. This includes +metadata operations such as enabling or modifying object locking or +retention settings. + +MinIO server-side bucket replication is functionally similar to Amazon S3 +replication while adding the following MinIO-only features: + +- Source and destination bucket names can match, supporting site-to-site + use cases such as Splunk or Veeam BC/DR. + +- Simplified implementation than S3 bucket replication configuration, removing + the need to configure settings like AccessControlTranslation, Metrics, and + SourceSelectionCriteria. + +- 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-behavior-resync: + +Resynchronization (Disaster Recovery) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Resynchronization primarily supports recovery after partial or total loss of the +data on a MinIO deployment using a healthy deployment in the replica +configuration. Use the :mc-cmd:`mc replicate resync` command completely +resynchronize the remote target (:mc-cmd:`mc admin bucket remote`) using the +specified source bucket. + +The resynchronization process checks all objects in the source bucket against +all configured replication rules that include :ref:`existing object replication +`. For each object which matches a +rule, the resynchronization process places the object into the replication +:ref:`queue ` regardless of the object's current +:ref:`replication status `. + +MinIO skips synchronizing those objects whose remote copy exactly match the +source, including object metadata. MinIO otherwise does not prioritize or modify +the queue with regards to the existing contents of the target. + +:mc-cmd:`mc replicate resync` operates at the bucket level and does +*not* support prefix-level granularity. Initiating resynchronization on a large +bucket may result in a significant increase in replication-related load +and traffic. Use this command with caution and only when necessary. + +For buckets with :ref:`object transition (Tiering) +` configured, replication resynchronization +restores objects in a non-transitioned state with no associated transition +metadata. Any data previously transitioned to the remote storage is therefore +permanently disconnected from the remote MinIO deployment. For tiering +configurations which specify an explicit human-readable prefix as part of the +remote configuration, you can safely purge the transitioned data in that prefix +to avoid costs associated to the "lost" data. + +.. _minio-replication-behavior-delete: + +Replication of Delete Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO supports replicating delete operations, where MinIO synchronizes +deleting specific object versions *and* new +:s3-docs:`delete markers `. Delete operation +replication uses the same :ref:`replication process ` +as all other replication operations. + +MinIO requires explicitly enabling versioned deletes and delete marker +replication . Use the :mc-cmd:`mc replicate add --replicate` field to +specify both or either ``delete`` and ``delete-marker`` to enable versioned +deletes and delete marker replication respectively. To enable both, specify both +strings using a comma separator ``delete,delete-marker``. + +For delete marker replication, MinIO begins the replication process after +a delete operation creates the delete marker. MinIO uses the +``X-Minio-Replication-DeleteMarker-Status`` metadata field for tracking +delete marker replication status. In +:ref:`active-active ` +replication configurations, MinIO may produce duplicate delete markers if +both clusters concurrently create a delete marker for an object *or* +if one or both clusters were down before the replication event synchronized. + +For replicating the deletion of a specific object version, MinIO marks the +object version as ``PENDING`` until replication completes. Once the remote +target deletes that object version, MinIO deletes the object on the source. +While this process ensures near-synchronized version deletion, it may result +in listing operations returning the object version after the initial +delete operation. MinIO uses the ``X-Minio-Replication-Delete-Status`` for +tracking delete version replication status. + +MinIO only replicates explicit client-driven delete operations. MinIO does *not* +replicate objects deleted from the application of +:ref:`lifecycle management expiration rules +`. For :ref:`active-active +` configurations, set the same +expiration rules on *all* of of the replication buckets to ensure consistent +application of object expiration. + +.. admonition:: MinIO Trims Empty Object Prefixes on Source and Remote Bucket + :class: note, dropdown + + If a delete operation removes the last object in a bucket prefix, MinIO + recursively removes each empty part of the prefix up to the bucket root. + MinIO only applies the recursive removal to prefixes created *implicitly* as + part of object write operations - that is, the prefix was not created using + an explicit directory creation command such as :mc:`mc mb`. + + If a replication rule enables replication delete operations, the replication + process *also* applies the implicit prefix trimming behavior on the + destination MinIO cluster. + + For example, consider a bucket ``photos`` with the following object prefixes: + + - ``photos/2021/january/myphoto.jpg`` + - ``photos/2021/february/myotherphoto.jpg`` + - ``photos/NYE21/NewYears.jpg`` + + ``photos/NYE21`` is the *only* prefix explicitly created using :mc:`mc mb`. + All other prefixes were *implicitly* created as part of writing the object + located at that prefix. + + - A command removes ``myphoto.jpg``. MinIO automatically trims the empty + ``/janaury`` prefix. + + - A command then removes the ``myotherphoto.jpg``. MinIO automatically + trims the ``/february`` prefix *and* the now-empty ``/2021`` prefix. + + - A command removes the ``NewYears.jpg`` object. MinIO leaves the + ``/NYE21`` prefix remains in place since it was *explicitly* created. + +.. _minio-replication-behavior-existing-objects: + +Replication of Existing Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO by default does not enable existing object replication. Objects +created before replication was configured *or* while replication is +disabled are not synchronized to the target deployment. +Starting with :mc:`mc` :minio-git:`RELEASE.2021-06-13T17-48-22Z +` and :mc:`minio` +:minio-git:`RELEASE.2021-06-07T21-40-51Z +`, MinIO supports enabling +replication of existing objects in a bucket. + +Enabling existing object replication marks all objects or object prefixes that +satisfy the replication rules as eligible for synchronization to the source +cluster, *even if* those objects were created prior to configuring or enabling +replication. You can enable existing object replication while configuring +or modifying a replication rule: + +- For new replication rules, include ``"existing-objects"`` to the list of + replication features specified to :mc-cmd:`mc replicate add --replicate`. + +- For existing replication rules, add ``"existing-objects"`` to the list of + existing replication features using + :mc-cmd:`mc replicate edit --replicate`. You must specify *all* desired + replication features when editing the replication rule. + +Enabling existing object replication does not increase the priority of objects +pending replication. MinIO uses the same core +:ref:`replication scanner and queue system ` for +detecting and synchronizing objects regardless of the enabled replication +feature. The time required to fully synchronize a bucket depends on a number of +factors, including but not limited to the current cluster replication load, +overall cluster load, and the size of the namespace (all objects in the bucket). + +If versioning was not previously enabled when configuring bucket replication, +existing objects have a ``versionid = null``. These objects do replicate. + +MinIO existing object replication +implements functionality similar to +`AWS: Replicating existing objects between S3 buckets +`__ +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 +`. 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. + +You must explicitly enable synchronous replication when configuring the remote +target target using the :mc-cmd:`mc admin bucket remote add` command with the +:mc-cmd:`~mc admin bucket remote add` flag. + +Replication Internals +~~~~~~~~~~~~~~~~~~~~~ + +This section documents internal replication behavior and is not critical to +using or implementing replication. This documentation is provided strictly +for learning and educational purposes. + +.. _minio-replication-process: + +Replication Process ++++++++++++++++++++ + +MinIO uses a replication queuing system with multiple concurrent replication +workers operating on that queue. MinIO continuously works to replicate and +remove objects from the queue while scanning for new unreplicated objects to +add to the queue. + +MinIO sets the ``X-Amz-Replication-Status`` metadata field according to the +replication state of the object: + +.. list-table:: + :header-rows: 1 + :width: 100% + :widths: 30 70 + + * - Replication State + - Description + + * - ``PENDING`` + - The object has not yet been replicated. MinIO applies this state + if the object meets one of the configured replication rules on the + 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. + + * - ``FAILED`` + - The object failed to replicate to the remote cluster. + + MinIO continuously scans for ``FAILED`` objects not yet in the + replication queue and adds them to the queue as space is available. + + * - ``REPLICA`` + - The object is itself a replica from a remote source. + +The replication process generally has one of the following flows: + +- ``PENDING -> COMPLETED`` +- ``PENDING -> FAILED -> COMPLETED`` + +.. toctree:: + :hidden: + :titlesonly: + + /replication/enable-server-side-one-way-bucket-replication + /replication/enable-server-side-two-way-bucket-replication + /replication/enable-server-side-multi-site-bucket-replication + /replication/server-side-replication-resynchronize-remote + +.. _minio-bucket-replication-clientside: + +Client-Side Bucket Replication +------------------------------ + +The :mc:`mc` command :mc-cmd:`mc mirror` supports watching a source bucket +and automatically replicating objects to a destination bucket. diff --git a/source/replication/replication-overview.rst b/source/replication/replication-overview.rst index 6c973946..2fc78875 100644 --- a/source/replication/replication-overview.rst +++ b/source/replication/replication-overview.rst @@ -1,323 +1,70 @@ -.. _minio-bucket-replication: +.. _minio-replication-overview: -================== -Bucket Replication -================== +==================== +Replication Overview +==================== .. default-domain:: minio .. contents:: Table of Contents :local: - :depth: 2 + :depth: 1 -MinIO supports server-side and client-side replication of objects between source -and destination buckets. +Replication duplicates objects from one MinIO location to another MinIO location. +This provides a means for data backup and recovery or for geographic distribution across regions. -:ref:`Server-Side Bucket Replication ` - Configure per-bucket rules for automatically synchronizing objects between - buckets within the same MinIO cluster *or* between two independent MinIO - Clusters. MinIO applies rules as part of object write operations - (e.g. ``PUT``) and automatically synchronizes new objects *and* object - mutations, such as new object versions or changes to object metadata. - - MinIO server-side bucket replication only supports MinIO clusters for the - remote replication target. +MinIO supports two types of replication: -:ref:`Client-side Bucket Replication ` - Use The command process to synchronize objects between buckets - within the same S3-compatible cluster *or* between two independent - S3-compatible clusters. Client-side replication using :mc-cmd:`mc mirror` - supports MinIO-to-S3 and similar replication configurations. +#. :ref:`Bucket Replication ` +#. :ref:`Site Replication ` -.. _minio-bucket-replication-serverside: +You can use one or the other, but not both types of replication. -Server-Side Bucket Replication ------------------------------- +.. note:: -MinIO server-side bucket replication is an automatic bucket-level configuration -that synchronizes objects between a source and destination bucket. MinIO -server-side replication *requires* the source and destination bucket be MinIO -clusters. The source and destination bucket *may* be the same MinIO cluster *or* -two independent MinIO clusters. + MinIO also provides the :mc-cmd:`mc mirror` command. + ``mc mirror`` is similar to bucket replication with the difference that bucket replication is between two MinIO locations. + ``mc mirror`` duplicates objects between any two S3-compliant locations. -For each write operation to the bucket, MinIO checks all configured replication -rules for the bucket and applies the matching rule with highest configured -priority. MinIO synchronizes new objects *and* object mutations, such as -new object versions or changes to object metadata. This includes -metadata operations such as enabling or modifying object locking or -retention settings. +Bucket Replication +------------------ -MinIO server-side bucket replication is functionally similar to Amazon S3 -replication while adding the following MinIO-only features: +Bucket replication duplicates the content of a specific bucket from one MinIO location to another MinIO location. +The target location can be within a MinIO deployment or across deployments. -- Source and destination bucket names can match, supporting site-to-site - use cases such as Splunk or Veeam BC/DR. +Bucket replication can be either ``active-active`` or ``active-passive``. -- Simplified implementation than S3 bucket replication configuration, removing - the need to configure settings like AccessControlTranslation, Metrics, and - SourceSelectionCriteria. +Active-active bucket replication is two-way replication where changes on either bucket duplicate to the other bucket. -- Active-Active (Two-Way) replication of objects between source and destination - buckets. +:ref:`Active-passive bucket replication ` is one-way replication where only changes on the origin bucket are made to the target bucket. +With active-passive bucket repliction, changes made on the target bucket do not replicate to the origin bucket. -- Multi-Site replication of objects between three or more MinIO deployments - (New in :minio-release:`RELEASE.2021-09-23T04-46-24Z`). -.. _minio-replication-behavior-resync: +Site Replication +---------------- -Resynchronization (Disaster Recovery) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Site replication expands the features of bucket replication to include IAM, security tokens, service accounts, and bucket features the same across all sites. -Resynchronization primarily supports recovery after partial or total loss of the -data on a MinIO deployment using a healthy deployment in the replica -configuration. Use the :mc-cmd:`mc replicate resync` command completely -resynchronize the remote target (:mc-cmd:`mc admin bucket remote`) using the -specified source bucket. +:ref:`Site replication ` links multiple MinIO deployments together and keeps the buckets, objects, and Identify and Access Management (IAM) settings in sync across all connected sites. -The resynchronization process checks all objects in the source bucket against -all configured replication rules that include :ref:`existing object replication -`. For each object which matches a -rule, the resynchronization process places the object into the replication -:ref:`queue ` regardless of the object's current -:ref:`replication status `. +.. include:: /includes/common-replication.rst + :start-after: start-mc-admin-replicate-what-replicates + :end-before: end-mc-admin-replicate-what-replicates -MinIO skips synchronizing those objects whose remote copy exactly match the -source, including object metadata. MinIO otherwise does not prioritize or modify -the queue with regards to the existing contents of the target. -:mc-cmd:`mc replicate resync` operates at the bucket level and does -*not* support prefix-level granularity. Initiating resynchronization on a large -bucket may result in a significant increase in replication-related load -and traffic. Use this command with caution and only when necessary. +What Does Not Replicate? +~~~~~~~~~~~~~~~~~~~~~~~~ -For buckets with :ref:`object transition (Tiering) -` configured, replication resynchronization -restores objects in a non-transitioned state with no associated transition -metadata. Any data previously transitioned to the remote storage is therefore -permanently disconnected from the remote MinIO deployment. For tiering -configurations which specify an explicit human-readable prefix as part of the -remote configuration, you can safely purge the transitioned data in that prefix -to avoid costs associated to the "lost" data. +Not everything replicates across sites. -.. _minio-replication-behavior-delete: +.. include:: /includes/common-replication.rst + :start-after: start-mc-admin-replicate-what-does-not-replicate + :end-before: end-mc-admin-replicate-what-does-not-replicate -Replication of Delete Operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MinIO supports replicating delete operations, where MinIO synchronizes -deleting specific object versions *and* new -:s3-docs:`delete markers `. Delete operation -replication uses the same :ref:`replication process ` -as all other replication operations. - -MinIO requires explicitly enabling versioned deletes and delete marker -replication . Use the :mc-cmd:`mc replicate add --replicate` field to -specify both or either ``delete`` and ``delete-marker`` to enable versioned -deletes and delete marker replication respectively. To enable both, specify both -strings using a comma separator ``delete,delete-marker``. - -For delete marker replication, MinIO begins the replication process after -a delete operation creates the delete marker. MinIO uses the -``X-Minio-Replication-DeleteMarker-Status`` metadata field for tracking -delete marker replication status. In -:ref:`active-active ` -replication configurations, MinIO may produce duplicate delete markers if -both clusters concurrently create a delete marker for an object *or* -if one or both clusters were down before the replication event synchronized. - -For replicating the deletion of a specific object version, MinIO marks the -object version as ``PENDING`` until replication completes. Once the remote -target deletes that object version, MinIO deletes the object on the source. -While this process ensures near-synchronized version deletion, it may result -in listing operations returning the object version after the initial -delete operation. MinIO uses the ``X-Minio-Replication-Delete-Status`` for -tracking delete version replication status. - -MinIO only replicates explicit client-driven delete operations. MinIO does *not* -replicate objects deleted from the application of -:ref:`lifecycle management expiration rules -`. For :ref:`active-active -` configurations, set the same -expiration rules on *all* of of the replication buckets to ensure consistent -application of object expiration. - -.. admonition:: MinIO Trims Empty Object Prefixes on Source and Remote Bucket - :class: note, dropdown - - If a delete operation removes the last object in a bucket prefix, MinIO - recursively removes each empty part of the prefix up to the bucket root. - MinIO only applies the recursive removal to prefixes created *implicitly* as - part of object write operations - that is, the prefix was not created using - an explicit directory creation command such as :mc:`mc mb`. - - If a replication rule enables replication delete operations, the replication - process *also* applies the implicit prefix trimming behavior on the - destination MinIO cluster. - - For example, consider a bucket ``photos`` with the following object prefixes: - - - ``photos/2021/january/myphoto.jpg`` - - ``photos/2021/february/myotherphoto.jpg`` - - ``photos/NYE21/NewYears.jpg`` - - ``photos/NYE21`` is the *only* prefix explicitly created using :mc:`mc mb`. - All other prefixes were *implicitly* created as part of writing the object - located at that prefix. - - - A command removes ``myphoto.jpg``. MinIO automatically trims the empty - ``/janaury`` prefix. - - - A command then removes the ``myotherphoto.jpg``. MinIO automatically - trims the ``/february`` prefix *and* the now-empty ``/2021`` prefix. - - - A command removes the ``NewYears.jpg`` object. MinIO leaves the - ``/NYE21`` prefix remains in place since it was *explicitly* created. - -.. _minio-replication-behavior-existing-objects: - -Replication of Existing Objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MinIO by default does not enable existing object replication. Objects -created before replication was configured *or* while replication is -disabled are not synchronized to the target deployment. -Starting with :mc:`mc` :minio-git:`RELEASE.2021-06-13T17-48-22Z -` and :mc:`minio` -:minio-git:`RELEASE.2021-06-07T21-40-51Z -`, MinIO supports enabling -replication of existing objects in a bucket. - -Enabling existing object replication marks all objects or object prefixes that -satisfy the replication rules as eligible for synchronization to the source -cluster, *even if* those objects were created prior to configuring or enabling -replication. You can enable existing object replication while configuring -or modifying a replication rule: - -- For new replication rules, include ``"existing-objects"`` to the list of - replication features specified to :mc-cmd:`mc replicate add --replicate`. - -- For existing replication rules, add ``"existing-objects"`` to the list of - existing replication features using - :mc-cmd:`mc replicate edit --replicate`. You must specify *all* desired - replication features when editing the replication rule. - -Enabling existing object replication does not increase the priority of objects -pending replication. MinIO uses the same core -:ref:`replication scanner and queue system ` for -detecting and synchronizing objects regardless of the enabled replication -feature. The time required to fully synchronize a bucket depends on a number of -factors, including but not limited to the current cluster replication load, -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 ` enabled when the -object was created. You can use The command 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 -`AWS: Replicating existing objects between S3 buckets -`__ -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 -`. 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. - -You must explicitly enable synchronous replication when configuring the remote -target target using the :mc-cmd:`mc admin bucket remote add` command with the -:mc-cmd:`~mc admin bucket remote add` flag. - -Replication Internals -~~~~~~~~~~~~~~~~~~~~~ - -This section documents internal replication behavior and is not critical to -using or implementing replication. This documentation is provided strictly -for learning and educational purposes. - -.. _minio-replication-process: - -Replication Process -+++++++++++++++++++ - -MinIO uses a replication queuing system with multiple concurrent replication -workers operating on that queue. MinIO continuously works to replicate and -remove objects from the queue while scanning for new unreplicated objects to -add to the queue. - -MinIO sets the ``X-Amz-Replication-Status`` metadata field according to the -replication state of the object: - -.. list-table:: - :header-rows: 1 - :width: 100% - :widths: 30 70 - - * - Replication State - - Description - - * - ``PENDING`` - - The object has not yet been replicated. MinIO applies this state - if the object meets one of the configured replication rules on the - 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. - - * - ``FAILED`` - - The object failed to replicate to the remote cluster. - - MinIO continuously scans for ``FAILED`` objects not yet in the - replication queue and adds them to the queue as space is available. - - * - ``REPLICA`` - - The object is itself a replica from a remote source. - - MinIO ignores ``REPLICA`` objects, including any metadata-only changes - to that object. MinIO does not support - AWS `replica modification sync - `__ - at this time. - -The replication process generally has one of the following flows: - -- ``PENDING -> COMPLETED`` -- ``PENDING -> FAILED -> COMPLETED`` .. toctree:: - :hidden: :titlesonly: + :hidden: - /replication/enable-server-side-one-way-bucket-replication - /replication/enable-server-side-two-way-bucket-replication - /replication/enable-server-side-multi-site-bucket-replication - /replication/server-side-replication-resynchronize-remote - -.. _minio-bucket-replication-clientside: - -Client-Side Bucket Replication ------------------------------- - -The :mc:`mc` command :mc-cmd:`mc mirror` supports watching a source bucket -and automatically replicating objects to a destination bucket. + /replication/bucket-replication-overview + /replication/site-replication-overview \ No newline at end of file diff --git a/source/replication/site-replication-overview.rst b/source/replication/site-replication-overview.rst new file mode 100644 index 00000000..42ba0603 --- /dev/null +++ b/source/replication/site-replication-overview.rst @@ -0,0 +1,524 @@ +.. _minio-site-replication-overview: + +========================= +Site Replication Overview +========================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +Site replication configures multiple independent MinIO deployments as a cluster of replicas called peer sites. + +Site replication assumes the use of either the included MinIO identity provider (IDP) *or* an external IDP. +All configured deployments must use the same IDP. +Deployments using an external IDP must use the same configuration across sites. + +Overview +-------- + +.. _minio-site-replication-what-replicates: + +What Replicates Across All Sites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-replication.rst + :start-after: start-mc-admin-replicate-what-replicates + :end-before: end-mc-admin-replicate-what-replicates + +What Does Not Replicate Across Sites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-replication.rst + :start-after: start-mc-admin-replicate-what-does-not-replicate + :end-before: end-mc-admin-replicate-what-does-not-replicate + + +Initial Site Replication Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After enabling site replication, identity and access management (IAM) settings sync in the following order: + +.. tab-set:: + + .. tab-item:: MinIO IDP + + #. Policies + #. User accounts (for local users) + #. Groups + #. Service accounts + + Service accounts for ``root`` do not sync. + + #. Policy mapping for synced user accounts + #. Policy mapping for `Security Token Service (STS) users `__ + + .. tab-item:: OIDC + + #. Policies + #. Service accounts associated to OIDC accounts with a valid :ref:`MinIO Policy `. ``root`` service accounts do not sync. + #. Policy mapping for synced user accounts + #. Policy mapping for `Security Token Service (STS) users `__ + + .. tab-item:: LDAP + + #. Policies + #. Groups + #. Service accounts associated to LDAP accounts with a valid :ref:`MinIO Policy `. ``root`` service accounts do not sync. + #. Policy mapping for synced user accounts + #. Policy mapping for `Security Token Service (STS) users `__ + +After the initial synchronization of data across peer sites, MinIO continually replicates and synchronizes :ref:`replicable data ` among all sites as they occur on any site. + + +Site Healing +~~~~~~~~~~~~ + +Any MinIO deployment in the site replication configuration can resynchronize damaged :ref:`replica-eligible data ` from the peer with the most updated ("latest") version of that data. + + +Prerequisites +------------- + +One Site with Data at Setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Only *one* site can have data at the time of setup. +The other sites must be empty of buckets and objects. + +After configuring site replication, any data on the first deployment replicates to the other sites. + + +All Sites Must Use the Same IDP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All sites must use the same :ref:`Identity Provider `. +Site replication supports the included MinIO IDP, OIDC, or LDAP. + +Access to the Same Encryption Service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For :ref:`SSE-S3 ` or :ref:`SSE-KMS ` encryption via Key Management Service (KMS), all sites must have access to a central KMS deployment. + +You can achieve this with a central KES server or multiple KES servers (say one per site) connected via a central supported :ref:`key vault server `. + +Tutorials +--------- + +Configure Site Replication +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tab-set:: + + .. tab-item:: Console + + #. :ref:`Deploy ` two or more separate MinIO sites, using the same Identity Provider for each site + + Only one site can have any buckets or objects on it. + The other site(s) must be empty. + + #. In a browser, access the Console for the site with data (if any) + + For example, ``https://:9000`` + + Replace ```` with the IP address or URL for the MinIO deployment. + + #. Select **Settings**, then **Site Replication** + + .. image:: /images/minio-console/console-settings-site-replication.png + :width: 400px + :alt: MinIO Console menu with the Settings heading expanded to show Site Repilication + :align: center + + #. Select :guilabel:`Add Sites +` + + .. image:: /images/minio-console/console-settings-site-replication-add.png + :width: 600px + :alt: MinIO Console's Add Sites for Replication screen + :align: center + + #. Complete the requested information for the site: + + :Access Key: `(required)` The user name for ``root`` to use for signing in to the site. + + :Secret Key: `(required)` The password for ``root`` to use for signing in to the site. + + :Site Name: A name or other identifying text to associate to the site. + + :Endpoint: `(required)` The URL or IP address and port to use to access the site. + + To add additional sites beyond two, select the ``+`` button to the side of one of the Site entries. + To remove a site previously added, select the ``-`` button to the side of the site. + + Site replication adds a :mc-cmd:`~mc admin user svcacct` under the ``root`` user to perform replication activities. + + #. Select **Save** + + #. Select :guilabel:`Replication Status` button to verify replication has completed across peer sites. + + Any :ref:`replicable data ` that exists should show as successfully synced. + + For more on reviewing site replication, see the :ref:`Site Replication Status tutorial `. + + + .. tab-item:: Command Line + + The following steps create a new site replication configuration for three :ref:`distributed deployments `. + One of the sites contains :ref:`replicable data `. + + The three sites use aliases, ``minio1``, ``minio2``, and ``minio3``, and only ``minio1`` contains any data. + + #. :ref:`Deploy ` three or more separate MinIO sites, using the same :ref:`IDP ` + + Start with empty sites *or* have no more than one site with any :ref:`replicable data `. + + #. Configure an alias for each site + + For example, for three MinIO sites, you might create aliases ``minio1``, ``minio2``, and ``minio3``. + + Use :mc-cmd:`mc alias set` + + .. code-block:: shell + + mc alias set minio1 https://minio1.example.com:9000 adminuser adminpassword + mc alias set minio2 https://minio2.example.com:9000 adminuser adminpassword + mc alias set minio3 https://minio3.example.com:9000 adminuser adminpassword + + or define environment variables + + .. code-block:: shell + + export MC_HOST_minio1=https://adminuser:adminpassword@minio1.example.com + export MC_HOST_minio2=https://adminuser:adminpassword@minio2.example.com + export MC_HOST_minio3=https://adminuser:adminpassword@minio3.example.com + + #. Add site replication configuration + + .. code-block:: shell + + mc admin replicate add minio1 minio2 minio3 + + If all sites are empty, the order of the aliases does not matter. + If one of the sites contains any :ref:`replicable data `, you must list it first. + + No more than one site can contain any replicable data. + + #. Query the site replication configuration to verify + + .. code-block:: shell + + mc admin replicate info minio1 + + You can use the alias for any peer site in the site replication configuration. + + #. Query the site replication status to confirm any initial data has replicated to all peer sites. + + .. code-block:: shell + + mc admin replicate status minio1 + + You can use the alias for any of the peer sites in the site replication configuration. + The output should say that all :ref:`replicable data ` is in sync. + + The output could resemble the following: + + .. code-block:: shell + + Bucket replication status: + ● 1/1 Buckets in sync + + Policy replication status: + ● 5/5 Policies in sync + + User replication status: + No Users present + + Group replication status: + No Groups present + + For more on reviewing site replication, see the :ref:`Site Replication Status tutorial `. + + +Expand Site Replication +~~~~~~~~~~~~~~~~~~~~~~~ + +You can add more sites to an existing site replication configuration. + +The new site must meet the following requirements: + +- Site is fully deployed and accessible by hostname or IP +- Shares the IDP configuration as all other sites in the configuration +- Uses the same root user credentials as other configured sites +- Contains no bucket or object data + +.. tab-set:: + + .. tab-item:: Console + + #. Deploy a new, empty MinIO site + + #. In a browser, access the Console for one of the exisitng replicated sites + + For example, ``https://:9000`` + + #. Select **Settings**, then **Site Replication** + + .. image:: /images/minio-console/console-site-replication-list-of-sites.png + :width: 600px + :alt: MinIO Console Site Replication with three sites listed + :align: center + + #. Select :guilabel:`Add Sites +` + + .. image:: /images/minio-console/console-settings-site-replication-add.png + :width: 600px + :alt: MinIO Console's Add Sites for Replication screen + :align: center + + #. Make the following entries: + + :Access Key: `(required)` The user name to use for signing in to each site. Should be the same across all sites. + + :Secret Key: `(required)` The password for the user name to use for signing in to each site. Should be the same across all sites. + + :Site Name: An alias to use for the site name. + + :Endpoint: `(required)` The URL or IP address and port to use to access the site. + + To add additional sites beyond two, select the ``+`` button to the side of the last Site entry. + + #. Select :guilabel:`Save` + + .. tab-item:: Command Line + + #. Deploy three or more separate MinIO sites, using the same external IDP + + Only one site can have any buckets or objects on it. + The other sites must be empty. + + #. Configure an alias for each site + + To check the existing aliases, use :mc-cmd:`mc alias list`. + + For example, for three MinIO sites, you might create aliases ``minio1``, ``minio2``, and ``minio3``. + + Use :mc-cmd:`mc alias set` + + .. code-block:: shell + + mc alias set minio1 https://minio1.example.com:9000 adminuser adminpassword + mc alias set minio2 https://minio2.example.com:9000 adminuser adminpassword + mc alias set minio3 https://minio3.example.com:9000 adminuser adminpassword + + or define environment variables + + .. code-block:: shell + + export MC_HOST_minio1=https://adminuser:adminpassword@minio1.example.com + export MC_HOST_minio2=https://adminuser:adminpassword@minio2.example.com + export MC_HOST_minio3=https://adminuser:adminpassword@minio3.example.com + + #. Add site replication configuration + + List all existing replicated sites first, then list the new site(s) to add. + In this example, ``minio1``, ``minio2``, and ``minio3`` are already configured for replication. + The command adds minio4 and minio5 as new sites to add to the replication. + ``minio4`` and ``minio5`` must be empty. + + .. code-block:: shell + + mc admin replicate add minio1 minio2 minio3 minio4 minio5 + + #. Query the site replication configuration to verify + + .. code-block:: shell + + mc admin replicate info minio1 + +Modify a Site's Endpoint +~~~~~~~~~~~~~~~~~~~~~~~~ + +If a peer site changes its hostname, you can modify the replication configuration to reflect the new hostname. + +.. tab-set:: + + .. tab-item:: Console + + #. In a browser, access the Console for one of the replicated sites + + For example, ``https://:9000`` + + #. Select **Settings**, then **Site Replication** + + #. Select the pencil **Edit** icon to the side of the site to update + + .. image:: /images/minio-console/console-site-replication-edit-button.png + :width: 600px + :alt: MinIO Console's List of Replicated Sites screen with the edit buttons highlighted + :align: center + + #. Make the following entries: + + :New Endpoint: `(required)` The new endpoint address and port to use. + + .. image:: /images/minio-console/console-settings-site-replication-edit-endpoint.png + :width: 600px + :alt: Example of the MinIO Console's Edit Replication Endpoint screen + :align: center + + #. Select **Update** + + .. tab-item:: Command Line + + #. Obtain the site's Deployment ID with :mc-cmd:`mc admin replicate info` + + .. code-block:: shell + + mc admin replicate info + + + #. Update the site's endpoint with :mc-cmd:`mc admin replicate edit` + + .. code-block:: shell + + mc admin replicate edit ALIAS --deployment-id [DEPLOYMENT-ID] --endpoint [NEW-ENDPOINT] + + Replace [DEPLOYMENT-ID] with the deployment ID of the site to update. + + Replace [NEW-ENDPOINT] with the new endpoint for the site. + +Remove a Site from Replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can remove a site from replication at any time. +You can re-add the site at a later date, but you must first completely wipe bucket and object data from the site. + +.. tab-set:: + + .. tab-item:: Console + + #. In a browser, access the Console for one of the replicated sites + + For example, ``https://:9000`` + + #. Select **Settings**, then **Site Replication** + + #. Select the trash can Delete icon to the side of the site to update + + .. image:: /images/minio-console/console-site-replication-delete-button.png + :width: 600px + :alt: MinIO Console's List of Replicated Sites screen with the delete buttons highlighted + :align: center + + #. Confirm the site deletion at the prompt by selecting **Delete** + + .. image:: /images/minio-console/console-settings-site-replication-confirm-delete.png + :width: 600px + :alt: Example of the MinIO Console's Edit Replication Endpoint screen + :align: center + + .. tab-item:: Command Line + + Use :mc-cmd:`mc admin replicate remove` + + .. code-block:: shell + + mc admin replicate remove --all --force + + The ``-all`` flag removes the site as a peer from all participating sites. + + The ``--force`` flag is required to removes the site from the site replication configuration. + +.. _minio-site-replication-status-tutorial: + +Review Replication Status +~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO provides information on replication across the sites for users, groups, policies, or buckets. + +The summary information includes the number of **Synced** and **Failed** items for each category. + +.. tab-set:: + + .. tab-item:: Console + + #. In a browser, access the Console for one of the replicated sites + + For example, ``https://:9000`` + + #. Select **Settings**, then **Site Replication** + + #. Select :guilabel:`Replication Status` + + .. image:: /images/minio-console/console-settings-site-replication-status-summary.png + :width: 600px + :alt: MinIO Console's Replication status from all Sites screen + :align: center + + #. `(Optional)` View the replication status for a specific item + + Select the type of item to view in the :guilabel:`View Replication Status for a:` dropdown + + Specify the name of the specific Bucket, Group, Policy, or User to view + + .. image:: /images/minio-console/console-settings-site-replication-status-item.png + :width: 600px + :alt: Example of replication status for a particular bucket item + :align: center + + #. `(Optional)` Update the information by selecting :guilabel:`Refresh` + + .. tab-item:: Command Line + + Use :mc-cmd:`mc admin replicate status` + + .. code-block:: shell + + mc admin replicate status -- + + For example: + + - ``mc admin replicate status minio3 --bucket images`` + + Displays the replication status for the ``images`` bucket on the ``minio3`` site. + + The output resembles the following: + + .. code-block:: + + ● Bucket config replication summary for: images + + Bucket | MINIO2 | MINIO3 | MINIO4 + Tags | | | + Policy | | | + Quota | | | + Retention | | | + Encryption | | | + Replication | ✔ | ✔ | ✔ + + - ``mc admin replicate status minio3 --all`` + + Displays the replication status summary for all replication sites of which ``minio3`` is part. + + The output resembles the following: + + .. code-block:: + + Bucket replication status: + ● 1/1 Buckets in sync + + Policy replication status: + ● 5/5 Policies in sync + + User replication status: + ● 1/1 Users in sync + + Group replication status: + ● 0/2 Groups in sync + + Group | MINIO2 | MINIO3 | MINIO4 + ittechs | ✗ in-sync | | ✗ in-sync + managers | ✗ in-sync | | ✗ in-sync + \ No newline at end of file diff --git a/source/security/encryption-overview.rst b/source/security/encryption-overview.rst index 7975897c..d2702b25 100644 --- a/source/security/encryption-overview.rst +++ b/source/security/encryption-overview.rst @@ -1,3 +1,5 @@ +.. _minio-encryption-overview: + =========================== Data and Network Encryption ===========================