Adds an admonition for exclusive drive access (#1196)

Admonition added as an include, then put in many files throughout the
docs.
Where it is included, it's the same admonition and text.

It's worth making sure where I placed the include makes sense.

Closes #1186

source/administration/concepts.rst

@@ -129,6 +129,9 @@ Besides replication, MinIO provides a mirroring service.
 :mc:`mc mirror` copies only the actual object to any other S3 compatible data store, including other MinIO stores.
 However, versions and metadata do not back up with the :mc:`mc mirror` command.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
 
 What tools does MinIO provide to manage objects based on speed and frequency of access?
 ---------------------------------------------------------------------------------------
@@ -162,4 +165,4 @@ MinIO provides a configuration option to create buckets with versioning enabled.
 :ref:`Versioning <minio-bucket-versioning>` provides access to various iterations of a uniquely named object as it changes over time. 
 When enabled, MinIO writes mutated objects to a different version than the original, allowing access to both the original object and the newer, changed object.
 
-Additional configurations on the MinIO bucket determine how long to retain older versions of each object in the bucket.
+Additional configurations on the MinIO bucket determine how long to retain older versions of each object in the bucket.

source/administration/object-management.rst

@@ -21,6 +21,10 @@ An :ref:`object <objects>` is binary data, such as images, audio files, spreadsh
 The term "Binary Large Object" or "blob" is sometimes associated to object storage, although blobs can be anywhere from a few bytes to several terabytes in size.
 Object Storage platforms like MinIO provide dedicated tools and capabilities for storing, listing, and retrieving objects using a standard S3-compatible API. 
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. _buckets:
 
 MinIO Object Storage uses :ref:`buckets <buckets>` to organize objects. 

source/glossary.rst

@@ -251,6 +251,10 @@ Glossary
      A portion of an object after being :term:`erasure coded <erasure coding>` by MinIO.
      Each "shard" represents either data or parity for MinIO to use for reconstructing objects on read requests.
 
+     .. include:: /includes/common-admonitions.rst
+        :start-after: start-exclusive-drive-access
+        :end-before: end-exclusive-drive-access
+     
      For more detailed information, see :ref:`minio-erasure-coding`.
 
    single-node multi-drive

source/includes/common-admonitions.rst

@@ -2,7 +2,6 @@
    - /monitoring/bucket-notifications/publish-events-to-amqp.rst
 
 .. Used in the following pages:
-
    /reference/minio-cli/minio-mc/mc-rm.rst
    /reference/minio-cli/minio-mc/mc-mv.rst
    /reference/minio-cli/minio-mc/mc-mirror.rst
@@ -46,4 +45,36 @@ directory path and an implicitly created one. If |command| deletes the last
 object at a filesystem path, :mc:`mc` recursively deletes all empty directories
 within that path up to the root as part of the removal operation.
 
-.. end-remove-api-trims-prefixes-fs
+.. end-remove-api-trims-prefixes-fs
+
+.. The following exclusive access admonition is used on a number of pages:
+   - administration/object-management.rst
+   - administration/concepts.rst
+   - operations/concepts.rst
+   - operations/data-recovery.rst
+   - operations/checklists/hardware.rst
+   - operations/checklists/software.rst
+   - operations/concepts/availability-and-resiliency.rst
+   - operations/concepts/erasure-coding.rst
+   - operations/data-recover/recover-after-drive-failure.rst
+   - operations/data-recover/recover-after-node-failure.rst
+   - operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst
+   - operations/install-deploy-manage/deploy-minio-single-node-multi-drive.rst
+   - operations/install-deploy-manage/deploy-minio-single-node-single-drive.rst
+   - operations/install-deploy-manage/deploy-minio-tenant.rst
+   - operations/install-deploy-manage/expand-minio-deployment.rst
+   - operations/install-deploy-manage/expand-minio-tenant.rst
+   - glossary.rst
+
+.. start-exclusive-drive-access
+
+.. admonition:: Exclusive access to drives
+   :class: warning
+
+   MinIO **requires** *exclusive* access to the drives or volumes provided for object storage.
+   No other processes, software, scripts, or persons should perform *any* actions directly on the drives or volumes provided to MinIO or the objects or files MinIO places on them.
+   
+   Unless directed by MinIO Engineering, do not use scripts or tools to directly modify, delete, or move any of the data shards, parity shards, or metadata files on the provided drives, including from one drive or node to another.
+   Such operations are very like to result in widespread corruption and data loss beyond MinIO's ability to heal.
+
+.. end-exclusive-drive-access

source/operations/checklists/hardware.rst

@@ -198,6 +198,10 @@ The following table provides general guidelines for allocating memory for use by
 Storage
 ~~~~~~~
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. cond:: k8s
 
    MinIO recommends provisioning a storage class for each MinIO Tenant that meets the performance objectives for that tenant.

source/operations/checklists/software.rst

@@ -93,6 +93,10 @@ Post Install Tasks
    * - :octicon:`circle`
      - Configure :ref:`Object storage level rules with tiering <minio-lifecycle-management-tiering>` to move objects between hot, warm, and cold storage and maximize storage cost efficiencies
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 3rd Party Identity Provider Tasks
 ---------------------------------
 
@@ -102,4 +106,4 @@ Post Install Tasks
 
    * - :octicon:`circle`
      - | Authenticate to MinIO with :ref:`Security Token Service (STS) <minio-security-token-service>`
-       | Enabling this requires MinIO support.
+       | Enabling this requires MinIO support.

source/operations/concepts.rst

@@ -208,6 +208,10 @@ Data loss can come from bit rot, drive loss, or node loss.
 
 :ref:`Erasure coding <minio-erasure-coding>` provides continued read and write access if an object has been partially lost.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 MinIO Writes Data Protection at the Object Level with Parity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/operations/concepts/availability-and-resiliency.rst

@@ -161,6 +161,10 @@ For multi-pool MinIO deployments, each pool requires at least one erasure set ma
    Use replicated remotes to restore the lost data to the deployment.
    All data stored on the healthy pools remain safe on disk.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 Replicated MinIO Deployments
 ----------------------------
 

source/operations/concepts/erasure-coding.rst

@@ -125,6 +125,10 @@ For an object maintaining **read quorum**, MinIO can use any data or parity shar
 Use the MinIO `Erasure Coding Calculator <https://min.io/product/erasure-code-calculator>`__ to explore the possible erasure set size and distributions for your planned topology.
 Where possible, use an even number of nodes and drives per node to simplify topology planning and conceptualization of drive/erasure-set distribution.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. _minio-ec-parity:
 
 Erasure Parity and Storage Efficiency

source/operations/data-recovery.rst

@@ -47,9 +47,13 @@ in a degraded state (increasing drive errors, SMART warnings, timeouts in MinIO
 logs, etc.), you can safely unmount the drive *if* the cluster has sufficient
 remaining healthy drives to maintain
 :ref:`read and write quorum <minio-ec-parity>`. Missing drives are less
-disruptive to the deployment than drives that are reliably producing read and
+disruptive to the deployment than drives that are consistently producing read and
 write errors.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. admonition:: MinIO Professional Support
    :class: note
 

source/operations/data-recovery/recover-after-drive-failure.rst

@@ -15,9 +15,11 @@ and heals those drives without requiring any node or deployment-level restart.
 MinIO healing occurs only on the replaced drive(s) and does not typically impact
 deployment performance.
 
-MinIO healing ensures consistency and correctness of all data restored onto the
+MinIO healing ensures consistency and correctness of all data restored onto the drive.
-drive. **Do not** attempt to manually recover or migrate data from the failed
+
-drive onto the new healthy drive.
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
 
 The following steps provide a more detailed walkthrough of drive replacement.
 These steps assume a MinIO deployment where each node manages drives using

source/operations/data-recovery/recover-after-node-failure.rst

@@ -16,8 +16,11 @@ MinIO healing occurs only on the replaced hardware and does not typically impact
 deployment performance.
 
 MinIO healing ensures consistency and correctness of all data restored onto the
-drive. **Do not** attempt to manually recover or migrate data from the failed
+drive.
-node onto the new healthy node.
+
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
 
 The replacement node hardware should be substantially similar to the failed
 node. There are no negative performance implications to using improved hardware.

source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst

@@ -104,6 +104,10 @@ Storage Requirements
    :start-after: start-storage-requirements-desc
    :end-before: end-storage-requirements-desc
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 Memory Requirements
 ~~~~~~~~~~~~~~~~~~~
 

source/operations/install-deploy-manage/deploy-minio-single-node-multi-drive.rst

@@ -33,6 +33,10 @@ Storage Requirements
    :start-after: start-storage-requirements-desc
    :end-before: end-storage-requirements-desc
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 Memory Requirements
 ~~~~~~~~~~~~~~~~~~~
 

source/operations/install-deploy-manage/deploy-minio-single-node-single-drive.rst

@@ -82,6 +82,10 @@ Persist Drive Mounting and Mapping Across Reboots
 
    Non-Linux Operating Systems should use the equivalent drive mount management tool.
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 Memory Requirements
 ~~~~~~~~~~~~~~~~~~~
 

source/operations/install-deploy-manage/deploy-minio-tenant.rst

@@ -174,6 +174,10 @@ See :ref:`deploy-operator-kubernetes` for complete documentation on deploying th
 Persistent Volumes
 ~~~~~~~~~~~~~~~~~~
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. cond:: not eks
 
    MinIO can use any Kubernetes :kube-docs:`Persistent Volume (PV) <concepts/storage/persistent-volumes>` that supports the :kube-docs:`ReadWriteOnce <concepts/storage/persistent-volumes/#access-modes>` access mode.

source/operations/install-deploy-manage/expand-minio-deployment.rst

@@ -97,6 +97,10 @@ Storage Requirements
    :start-after: start-storage-requirements-desc
    :end-before: end-storage-requirements-desc
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 Minimum Drives for Erasure Code Parity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/operations/install-deploy-manage/expand-minio-tenant.rst

@@ -37,6 +37,10 @@ The MinIO Operator provides configurations for controlling pod affinity and anti
 Persistent Volumes
 ~~~~~~~~~~~~~~~~~~
 
+.. include:: /includes/common-admonitions.rst
+   :start-after: start-exclusive-drive-access
+   :end-before: end-exclusive-drive-access
+
 .. cond:: not eks
 
    MinIO can use any Kubernetes :kube-docs:`Persistent Volume (PV) <concepts/storage/persistent-volumes>` that supports the :kube-docs:`ReadWriteOnce <concepts/storage/persistent-volumes/#access-modes>` access mode.