minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

Adding concept docs for operation and administration sections (#519)

Browse Source 
Creates an administration/concepts.rst file.
Adds content to the operation/concepts.rst file stub.
This commit is contained in:
Daryl White
2022-08-24 16:40:48 -05:00
committed by GitHub
parent da199027d2
commit ac7f725e43
7 changed files with 387 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
source/administration/concepts.rst Normal file
View File

@ -0,0 +1,161 @@
============================
Core Administration Concepts
============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The following core concepts are fundamental to the administration of MinIO deployments, including but not limited to object retention, encryption, and access management.
What Is Object Storage?
-----------------------
.. _objects:
An :ref:`object <objects>` is binary data, sometimes referred to as a Binary Large OBject (BLOB).
Blobs can be images, audio files, spreadsheets, or even binary executable code.
Object Storage platforms like MinIO provide dedicated tools and capabilities for storing, retrieving, and searching for blobs.
.. _buckets:
MinIO Object Storage uses :ref:`buckets <buckets>` to organize objects.
A bucket is similar to a folder or directory in a filesystem, where each bucket can hold an arbitrary number of objects.
MinIO buckets provide the same functionality as AWS S3 buckets.
For example, consider an application that hosts a web blog.
The application needs to store a variety of blobs, including rich multimedia like videos and images.
MinIO supports multiple levels of nested directories through the feature of ``prefixing`` to support even the most dynamic object storage workloads.
How does MinIO determine access to objects?
-------------------------------------------
MinIO requires the client perform both authentication and authorization for each new operation.
:ref:`Identity and access management (IAM) <minio-authentication-and-identity-management>` is therefore a critical component of a MinIO configuration.
*Authentication* verifies the identity of a connecting client.
MinIO requires clients to authenticate using :s3-api:`AWS Signature Version 4 protocol <sig-v4-authenticating-requests.html>` with support for the deprecated Signature Version 2 protocol.
Specifically, clients must present a valid access key and secret key to access any S3 or MinIO administrative API, such as ``PUT``, ``GET``, and ``DELETE`` operations.
MinIO then checks that authenticated users or clients have *authorization* to perform actions or use resources on the deployment.
MinIO uses :ref:`Policy-Based Access Control (PBAC) <minio-policy>`, where each policy describes one or more rules that outline the permissions of a user or group of users.
MinIO supports S3-specific :ref:`actions <minio-policy-actions>` and :ref:`conditions <minio-policy-conditions>` when creating policies.
By default, MinIO *denies* access to actions or resources not explicitly referenced in a user's assigned or inherited policies.
MinIO provides an access management feature as part of the software.
Alternatively, you can configure MinIO to authenticate with one of several external IAM providers using either :ref:`Active Directory/LDAP <minio-external-identity-management-ad-ldap>` or :ref:`OpenID/OIDC <minio-external-identity-management-openid>`.
How does MinIO secure data?
---------------------------
MinIO supports methods that encode objects while on disk (encryption-at-rest) and during transition from one location to another (encryption-in-transit, or "in flight").
When enabled, MinIO utilizes :ref:`server-side encryption <minio-encryption-overview>` to write objects in an encrypted state.
To retrieve and read an encrypted object, the user must have appropriate access privileges and also provide the object's decryption key.
MinIO supports **Transport Layer Security** (TLS) versions 1.2 and 1.3 encrypting objects.
TLS replaces the previously used Secure Socket Layer (SSL) method that has since been deprecated.
The TLS standard, maintained by the Internet Engineering Task Force (IETF), provides the standards used by internet communications to support encryption, authentication, and data integrity.
The process of authenticating a user and verifying access to objects is known as the `TLS Handshake`.
Once authenticated, TLS provides the cipher to encrypt and then decrypt the transfer of information from the server to the requesting client.
MinIO supports several methods of :ref:`Server-Side Encryption <minio-encryption-overview>`.
Can I organize objects in a folder structure within buckets?
------------------------------------------------------------
MinIO utilizes a :term:`prefix` method for each object that mimics a folder structure from traditional file systems.
Prefixing involves prepending the name of an object with a fixed string.
With prefixes, you do not manually create folders and subfolders.
Instead, MinIO looks for the ``/`` character in the prefix of an object's name.
Each ``/`` indicates a new folder or subfolder.
Using the object's name and prefix, MinIO automatically generates a series of folders and subfolders for stored objects.
When you use the same prefix string on multiple objects, MinIO identifies those as similar or grouped objects.
For example, an object named ``/articles/john.doe/2022-01-02-MinIO-Object-Storage.md`` winds up in the ``articles`` bucket in a folder labeled ``john.doe``.
A MinIO object store might resemble the following structure, with three buckets.
MinIO automatically generates two folders in the ``articles`` bucket based on the prefixes for those objects.
.. code-block:: text
/ #root
/images/
2022-01-02-MinIO-Diagram.png
2022-01-03-MinIO-Advanced-Deployment.png
MinIO-Logo.png
/videos/
2022-01-04-MinIO-Interview.mp4
/articles/
/john.doe/
2022-01-02-MinIO-Object-Storage.md
2022-01-02-MinIO-Object-Storage-comments.json
/jane.doe/
2022-01-03-MinIO-Advanced-Deployment.png
2022-01-02-MinIO-Advanced-Deployment-comments.json
2022-01-04-MinIO-Interview.md
How can I backup and restore objects on MinIO?
----------------------------------------------
MinIO provides two types of replication to copy an object, its versions, and its metadata from one location to another.
You can configure replication at either the :ref:`bucket level <minio-bucket-replication>` or at the :ref:`site level <minio-site-replication-overview>`.
- Bucket level replication can function as either one-way, active-passive replication (such as for archival purposes) or as two-way, active-active replication to keep two buckets in sync with each other.
- Site level replication functions as two-way, active-active replication to keep multiple data locations (such as different geographic data centers) in sync with one another.
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.
What tools does MinIO provide to manage objects based on speed and frequency of access?
---------------------------------------------------------------------------------------
:ref:`Tiering rules <minio-lifecycle-management-tiering>` allow frequently accessed objects to store on hot or warm storage, which is typically more expensive but provides better performance.
Less frequently accessed objects can move to cold storage.
Cold storage often exchanges slower performance for a cheaper price.
How does MinIO protect objects from accidental overwrite or deletion?
---------------------------------------------------------------------
Locking
~~~~~~~
Locks, a Write Once Read Many (WORM) mechanism, prevent the deletion or modification of an object.
When locked, MinIO retains the objects indefinitely until someone removes the lock or the lock expires.
MinIO provides:
- :ref:`legal holds <minio-object-locking-legalhold>` locks for indefinite retention by all users
- :ref:`compliance holds <minio-object-locking-compliance>` for time-based restrictions for all users
- :ref:`governing locks <minio-object-locking-governance>` for time-based rules for non-privileged users
Versioning
~~~~~~~~~~
By default, objects written with the same name (including prefix) overwrite an existing object of the same name.
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.
.. toctree::
:titlesonly:
:hidden:
:glob:
/operations/concepts/*

13
source/glossary.rst
View File

@ -26,15 +26,6 @@ Glossary
bit rot bit rot
Data corruption that occurrs without the user’s knowledge. Data corruption that occurrs without the user’s knowledge.
Some common reasons for bitrot include:
- ageing drives
- current spikes
- bugs in disk firmware
- phantom writes
- misdirected reads/writes
- driver errors
- accidental overwrites
MinIO combats bit rot with :term:`hashing` and :term:`erasure coding`. MinIO combats bit rot with :term:`hashing` and :term:`erasure coding`.
@ -263,3 +254,7 @@ Glossary
webhook webhook
A :ref:`webhook <minio-bucket-notifications-publish-webhook>` is a method for altering the behavior of a web page or web application with a custom callback. A :ref:`webhook <minio-bucket-notifications-publish-webhook>` is a method for altering the behavior of a web page or web application with a custom callback.
The format is typically :abbr:`JSON (JavaScript Object Notation)` sent as an HTTP POST request. The format is typically :abbr:`JSON (JavaScript Object Notation)` sent as an HTTP POST request.
WORM
Write Once Read Many (WORM) is a data retention methodology that functions as part of object locking.
Many requests can retrieve can view a WORM-locked object (``read many``), but no write requests can change the object (``write once``).

2
source/index.rst
View File

@ -107,6 +107,7 @@ without validating their usage do so at their own risk.
/administration/identity-access-management /administration/identity-access-management
/administration/server-side-encryption /administration/server-side-encryption
/administration/bucket-replication /administration/bucket-replication
/administration/concepts
/developers/minio-drivers /developers/minio-drivers
/developers/security-token-service /developers/security-token-service
/reference/minio-mc /reference/minio-mc
@ -136,6 +137,7 @@ without validating their usage do so at their own risk.
/administration/identity-access-management /administration/identity-access-management
/administration/server-side-encryption /administration/server-side-encryption
/administration/bucket-replication /administration/bucket-replication
/administration/concepts
/developers/minio-drivers /developers/minio-drivers
/developers/security-token-service /developers/security-token-service
/reference/minio-mc /reference/minio-mc

212
source/operations/concepts.rst
View File

@ -8,75 +8,57 @@ Core Operational Concepts
:local: :local:
:depth: 2 :depth: 2
The following core concepts are fundamental to operation of MinIO deployments, including but not limited to installation and management of MinIO. What are the components of a MinIO Deployment?
----------------------------------------------
What Is Object Storage? A MinIO deployment consists of a set of storage and compute resources running one or more :mc:`minio server` nodes that together act as a single object storage repository.
-----------------------
.. _objects: A standalone instance of MinIO consists of a single Server Pool with a single :mc:`minio server` node.
Standalone instances are best suited for initial development and evaluation.
An :ref:`object <objects>` is binary data, sometimes referred to as a Binary A MinIO deployment can run directly on a physical device in a ``bare metal`` or non-virtualized infrastructure.
Large OBject (BLOB). Blobs can be images, audio files, spreadsheets, or even Or, MinIO might run within a virtual machine on a cloud service, such as using Docker, Podman, or Kubernetes.
binary executable code. Object Storage platforms like MinIO provide dedicated MinIO can run locally, on a private cloud, or in any of the many public clouds available on the market.
tools and capabilities for storing, retrieving, and searching for blobs.
.. _buckets: The specific way you design, architect, and build your system is called the system's ``topology``.
MinIO Object Storage uses :ref:`buckets <buckets>` to organize objects. What system topologies does MinIO support?
A bucket is similar to a folder or directory in a filesystem, where each ------------------------------------------
bucket can hold an arbitrary number of objects. MinIO buckets provide the
same functionality as AWS S3 buckets.
For example, consider an application that hosts a web blog. The application MinIO can deploy to three types of topologies:
needs to store a variety of blobs, including rich multimedia like videos and
images. The structure of objects on the MinIO server might look similar to the
following:
.. code-block:: text #. :ref:`Single Node Single Drive <minio-snsd>`, one MinIO server with a single drive or folder for data
/ #root For example, testing on a local PC using a folder on the computer's hard drive.
/images/ #. :ref:`Single Node Multi Drive <minio-snmd>`, one MinIO server with multiple mounted drives or folders for data
2020-01-02-MinIO-Diagram.png
2020-01-03-MinIO-Advanced-Deployment.png
MinIO-Logo.png
/videos/
2020-01-04-MinIO-Interview.mp4
/articles/
/john.doe/
2020-01-02-MinIO-Object-Storage.md
2020-01-02-MinIO-Object-Storage-comments.json
/jane.doe/
2020-01-03-MinIO-Advanced-Deployment.png
2020-01-02-MinIO-Advanced-Deployment-comments.json
2020-01-04-MinIO-Interview.md
MinIO supports multiple levels of nested directories and objects to support For example, a single container with two or more mounted volumes.
even the most dynamic object storage workloads. #. :ref:`Multi Node Multi Drive <minio-mnmd>`, multiple MinIO servers with multiple mounted drives or volumes for data
Deployment Architecture For example, a production deployment using Kubernetes to manage and deploy pods with multiple persistent volume claims.
-----------------------
:ref:`Erasure Set <minio-ec-erasure-set>`
A set of disks that supports MinIO :ref:`Erasure Coding
<minio-erasure-coding>`. Erasure Coding provides high availability,
reliability, and redundancy of data stored on a MinIO deployment.
MinIO divides objects into chunks and evenly distributes them among each How does a distributed MinIO deployment work?
drive in the Erasure Set. MinIO can continue seamlessly serving read and ---------------------------------------------
write requests despite the loss of any single drive. At the highest
redundancy levels, MinIO can serve read requests with minimal performance A distributed deployment makes use of the resources of more than one physical or virtual machine's compute and storage resources.
impact despite the loss of up to half (``N/2``) of the total drives in the In modern situations, this often means running MinIO in a private or public cloud environment, such as with Amazon Web Services, the Google Cloud Platform, Microsoft's Azure platform, or many others.
deployment.
.. _minio-intro-server-pool: .. _minio-intro-server-pool:
:ref:`Server Pool <minio-intro-server-pool>` How does MinIO manage multiple virtual or physical servers?
A set of MinIO :mc:`minio server` nodes which pool their drives and ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
resources for supporting object storage/retrieval requests. Server pools
support horizontal expansion for MinIO deployments.
The :mc-cmd:`~minio server HOSTNAME` argument passed to the While testing MinIO may only involve a single drive on a single computer, most production MinIO deployments use multiple compute and storage devices to create a high availability environment.
:mc:`minio server` command represents a Server Pool: A server pool a set of :mc:`minio server` nodes that pool their drives and resources to support object storage write and retrieval requests.
MinIO supports adding one or more server pools to existing MinIO deployments for horizontal expansion.
When MinIO has multiple server pools available, an individual object always writes to the same server pool.
If one server pool goes down, objects on other pools remain accessible.
The :mc-cmd:`~minio server HOSTNAME` argument passed to the :mc:`minio server` command represents a Server Pool:
Consider the following example startup command, which creates a single Server Pool with 4 :mc:`minio server` nodes of 4 drives each for a total of 16 drives.
.. code-block:: shell .. code-block:: shell
@ -84,23 +66,18 @@ Deployment Architecture
| Server Pool | | Server Pool |
The above example describes a single Server Pool with Starting server pools in the same :mc:`minio server` startup command enables awareness of all server pool peers.
4 :mc:`minio server` nodes and 4 drives each for a total of 16 drives.
MinIO requires starting each :mc:`minio server` in the set with the same
startup command to enable awareness of all set peers.
See :mc:`minio server` for complete syntax and usage. See :mc:`minio server` for complete syntax and usage.
MinIO calculates the size and number of Erasure Sets in the Server Pool based
on the total number of drives in the set *and* the number of :mc:`minio`
servers in the set. See :ref:`minio-ec-erasure-set` for more information.
.. _minio-intro-cluster: .. _minio-intro-cluster:
:ref:`Cluster <minio-intro-cluster>` How does MinIO link multiple server pools into a single MinIO cluster?
The whole MinIO deployment consisting of one or more Server Pools. Each ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc-cmd:`~minio server HOSTNAME` argument passed to the
:mc:`minio server` command represents one Server Pool: A cluster refers to an entire MinIO deployment consisting of one or more Server Pools.
Consider the command below that creates a cluster consisting of two Server Pools, each with 4 :mc:`minio server` nodes and 4 drives per node for a total of 32 drives.
.. code-block:: shell .. code-block:: shell
@ -109,25 +86,100 @@ Deployment Architecture
| Server Pool | | Server Pool |
The above example describes two Server Pools, each consisting of 4 Within a cluster, MinIO always stores each unique object and all versions of that object on the same Server Pool.
:mc:`minio server` nodes with 4 drives each for a total of 32 drives. MinIO
always stores each unique object and all versions of that object on the
same Server Pool.
Server Pool expansion is a function of Horizontal Scaling, where each new set MinIO strongly recommends production clusters consist of a *minimum* of 4 :mc:`minio server` nodes in a Server Pool for proper high availability and durability guarantees.
expands the cluster storage and compute resources. Server Pool expansion
is not intended to support migrating existing sets to newer hardware.
MinIO Standalone clusters consist of a single Server Pool with a single Can I change the size of an existing MinIO deployment?
:mc:`minio server` node. Standalone clusters are best suited for initial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
development and evaluation. MinIO strongly recommends production
clusters consist of a *minimum* of 4 :mc:`minio server` nodes in a
Server Pool.
Erasure Coding You can move objects from an existing server pool on to other server pools on the deployment to reduce the size of a deployment by decommissioning a server pool.
-------------- Likewise, you can add on a new server pool to an existing deployment to expand the total size of a deployment with a horizontal expansion.
When the time comes to retire or replace a server pool, :ref:`decommissioning <minio-decommissioning>` is the process of draining the objects of a pool to other active pools on the deployment.
MinIO rewrites objects from the decommissioned pool and does not allow additional writes to the pool while it is in decommissioning.
Once started, decommissioning cannot be stopped.
In a distributed MinIO deployment, you can upgrade the total available size of a :ref:`deployment <expand-minio-distributed>` or :ref:`cluster <minio-k8s-expand-minio-tenant>` by adding one or more additional server pools.
The addition of a server pool is an expansion.
How do I manage one or more MinIO instances or clusters?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several options to manage your MinIO deployments and clusters:
- Use the command line with :mc-cmd:`mc` and :mc-cmd:`mc admin`
- The :ref:`MinIO Console <minio-console>` graphical user interface for individual instances
- In Kubernetes, with the :ref:`MinIO Operator Console <minio-operator-console>`
How does MinIO provide availability, redundancy, and reliability?
-----------------------------------------------------------------
MinIO Uses :ref:`Erasure Coding <minio-erasure-coding>` for Data Redundancy and Reliability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO Erasure Coding is a data redundancy and availability feature that allows MinIO deployments with multiple drives to automatically reconstruct objects on-the-fly despite the loss of multiple drives or nodes in the cluster.
Erasure Coding provides object-level healing with significantly less overhead than adjacent technologies such as RAID or replication.
MinIO Implements Bit Rot Healing to Protect Data At Rest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bit rot is the random, silent corruption to data that can happen on any storage device.
Bit rot corruption is not prompted by any activity from a user, nor does the system's operating system alone have awareness of the corruption to notify a user or administrator about a change to the data.
Some common reasons for bit rot include:
- ageing drives
- current spikes
- bugs in disk firmware
- phantom writes
- misdirected reads/writes
- driver errors
- accidental overwrites
MinIO uses a hashing algorithm to confirm the integrity of an object.
If an object becomes corrupted by bit rot, MinIO can automatically heals the object depending on the system topology and availability.
MinIO Distributes Data Across :ref:`Erasure Sets <minio-ec-erasure-set>` for High Availability and Resiliency
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An erasure set is a group of multiple drives that supports MinIO :ref:`Erasure Coding <minio-erasure-coding>`.
Erasure Coding provides high availability, reliability, and redundancy of data stored on a MinIO deployment.
MinIO divides objects into chunks — called `shards` — and evenly distributes them among each drive in the Erasure Set.
MinIO can continue seamlessly serving read and write requests despite the loss of any single drive.
At the highest redundancy levels, MinIO can serve read requests with minimal performance impact despite the loss of up to half (:math:`N / 2`) of the total drives in the deployment.
MinIO calculates the size and number of Erasure Sets in a Server Pool based on the total number of drives in the set *and* the number of :mc:`minio` servers in the set. See :ref:`minio-ec-erasure-set` for more information.
MinIO Automatically Heals Corrupt or Missing Data On-the-fly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Healing is MinIO's ability to restore data after some event causes data loss.
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.
MinIO Writes Data Protection at the Object Level with Parity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A MinIO deployment with multiple drives divides the available drives into data drives and parity drives.
MinIO Erasure Coding adds additional hashing information about the contents of an object to the parity drives when writing an object.
MinIO uses the parity information to confirm the integrity of an object and, if necessary, to restore a lost, missing, or corrupted object shard on a given disk or set of disks.
MinIO can tolerate losing up to the total number of drives equal to the number of parity devices available in the erasure set while still providing full access to an object.
Deliver Read and Write Functions with Quorum
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A minimum number of drives that must be available to perform a task.
MinIO has one quorum for reading data and a separate quorum for writing data.
Typically, MinIO requires a higher number of available drives to maintain the ability to write objects than what is required to read objects.
High-level blurb on Erasure Coding
.. toctree:: .. toctree::
:titlesonly: :titlesonly:

175
source/operations/concepts/erasure-coding.rst
View File

@ -10,35 +10,24 @@ Erasure Coding
:local: :local:
:depth: 2 :depth: 2
MinIO Erasure Coding is a data redundancy and availability feature that allows MinIO Erasure Coding is a data redundancy and availability feature that allows MinIO deployments to automatically reconstruct objects on-the-fly despite the loss of multiple drives or nodes in the cluster.
MinIO deployments to automatically reconstruct objects on-the-fly despite the Erasure Coding provides object-level healing with significantly less overhead than adjacent technologies such as RAID or replication.
loss of multiple drives or nodes in the cluster. Erasure Coding provides
object-level healing with less overhead than adjacent technologies such as
RAID or replication.
MinIO splits each new object into data and parity blocks, where parity blocks MinIO splits each new object into data and parity blocks, where parity blocks support reconstruction of missing or corrupted data blocks.
support reconstruction of missing or corrupted data blocks. MinIO writes these MinIO writes these blocks to a single :ref:`erasure set <minio-ec-erasure-set>` in the deployment.
blocks to a single :ref:`erasure set <minio-ec-erasure-set>` in the deployment. Since erasure set drives are striped across the server pool, a given node contains only a portion of data or parity blocks for each object.
Since erasure set drives are striped across the deployment, a given node MinIO can therefore tolerate the loss of multiple drives or nodes in the deployment depending on the configured parity and deployment topology.
typically contains only a portion of data or parity blocks for each object.
MinIO can therefore tolerate the loss of multiple drives or nodes in the
deployment depending on the configured parity and deployment topology.
.. image:: /images/erasure-code.jpg .. image:: /images/erasure-code.jpg
:width: 600px :width: 600px
:alt: MinIO Erasure Coding example :alt: MinIO Erasure Coding example
:align: center :align: center
At maximum parity, MinIO can tolerate the loss of up to half the drives per At maximum parity, MinIO can tolerate the loss of up to half the drives per erasure set (:math:`(N / 2) - 1`) and still perform read and write operations.
erasure set (``N/2-1``) and still perform read and write operations. MinIO MinIO defaults to 4 parity blocks per object with tolerance for the loss of 4 drives per erasure set.
defaults to 4 parity blocks per object with tolerance for the loss of 4 drives For more complete information on selecting erasure code parity, see :ref:`minio-ec-parity`.
per erasure set. For more complete information on selecting erasure code parity,
see :ref:`minio-ec-parity`.
Use the MinIO `Erasure Code Calculator Use the MinIO `Erasure Code Calculator <https://min.io/product/erasure-code-calculator?ref=docs>`__ when planning and designing your MinIO deployment to explore the effect of erasure code settings on your intended topology.
<https://min.io/product/erasure-code-calculator?ref=docs>`__ when planning and
designing your MinIO deployment to explore the effect of erasure code settings
on your intended topology.
Zero-Parity Deployments Zero-Parity Deployments
----------------------- -----------------------
@ -53,50 +42,45 @@ Zero-parity deployments depend on the underlying storage for resiliency and avai
Erasure Sets Erasure Sets
------------ ------------
An *Erasure Set* is a set of drives in a MinIO deployment that support Erasure An *Erasure Set* is a set of drives in a MinIO deployment that support Erasure Coding.
Coding. MinIO evenly distributes object data and parity blocks among the drives MinIO evenly distributes object data and parity blocks among the drives in the Erasure Set.
in the Erasure Set. MinIO randomly and uniformly distributes the data and parity MinIO randomly and uniformly distributes the data and parity blocks across drives in the erasure set with *no overlap*.
blocks across drives in the erasure set with *no overlap*. Each unique object Each unique object has no more than one data or parity block per drive in the set.
has no more than one data or parity block per drive in the set.
MinIO calculates the number and size of *Erasure Sets* by dividing the total MinIO calculates the number and size of *Erasure Sets* by dividing the total number of drives in the :ref:`Server Pool <minio-intro-server-pool>` into sets consisting of between 4 and 16 drives each.
number of drives in the :ref:`Server Pool <minio-intro-server-pool>` into sets
consisting of between 4 and 16 drives each.
Use the MinIO For clusters, pools, or deployments with more than 16 drives, MinIO divides the drives into multiple erasure sets of the same number of drives.
`Erasure Coding Calculator <https://min.io/product/erasure-code-calculator>`__ For this reason, the total number of drives in a deployment must be divisible evenly by a number between 4 and 16.
to determine the optimal erasure set size for your preferred MinIO topology.
For example, 20 drives are divided into two erasure sets of 10 drives each.
28 drives are divided into 2 erasure sets of 14 drives each.
40 drives are divided into 4 erasure sets of 10 drives each.
Because numbers such as 17, 19, or 34 cannot be evenly divided by any number between 2 and 16, you cannot have a deployment with such a number of drives.
Add or remove drives to return to an allowable number of drives.
Use the MinIO `Erasure Coding Calculator <https://min.io/product/erasure-code-calculator>`__ to determine the optimal erasure set size for your preferred MinIO topology.
.. _minio-ec-parity: .. _minio-ec-parity:
Erasure Code Parity (``EC:N``) Erasure Code Parity (``EC:N``)
------------------------------ ------------------------------
MinIO uses a Reed-Solomon algorithm to split objects into data and parity blocks MinIO uses a Reed-Solomon algorithm to split objects into data and parity blocks based on the :ref:`Erasure Set <minio-ec-erasure-set>` size in the deployment.
based on the :ref:`Erasure Set <minio-ec-erasure-set>` size in the deployment. For a given erasure set of size ``M``, MinIO splits objects into ``N`` parity blocks and ``M-N`` data blocks.
For a given erasure set of size ``M``, MinIO splits objects into ``N`` parity
blocks and ``M-N`` data blocks.
MinIO uses the ``EC:N`` notation to refer to the number of parity blocks (``N``) MinIO uses the ``EC:N`` notation to refer to the number of parity blocks (``N``) in the deployment.
in the deployment. MinIO defaults to ``EC:4`` or 4 parity blocks per object. MinIO defaults to ``EC:4`` or 4 parity blocks per object.
MinIO uses the same ``EC:N`` value for all erasure sets and MinIO uses the same ``EC:N`` value for all erasure sets and :ref:`server pools <minio-intro-server-pool>` in the deployment.
:ref:`server pools <minio-intro-server-pool>` in the deployment.
MinIO can tolerate the loss of up to ``N`` drives per erasure set and MinIO can tolerate the loss of up to ``N`` drives per erasure set and continue performing read and write operations ("quorum").
continue performing read and write operations ("quorum"). If ``N`` is equal If ``N`` is equal to exactly 1/2 the drives in the erasure set, MinIO write quorum requires :math:`N + 1` drives to avoid data inconsistency ("split-brain").
to exactly 1/2 the drives in the erasure set, MinIO write quorum requires
``N+1`` drives to avoid data inconsistency ("split-brain").
Setting the parity for a deployment is a balance between availability Setting the parity for a deployment is a balance between availability and total usable storage.
and total usable storage. Higher parity values increase resiliency to drive Higher parity values increase resiliency to drive or node failure at the cost of usable storage, while lower parity provides maximum storage with reduced tolerance for drive/node failures.
or node failure at the cost of usable storage, while lower parity provides Use the MinIO `Erasure Code Calculator <https://min.io/product/erasure-code-calculator?ref=docs>`__ to explore the effect of parity on your planned cluster deployment.
maximum storage with reduced tolerance for drive/node failures.
Use the MinIO `Erasure Code Calculator
<https://min.io/product/erasure-code-calculator?ref=docs>`__ to explore the
effect of parity on your planned cluster deployment.
The following table lists the outcome of varying erasure code parity levels on The following table lists the outcome of varying erasure code parity levels on a MinIO deployment consisting of 1 node and 16 1TB drives:
a MinIO deployment consisting of 1 node and 16 1TB drives:
.. list-table:: Outcome of Parity Settings on a 16 Drive MinIO Cluster .. list-table:: Outcome of Parity Settings on a 16 Drive MinIO Cluster
:header-rows: 1 :header-rows: 1
@ -132,14 +116,14 @@ a MinIO deployment consisting of 1 node and 16 1TB drives:
Storage Classes Storage Classes
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
MinIO supports storage classes with Erasure Coding to allow applications to MinIO supports redundancy storage classes with Erasure Coding to allow applications to specify per-object :ref:`parity <minio-ec-parity>`.
specify per-object :ref:`parity <minio-ec-parity>`. Each storage class specifies Each storage class specifies a ``EC:N`` parity setting to apply to objects created with that class.
a ``EC:N`` parity setting to apply to objects created with that class.
MinIO storage classes are *distinct* from Amazon Web Services MinIO storage classes for erasure coding are *distinct* from Amazon Web Services :s3-docs:`storage classes <storage-class-intro.html>` used for tiering.
:s3-docs:`storage classes <storage-class-intro.html>`. MinIO storage classes MinIO erasure coding storage classes define *parity settings per object*, while AWS storage classes define *storage tiers per object*.
define *parity settings per object*, while AWS storage classes define *storage
tiers per object*. .. note::
For transitioning objects between storage classes for tiering purposes in MinIO, refer to the documentation on :ref:`lifecycle management <minio-lifecycle-management-tiering>`.
MinIO provides the following two storage classes: MinIO provides the following two storage classes:
@ -148,8 +132,7 @@ MinIO provides the following two storage classes:
.. tab-item:: STANDARD .. tab-item:: STANDARD
The ``STANDARD`` storage class is the default class for all objects. The ``STANDARD`` storage class is the default class for all objects.
MinIO sets the ``STANDARD`` parity based on the number of volumes MinIO sets the ``STANDARD`` parity based on the number of volumes in the Erasure Set:
in the Erasure Set:
.. list-table:: .. list-table::
:header-rows: 1 :header-rows: 1
@ -171,67 +154,51 @@ MinIO provides the following two storage classes:
You can override the default ``STANDARD`` parity using either: You can override the default ``STANDARD`` parity using either:
- The :envvar:`MINIO_STORAGE_CLASS_STANDARD` environment variable, *or* - The :envvar:`MINIO_STORAGE_CLASS_STANDARD` environment variable, *or*
- The :mc:`mc admin config` command to modify the - The :mc:`mc admin config` command to modify the ``storage_class.standard`` configuration setting.
``storage_class.standard`` configuration setting.
The maximum value is half of the total drives in the The maximum value is half of the total drives in the :ref:`Erasure Set <minio-ec-erasure-set>`.
:ref:`Erasure Set <minio-ec-erasure-set>`. The minimum value is ``2``. The minimum value is ``2``.
``STANDARD`` parity *must* be greater than or equal to ``STANDARD`` parity *must* be greater than or equal to ``REDUCED_REDUNDANCY``.
``REDUCED_REDUNDANCY``. If ``REDUCED_REDUNDANCY`` is unset, ``STANDARD`` If ``REDUCED_REDUNDANCY`` is unset, ``STANDARD`` parity *must* be greater than 2.
parity *must* be greater than 2.
.. tab-item:: REDUCED_REDUNDANCY .. tab-item:: REDUCED_REDUNDANCY
The ``REDUCED_REDUNDANCY`` storage class allows creating objects with The ``REDUCED_REDUNDANCY`` storage class allows creating objects with lower parity than ``STANDARD``.
lower parity than ``STANDARD``. ``REDUCED_REDUNDANCY`` requires ``REDUCED_REDUNDANCY`` requires *at least* 5 drives in the MinIO deployment.
*at least* 5 drives in the MinIO deployment.
MinIO sets the ``REDUCED_REDUNDANCY`` parity to ``EC:2`` by default. MinIO sets the ``REDUCED_REDUNDANCY`` parity to ``EC:2`` by default.
You can override ``REDUCED_REDUNDANCY`` storage class parity using You can override ``REDUCED_REDUNDANCY`` storage class parity using either:
either:
- The :envvar:`MINIO_STORAGE_CLASS_RRS` environment variable, *or* - The :envvar:`MINIO_STORAGE_CLASS_RRS` environment variable, *or*
- The :mc:`mc admin config` command to modify the - The :mc:`mc admin config` command to modify the ``storage_class.rrs`` configuration setting.
``storage_class.rrs`` configuration setting.
``REDUCED_REDUNDANCY`` parity *must* be less than or equal to ``REDUCED_REDUNDANCY`` parity *must* be less than or equal to ``STANDARD``.
``STANDARD``.
MinIO references the ``x-amz-storage-class`` header in request metadata for MinIO references the ``x-amz-storage-class`` header in request metadata for determining which storage class to assign an object.
determining which storage class to assign an object. The specific syntax The specific syntax or method for setting headers depends on your preferred method for interfacing with the MinIO server.
or method for setting headers depends on your preferred method for
interfacing with the MinIO server.
- For the :mc:`mc` command line tool, certain commands include a specific - For the :mc:`mc` command line tool, certain commands include a specific option for setting the storage class.
option for setting the storage class. For example, the :mc:`mc cp` command For example, the :mc:`mc cp` command has the :mc-cmd:`~mc cp storage-class` option for specifying the storage class to assign to the object being copied.
has the :mc-cmd:`~mc cp storage-class` option for specifying the
storage class to assign to the object being copied.
- For MinIO SDKs, the ``S3Client`` object has specific methods for setting - For MinIO SDKs, the ``S3Client`` object has specific methods for setting request headers.
request headers. For example, the ``minio-go`` SDK ``S3Client.PutObject`` For example, the ``minio-go`` SDK ``S3Client.PutObject`` method takes a ``PutObjectOptions`` data structure as a parameter.
method takes a ``PutObjectOptions`` data structure as a parameter. The ``PutObjectOptions`` data structure includes the ``StorageClass`` option for specifying the storage class to assign to the object being created.
The ``PutObjectOptions`` data structure includes the ``StorageClass``
option for specifying the storage class to assign to the object being
created.
.. _minio-ec-bitrot-protection: .. _minio-ec-bitrot-protection:
Bit Rot Protection Bit Rot Protection
----------------- ------------------
.. TODO- ReWrite w/ more detail. .. TODO- ReWrite w/ more detail.
Silent data corruption or bitrot is a serious problem faced by disk drives Silent data corruption or bit rot is a serious problem faced by disk drives resulting in data getting corrupted without the user’s knowledge.
resulting in data getting corrupted without the user’s knowledge. The reasons The corruption of data occurs when the electrical charge on a portion of the disk disperses or changes with no notification to or input from the user.
are manifold (ageing drives, current spikes, bugs in disk firmware, phantom Many events can lead to such a silent corruption of stored data.
writes, misdirected reads/writes, driver errors, accidental overwrites) but the For example, ageing drives, current spikes, bugs in disk firmware, phantom writes, misdirected reads/writes, driver errors, accidental overwrites, or a random cosmic ray can each lead to a bit change.
result is the same - compromised data. Whatever the cause, the result is the same - compromised data.
MinIO’s optimized implementation of the HighwayHash algorithm ensures that it MinIO’s optimized implementation of the :minio-git:`HighwayHash algorithm <highwayhash/blob/master/README.md>` ensures that it captures and heals corrupted objects on the fly.
will never read corrupted data - it captures and heals corrupted objects on the Integrity is ensured from end to end by computing a hash on READ and verifying it on WRITE from the application, across the network, and to the memory or drive.
fly. Integrity is ensured from end to end by computing a hash on READ and The implementation is designed for speed and can achieve hashing speeds over 10 GB/sec on a single core on Intel CPUs.
verifying it on WRITE from the application, across the network and to the
memory/drive. The implementation is designed for speed and can achieve hashing
speeds over 10 GB/sec on a single core on Intel CPUs.