From c676da2376a93dbc363f7655ecf80fda0ab7e115 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Thu, 25 Apr 2024 14:19:30 -0400 Subject: [PATCH] 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 | 5 ++- source/administration/object-management.rst | 4 +++ source/glossary.rst | 4 +++ source/includes/common-admonitions.rst | 35 +++++++++++++++++-- source/operations/checklists/hardware.rst | 4 +++ source/operations/checklists/software.rst | 6 +++- source/operations/concepts.rst | 4 +++ .../concepts/availability-and-resiliency.rst | 4 +++ source/operations/concepts/erasure-coding.rst | 4 +++ source/operations/data-recovery.rst | 6 +++- .../recover-after-drive-failure.rst | 8 +++-- .../recover-after-node-failure.rst | 7 ++-- .../deploy-minio-multi-node-multi-drive.rst | 4 +++ .../deploy-minio-single-node-multi-drive.rst | 4 +++ .../deploy-minio-single-node-single-drive.rst | 4 +++ .../deploy-minio-tenant.rst | 4 +++ .../expand-minio-deployment.rst | 4 +++ .../expand-minio-tenant.rst | 4 +++ 18 files changed, 105 insertions(+), 10 deletions(-) diff --git a/source/administration/concepts.rst b/source/administration/concepts.rst index b6ba2be7..89b01eb5 100644 --- a/source/administration/concepts.rst +++ b/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 ` 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. \ No newline at end of file diff --git a/source/administration/object-management.rst b/source/administration/object-management.rst index 640a3267..e3280291 100644 --- a/source/administration/object-management.rst +++ b/source/administration/object-management.rst @@ -21,6 +21,10 @@ An :ref:`object ` 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 ` to organize objects. diff --git a/source/glossary.rst b/source/glossary.rst index 987e71ff..f1857c01 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -251,6 +251,10 @@ Glossary A portion of an object after being :term:`erasure coded ` 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 diff --git a/source/includes/common-admonitions.rst b/source/includes/common-admonitions.rst index e415b057..c3d66880 100644 --- a/source/includes/common-admonitions.rst +++ b/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 \ No newline at end of file +.. 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 \ No newline at end of file diff --git a/source/operations/checklists/hardware.rst b/source/operations/checklists/hardware.rst index f1b106e0..94f4664c 100644 --- a/source/operations/checklists/hardware.rst +++ b/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. diff --git a/source/operations/checklists/software.rst b/source/operations/checklists/software.rst index 7de9af0c..aa949c8b 100644 --- a/source/operations/checklists/software.rst +++ b/source/operations/checklists/software.rst @@ -93,6 +93,10 @@ Post Install Tasks * - :octicon:`circle` - Configure :ref:`Object storage level rules with 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) ` - | Enabling this requires MinIO support. \ No newline at end of file + | Enabling this requires MinIO support. diff --git a/source/operations/concepts.rst b/source/operations/concepts.rst index b1d4edae..9568fdb0 100644 --- a/source/operations/concepts.rst +++ b/source/operations/concepts.rst @@ -208,6 +208,10 @@ Data loss can come from bit rot, drive loss, or node loss. :ref:`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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/operations/concepts/availability-and-resiliency.rst b/source/operations/concepts/availability-and-resiliency.rst index 7d1b3771..d29fa3a4 100644 --- a/source/operations/concepts/availability-and-resiliency.rst +++ b/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 ---------------------------- diff --git a/source/operations/concepts/erasure-coding.rst b/source/operations/concepts/erasure-coding.rst index f5c4d758..cc31a785 100644 --- a/source/operations/concepts/erasure-coding.rst +++ b/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 `__ 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 diff --git a/source/operations/data-recovery.rst b/source/operations/data-recovery.rst index ca8bd5b0..37540a99 100644 --- a/source/operations/data-recovery.rst +++ b/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 `. 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 diff --git a/source/operations/data-recovery/recover-after-drive-failure.rst b/source/operations/data-recovery/recover-after-drive-failure.rst index 574e07e0..882bd9a6 100644 --- a/source/operations/data-recovery/recover-after-drive-failure.rst +++ b/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 -drive. **Do not** attempt to manually recover or migrate data from the failed -drive onto the new healthy drive. +MinIO healing ensures consistency and correctness of all data restored onto the 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 diff --git a/source/operations/data-recovery/recover-after-node-failure.rst b/source/operations/data-recovery/recover-after-node-failure.rst index 5f14eb40..4dc27274 100644 --- a/source/operations/data-recovery/recover-after-node-failure.rst +++ b/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 -node onto the new healthy node. +drive. + +.. 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. diff --git a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst b/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst index 44faa70b..3fe94f22 100644 --- a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~ diff --git a/source/operations/install-deploy-manage/deploy-minio-single-node-multi-drive.rst b/source/operations/install-deploy-manage/deploy-minio-single-node-multi-drive.rst index dd500afd..b39fcbb0 100644 --- a/source/operations/install-deploy-manage/deploy-minio-single-node-multi-drive.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~ diff --git a/source/operations/install-deploy-manage/deploy-minio-single-node-single-drive.rst b/source/operations/install-deploy-manage/deploy-minio-single-node-single-drive.rst index 338ad3ce..6810e21c 100644 --- a/source/operations/install-deploy-manage/deploy-minio-single-node-single-drive.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~ diff --git a/source/operations/install-deploy-manage/deploy-minio-tenant.rst b/source/operations/install-deploy-manage/deploy-minio-tenant.rst index 122536ef..699a9426 100644 --- a/source/operations/install-deploy-manage/deploy-minio-tenant.rst +++ b/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) ` that supports the :kube-docs:`ReadWriteOnce ` access mode. diff --git a/source/operations/install-deploy-manage/expand-minio-deployment.rst b/source/operations/install-deploy-manage/expand-minio-deployment.rst index 15626dcf..a7194712 100644 --- a/source/operations/install-deploy-manage/expand-minio-deployment.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/operations/install-deploy-manage/expand-minio-tenant.rst b/source/operations/install-deploy-manage/expand-minio-tenant.rst index 788edbe8..507463fc 100644 --- a/source/operations/install-deploy-manage/expand-minio-tenant.rst +++ b/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) ` that supports the :kube-docs:`ReadWriteOnce ` access mode.