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

Refactor the installation documentation

Browse Source 
Refactor the installation documentation

Address Code Review comments, further refinements

More review feedback fron Kannappan

Broken ref

More fixups

Final fixups
This commit is contained in:
ravindk89
2021-07-19 20:27:28 -04:00
committed by Ravind Kumar
parent f1126b1db4
commit 773e5c67b7
11 changed files with 1416 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
source/conf.py
View File

@ -67,6 +67,7 @@ extlinks = {
'legacy' : ('https://docs.min.io/docs/%s',''),
'docs-k8s' : ('https://docs.min.io/minio/k8s/%s',''),
'prometheus-docs' : ('https://prometheus.io/docs/%s',''),
'podman-docs' : ('http://docs.podman.io/en/latest/%s',''),
}

13
source/index.rst
View File

@ -68,7 +68,6 @@ such as versioning and replication.
export MINIO_ROOT_USER=myminioaccesskey
export MINIO_ROOT_PASSWORD=myminiosecretkey
export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server /mnt/data
@ -85,16 +84,6 @@ such as versioning and replication.
- The :ref:`root user <minio-users-root>` secret key. Replace the
sample value with a long, random, and unique string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The encryption key for the MinIO IAM backend. Replace the
sample value with a 32-bit base-64 encoded value. For example,
use the following command to generate a random key:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
The output resembles the following:
.. code-block:: shell
@ -144,7 +133,7 @@ such as versioning and replication.
/introduction/minio-overview
/concepts/feature-overview
/tutorials/minio-installation
/installation/deployment-and-management
/lifecycle-management/lifecycle-management-overview
/replication/replication-overview
/security/security-overview

480
source/installation/deploy-minio-distributed.rst Normal file
View File

@ -0,0 +1,480 @@
.. _deploy-minio-distributed:
================================
Deploy MinIO in Distributed Mode
================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
Overview
--------
A distributed MinIO deployment consists of 4 or more drives/volumes managed by
one or more :mc:`minio server` process, where the processes manage pooling the
compute and storage resources into a single aggregated object storage resource.
Each MinIO server has a complete picture of the distributed topology, such that
an application can connect to any node in the deployment and perform S3
operations.
Distributed deployments implicitly enable :ref:`erasure coding
<minio-erasure-coding>`, MinIO's data redundancy and availability feature that
allows deployments 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 less overhead than adjacent technologies such as RAID
or replication.
Depending on the configured :ref:`erasure code parity <minio-ec-parity>`, a
distributed deployment with ``m`` servers and ``n`` disks per server can
continue serving read and write operations with only ``m/2`` servers or
``m*n/2`` drives online and accessible.
Distributed deployments also support the following features:
- :ref:`Server-Side Object Replication <minio-bucket-replication-serverside>`
- :ref:`Write-Once Read-Many Locking <minio-bucket-locking>`
- :ref:`Object Versioning <minio-bucket-versioning>`
.. _deploy-minio-distributed-prereqs:
Prerequisites
-------------
Networking and Hostnames
~~~~~~~~~~~~~~~~~~~~~~~~
Each node should have full bidirectional network access to every other
node in the deployment. For containerized or orchestrated infrastructures,
this may require specific configuration of networking and routing
components such as ingress or load balancers.
MinIO *requires* using sequentially-numbered hostnames to represent each
:mc:`minio server` process in the deployment. Create the necessary DNS hostname
mappings *prior* to starting this procedure. For example, the following hostnames
would support a 4-node distributed deployment:
- ``minio1.example.com``
- ``minio2.example.com``
- ``minio3.example.com``
- ``minio4.example.com``
Configuring network and DNS to support MinIO is out of scope for this procedure.
Local JBOD Storage with Sequential Mounts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends local :abbr:`JBOD (Just a Bunch of Disks)` arrays for
best performance. RAID or similar technologies do not provide additional
resilience or availability benefits when used with distributed MinIO
deployments, and typically reduce system performance.
MinIO generally recommends ``xfs`` formatted drives for best performance.
MinIO **requires** using sequentially-numbered drives on each node in the
deployment, where the number sequence is *duplicated* across all nodes.
For example, the following sequence of mounted drives would support a 4-drive
per node distributed deployment:
- ``/mnt/disk1``
- ``/mnt/disk2``
- ``/mnt/disk3``
- ``/mnt/disk4``
Each mount should correspond to a locally-attached drive of the same type and
size. MinIO limits the size used per disk to the smallest drive in the
deployment. For example, if the deployment has 15 10TB disks and 1 1TB disk,
MinIO limits the per-disk capacity to 1TB. Similarly, use the same model NVME,
SSD, or HDD drives consistently across all nodes. Mixing drive types in the
same distributed deployment can result in unpredictable performance.
.. admonition:: Network File System Volumes Break Consistency Guarantees
:class: note
MinIO's strict **read-after-write** and **list-after-write** consistency
model requires local disk filesystems (``xfs``, ``ext4``, etc.).
MinIO cannot provide consistency guarantees if the underlying storage
volumes are NFS or a similar network-attached storage volume.
For deployments that *require* using network-attached storage, use
NFSv4 for best results.
Considerations
--------------
Homogeneous Node Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends selecting a hardware configuration for all nodes in
the deployment. Ensure the hardware (CPU, memory, motherboard, storage adapters)
and software (operating system, kernel settings, system services) is consistent
across all nodes.
The deployment may exhibit unpredictable performance if nodes have heterogeneous
hardware or software configurations.
Erasure Coding Parity
~~~~~~~~~~~~~~~~~~~~~
MinIO :ref:`erasure coding <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.
Erasure Coding provides object-level healing with less overhead than adjacent
technologies such as RAID or replication. Distributed deployments implicitly
enable and rely on erasure coding for core functionality.
Erasure Coding splits objects into data and parity blocks, where parity blocks
support reconstruction of missing or corrupted data blocks. The number of parity
blocks in a deployment controls the deployment's relative data redundancy.
Higher levels of parity allow for higher tolerance of drive loss at the cost of
total available storage.
MinIO defaults to ``EC:4`` , or 4 parity blocks per
:ref:`erasure set <minio-ec-erasure-set>`. You can set a custom parity
level by setting the appropriate
:ref:`MinIO Storage Class environment variable
<minio-server-envvar-storage-class>`. Consider using the MinIO
`Erasure Code Calculator <https://min.io/product/erasure-code-calculator>`__ for
guidance in selecting the appropriate erasure code parity level for your
cluster.
.. _deploy-minio-distributed-baremetal:
Procedure
---------
The following procedure creates a new distributed MinIO deployment consisting
of a single :ref:`Server Pool <minio-intro-server-pool>`.
Review the :ref:`deploy-minio-distributed-prereqs` before starting this
procedure.
1) Install the MinIO Binary on Each Node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the :program:`minio` binary onto each node in the deployment. Visit
`https://min.io/download <https://min.io/download?ref=docs>`__ and select the
tab most relevant to your use case. Follow the displayed instructions to
install the MinIO server binary on each node. Do *not* run the process yet.
2) Add TLS/SSL Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO enables :ref:`Transport Layer Security (TLS) <minio-TLS>` 1.2+
automatically upon detecting a valid x.509 certificate (``.crt``) and
private key (``.key``) in the MinIO ``certs`` directory:
- For Linux/MacOS: ``${HOME}/.minio/certs``
- For Windows: ``%%USERPROFILE%%\.minio\certs``
Ensure each node has the necessary x.509 certificates in the
``certs`` directory.
You can override the certificate directory using the
:mc-cmd-option:`minio server certs-dir` commandline argument.
You can optionally skip this step to deploy without TLS enabled. MinIO
strongly recommends *against* non-TLS deployments outside of early development.
3) Run the MinIO Server Process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Issue the following command on each node in the deployment. The
following example assumes that:
- The deployment has four nodes with sequential hostnames (i.e.
``minio1.example.com``, ``minio2.example.com``, etc.).
- Each node has 4 locally-attached disks mounted using sequential naming
semantics (i.e. ``/mnt/disk1/data``, ``/mnt/disk2/data``, etc.).
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data --console-address ":9001"
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Specify the *same* unique, random, and long string for all
nodes in the deployment.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Specify the *same* unique, random, and long string for all
nodes in the deployment.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). Single-key backend encryption
provides a baseline of security for non-production environments, and does
not support features like key rotation. You can leave this command
commented to deploy MinIO without backend encryption.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Specify the *same* encryption key for all nodes in the deployment.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Copy the key to a secure location. MinIO cannot decode the backend
without this key.
* - ``minio{1...4}.example.com/``
- The DNS hostname of each server in the distributed deployment specified
as a single Server Pool.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, the hostname
``https://minio{1...4}.example.com`` expands to:
- ``https://minio1.example.com``
- ``https://minio2.example.com``
- ``https://minio3.example.com``
- ``https://minio4.example.com``
The expanded set of hostnames must include all MinIO server nodes in the
server pool. Do **not** use a space-delimited series
(e.g. ``"HOSTNAME1 HOSTNAME2"``), as MinIO treats these as individual
server pools instead of grouping the hosts into one server pool.
* - ``/mnt/disk{1...4}/data``
- The path to each disk on the host machine.
``/data`` is an optional folder in which the ``minio`` server stores
all information related to the deployment.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
- ``/mnt/disk1/data``
- ``/mnt/disk2/data``
- ``/mnt/disk3/data``
- ``/mnt/disk4/data``
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
* - ``--console-address ":9001"``
- The static port on which the embedded MinIO Console listens for incoming
connections.
Omit to allow MinIO to select a dynamic port for the MinIO Console.
Browsers opening the root node hostname
``https://minio1.example.com:9000`` are automatically redirected to the
Console.
You may specify other :ref:`environment variables
<minio-server-environment-variables>` as required by your deployment.
4) Open the MinIO Console
~~~~~~~~~~~~~~~~~~~~~~~~~
Open your browser and access any of the MinIO hostnames at port ``:9001`` to
open the MinIO Console login page. For example,
``https://minio1.example.com:9001``.
Log in with the :guilabel:`MINIO_ROOT_USER` and :guilabel:`MINIO_ROOT_PASSWORD`
from the previous step.
.. image:: /images/minio-console-dashboard.png
:width: 600px
:alt: MinIO Console Dashboard displaying Monitoring Data
:align: center
You can use the MinIO Console for general administration tasks like
Identity and Access Management, Metrics and Log Monitoring, or
Server Configuration. Each MinIO server includes its own embedded MinIO
Console.
5) Next Steps
~~~~~~~~~~~~~
- Create an :ref:`alias <minio-mc-alias>` for accessing the deployment using
:mc:`mc`.
- :ref:`Create users and policies to control access to the deployment
<minio-authentication-and-identity-management>`.
.. _deploy-minio-distributed-recommendations:
Deployment Recommendations
--------------------------
Minimum Nodes per Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For all production deployments, MinIO recommends a *minimum* of 4 nodes per
:ref:`server pool <minio-intro-server-pool>` with 4 drives per server.
With the default :ref:`erasure code parity <minio-erasure-coding>` setting of
``EC:4``, this topology can continue serving read and write operations
despite the loss of up to 4 drives *or* one node.
The minimum recommendation reflects MinIO's experience with assisting enterprise
customers in deploying on a variety of IT infrastructures while maintaining the
desired SLA/SLO. While MinIO may run on less than the minimum recommended
topology, any potential cost savings come at the risk of decreased reliability.
Server Hardware
~~~~~~~~~~~~~~~
MinIO is hardware agnostic and runs on a variety of hardware architectures
ranging from ARM-based embedded systems to high-end x64 and POWER9 servers.
The following recommendations match MinIO's
`Reference Hardware <https://min.io/product/reference-hardware>`__ for
large-scale data storage:
.. list-table::
:stub-columns: 1
:widths: 20 80
:width: 100%
* - Processor
- Dual Intel Xeon Scalable Gold CPUs with 8 cores per socket.
* - Memory
- 128GB of Memory per pod
* - Network
- Minimum of 25GbE NIC and supporting network infrastructure between nodes.
MinIO can make maximum use of drive throughput, which can fully saturate
network links between MinIO nodes or clients. Large clusters may require
100GbE network infrastructure to fully utilize MinIO's per-node
performance potential.
* - Drives
- SATA/SAS NVMe/SSD with a minimum of 8 drives per server.
Drives should be :abbr:`JBOD (Just a Bunch of Disks)` arrays with
no RAID or similar technologies. MinIO recommends XFS formatting for
best performance.
Networking
~~~~~~~~~~
MinIO recommends high speed networking to support the maximum possible
throughput of the attached storage (aggregated drives, storage controllers,
and PCIe busses). The following table provides general guidelines for the
maximum storage throughput supported by a given NIC:
.. list-table::
:header-rows: 1
:width: 100%
:widths: 40 60
* - NIC bandwidth (Gbps)
- Estimated Aggregated Storage Throughput (GBps)
* - 10GbE
- 1GBps
* - 25GbE
- 2.5GBps
* - 50GbE
- 5GBps
* - 100GbE
- 10GBps
CPU Allocation
~~~~~~~~~~~~~~
MinIO can perform well with consumer-grade processors. MinIO can take advantage
of CPUs which support AVX-512 SIMD instructions for increased performance of
certain operations.
MinIO benefits from allocating CPU based on the expected per-host network
throughput. The following table provides general guidelines for allocating CPU
for use by based on the total network bandwidth supported by the host:
.. list-table::
:header-rows: 1
:width: 100%
:widths: 40 60
* - Host NIC Bandwidth
- Recommended Pod vCPU
* - 10GbE or less
- 8 vCPU per pod.
* - 25GbE
- 16 vCPU per pod.
* - 50GbE
- 32 vCPU per pod.
* - 100GbE
- 64 vCPU per pod.
Memory Allocation
~~~~~~~~~~~~~~~~~
MinIO benefits from allocating memory based on the total storage of each host.
The following table provides general guidelines for allocating memory for use
by MinIO server processes based on the total amount of local storage on the
host:
.. list-table::
:header-rows: 1
:width: 100%
:widths: 40 60
* - Total Host Storage
- Recommended Host Memory
* - Up to 1 Tebibyte (Ti)
- 8GiB
* - Up to 10 Tebibyte (Ti)
- 16GiB
* - Up to 100 Tebibyte (Ti)
- 32GiB
* - Up to 1 Pebibyte (Pi)
- 64GiB
* - More than 1 Pebibyte (Pi)
- 128GiB

394
source/installation/deploy-minio-standalone.rst Normal file
View File

@ -0,0 +1,394 @@
===============================
Deploy MinIO in Standalone Mode
===============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
The procedures on this page cover deploying MinIO in
:guilabel:`Standalone Mode`. A standalone MinIO deployment consists of a single
MinIO server process with a single drive or storage volume ("filesystem mode").
The MinIO server provides an S3 access layer to the drive or volume and stores
objects as-is without any :ref:`erasure coding <minio-erasure-coding>`.
For extended development or production environments, *or* to access
:ref:`advanced MinIO functionality <minio-installation-comparison>` deploy MinIO
in :guilabel:`Distributed Mode`. See :ref:`deploy-minio-distributed` for more
information.
.. _deploy-minio-standalone:
Deploy Standalone MinIO on Baremetal
------------------------------------
The following procedure deploys MinIO in :guilabel:`Standalone Mode` consisting
of a single MinIO server and a single drive or storage volume. Standalone
deployments are best suited for evaluation and initial development environments.
1) Download and Run MinIO Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Visit `https://min.io/download <https://min.io/download?ref=docs>`__ and select
the tab most relevant to your use case. Follow the displayed instructions to
download the :mc:`minio` binary to your local machine. The example instructions
use the ``/data`` folder by default. You can create or change this folder
as necessary for your deployment. The :mc:`minio` process must have
full access to the specified folder *and* all of its subfolders.
The :mc:`minio server` process prints its output to the system console, similar
to the following:
.. code-block:: shell
API: http://192.0.2.10:9000 http://127.0.0.1:9000
RootUser: minioadmin
RootPass: minioadmin
Console: http://192.0.2.10:9001 http://127.0.0.1:9001
RootUser: minioadmin
RootPass: minioadmin
Command-line: https://docs.min.io/docs/minio-client-quickstart-guide
$ mc alias set myminio http://192.0.2.10:9000 minioadmin minioadmin
Documentation: https://docs.min.io
WARNING: Detected default credentials 'minioadmin:minioadmin', we recommend that you change these values with 'MINIO_ROOT_USER' and 'MINIO_ROOT_PASSWORD' environment variables
Open your browser to any of the listed :guilabel:`Console` addresses to open the
MinIO Console and log in with the :guilabel:`RootUser` and :guilabel:`RootPass`.
You can use the MinIO Console for performing administration on the MinIO server.
For applications, use the :guilabel:`API` addresses to access the MinIO
server and perform S3 operations.
The following steps are optional but recommended for further securing the
MinIO deployment.
2) Add TLS Certificates
~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports enabling :ref:`Transport Layer Security (TLS) <minio-TLS>` 1.2+
automatically upon detecting a x.509 private key (``private.key``) and public
certificate (``public.crt``) in the MinIO ``certs`` directory:
- For Linux/MacOS: ``${HOME}/.minio/certs``
- For Windows: ``%%USERPROFILE%%\.minio\certs``
You can override the certificate directory using the
:mc-cmd-option:`minio server certs-dir` commandline argument.
3) Run the MinIO Server with Non-Default Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Issue the following command to start the :mc:`minio server` with non-default
credentials. The table following this command breaks down each portion of the
command:
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server /data --console-address ":9001"
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). Single-key backend encryption
provides a baseline of security for non-production environments, and does
not support features like key rotation. You can leave this command
commented to deploy MinIO without backend encryption.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Save the encryption key to a secure location. You cannot restart the
MinIO server without this key.
* - ``/data``
- The path to each disk on the host machine.
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
MinIO writes objects to the specified directory as is and without
:ref:`minio-erasure-coding`. Any other application accessing that
directory can read and modify stored objects.
* - ``--console-address ":9001"``
- The static port on which the embedded MinIO Console listens for incoming
connections.
Omit to allow MinIO to select a dynamic port for the MinIO Console.
With dynamic port selection, browsers opening the root node hostname
``https://minio1.example.com:9000`` are automatically redirected to the
Console.
You may specify other :ref:`environment variables
<minio-server-environment-variables>` as required by your deployment.
4) Open the MinIO Console
~~~~~~~~~~~~~~~~~~~~~~~~~
Open your browser to the DNS name or IP address corresponding to the
container and the MinIO Console port. For example,
``https://127.0.0.1:9001``.
Log in with the :guilabel:`MINIO_ROOT_USER` and :guilabel:`MINIO_ROOT_PASSWORD`
from the previous step.
.. image:: /images/minio-console-dashboard.png
:width: 600px
:alt: MinIO Console Dashboard displaying Monitoring Data
:align: center
You can use the MinIO Console for general administration tasks like
Identity and Access Management, Metrics and Log Monitoring, or
Server Configuration. Each MinIO server includes its own embedded MinIO
Console.
Applications should use the ``https://HOST-ADDRESS:9000`` to perform S3
operations against the MinIO server.
.. _deploy-minio-standalone-container:
Deploy Standalone MinIO in a Container
--------------------------------------
The following procedure deploys a single MinIO container with a single drive.
Standalone deployments are best suited for evaluation and initial development
environments.
The procedure uses `Podman <https://podman.io/>`__ for running the MinIO
container in rootfull mode. Configuring for rootless mode is out of scope for
this procedure.
1) Create a Configuration File to store Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO reads configuration values from environment variables. MinIO supports
reading these environment variables from ``/run/secrets/config.env``. Save
the ``config.env`` file as a :podman-docs:`Podman secret <secret.html>` and
specify it as part of running the container.
Create a file ``config.env`` using your preferred text editor and enter the
following environment variables:
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
Create the Podman secret using the ``config.env`` file:
.. code-block:: shell
:class: copyable
sudo podman secret create config.env config.env
The following table details each environment variable set in ``config.env``:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). Single-key backend encryption
provides a baseline of security for non-production environments, and does
not support features like key rotation. You can leave this command
commented to deploy MinIO without backend encryption.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Save the encryption key to a secure location. You cannot restart the
MinIO server without this key.
You may specify other :ref:`environment variables
<minio-server-environment-variables>` as required by your deployment.
2) Add TLS Certificates
~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports enabling :ref:`Transport Layer Security (TLS) <minio-TLS>` 1.2+
automatically upon detecting a x.509 private key (``private.key``) and public
certificate (``public.crt``) in the MinIO ``certs`` directory:
Create a Podman secret pointing to the x.509
``private.key`` and ``public.crt`` to use for the container.
.. code-block:: shell
:class: copyable
sudo podman secret create private.key /path/to/private.key
sudo podman secret create public.crt /path/to/public.crt
You can optionally skip this step to deploy without TLS enabled. MinIO
strongly recommends *against* non-TLS deployments outside of early development.
3) Run the MinIO Container
~~~~~~~~~~~~~~~~~~~~~~~~~~
Issue the following command to start the MinIO server in a container:
.. code-block:: shell
:class: copyable
sudo podman run -p 9000:9000 -p 9001:9001 \
-v /data:/data \
--secret private.key \
--secret public.crt \
--secret config.env \
minio/minio server /data \
--console-address ":9001" \
--certs-dir "/run/secrets/"
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - ``-p 9000:9000, -p 9001:9001``
- Exposes the container internal port ``9000`` and ``9001`` through
the node port ``9000`` and ``9001`` respectively.
Port ``9000`` is the default MinIO server listen port.
Port ``9001`` is the MinIO Console listen port specified by
the ``--console-address`` argument.
* - ``-v /data:/data``
- Mounts a local volume to the container at the specified path.
* - ``--secret ...``
- Mounts a secret to the container. The specified secrets correspond to
the following:
- The x.509 private and public key the MinIO server process uses for
enabling TLS.
- The ``config.env`` file from which MinIO looks for configuration
environment variables.
* - ``/data``
- The path to the container volume in which the ``minio`` server stores
all information related to the deployment.
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
* - ``--console-address ":9001"``
- The static port on which the embedded MinIO Console listens for incoming
connections.
Omit to allow MinIO to select a dynamic port for the MinIO Console.
With dynamic port selection, browsers opening the root node hostname
``https://minio1.example.com:9000`` are automatically redirected to the
Console.
* - ``--cert /run/secrets/``
- Directs the MinIO server to use the ``/run/secrets/`` folder for
retrieving x.509 certificates to use for enabling TLS.
4) Open the MinIO Console
~~~~~~~~~~~~~~~~~~~~~~~~~
Open your browser to the DNS name or IP address corresponding to the
container and the MinIO Console port. For example,
``https://127.0.0.1:9001``.
Log in with the :guilabel:`MINIO_ROOT_USER` and :guilabel:`MINIO_ROOT_PASSWORD`
from the previous step.
.. image:: /images/minio-console-dashboard.png
:width: 600px
:alt: MinIO Console Dashboard displaying Monitoring Data
:align: center
You can use the MinIO Console for general administration tasks like
Identity and Access Management, Metrics and Log Monitoring, or
Server Configuration. Each MinIO server includes its own embedded MinIO
Console.
Applications should use the ``https://HOST-ADDRESS:9000`` to perform S3
operations against the MinIO server.

126
source/installation/deployment-and-management.rst Normal file
View File

@ -0,0 +1,126 @@
.. _minio-installation:
=========================
Deployment and Management
=========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
MinIO is a software-defined high performance distributed object storage server.
You can run MinIO on consumer or enterprise-grade hardware and a variety
of operating systems and architectures.
MinIO supports two deployment modes: :guilabel:`Standalone` and
:guilabel:`Distributed`:
Standalone Deployments
A single MinIO server with a single storage volume or folder. Standalone
deployments are best suited for evaluation and initial development of
applications using MinIO for object storage, *or* for providing an S3 access
layer to single storage volume. Standalone deployments do not provide access
to the full set of MinIO's advanced S3 features and functionality.
Distributed Deployments
Two or more MinIO servers with multiple storage volumes per server.
Distributed deployments are best for production environments and
workloads and support all of MinIO's core and advanced S3 features and
functionality.
.. _minio-installation-comparison:
The following table compares the key functional differences between
:guilabel:`Standalone` and :guilabel:`Distributed` MinIO deployments:
.. list-table::
:header-rows: 1
:widths: 20 40 40
:width: 100%
* -
- :guilabel:`Standalone`
- :guilabel:`Distributed`
* - Site-to-Site Replication
- Client-Side via :mc:`mc mirror`
- :ref:`Server-Side Replication <minio-bucket-replication>`
* - Versioning
- No
- :ref:`Object Versioning <minio-bucket-versioning>`
* - Retention
- No
- :ref:`Write-Once Read-Many Locking <minio-bucket-locking>`
* - High Availability / Redundancy
- Drive Level Only (RAID and similar)
- :ref:`Erasure Coding <minio-erasure-coding>`
* - Scaling
- No
- :ref:`Server Pool Expansion <expand-minio-distributed>`.
For tutorials on deploying or expanding a distributed MinIO deployment, see:
- :ref:`deploy-minio-distributed`
- :ref:`expand-minio-distributed`
For instructions on deploying MinIO in Kubernetes, see
:docs-k8s:`Deploy a MinIO Tenant using the MinIO Kubernetes Plugin
<tenant-management/deploy-minio-tenant.html>`
For tutorials on deploying a standalone MinIO deployment, see:
- :ref:`deploy-minio-standalone`
- :ref:`deploy-minio-standalone-container`
Platform Support
----------------
MinIO provides builds of the MinIO server (:mc:`minio`) and the
MinIO :abbr:`CLI (Command Line Interface)` (:mc:`mc`) for the following
platforms.
.. list-table::
:stub-columns: 1
:widths: 20 80
:width: 100%
* - Linux
- MinIO recommends RHEL8+ or Ubuntu 18.04+.
MinIO provides builds for the following architectures:
- AMD64
- ARM64
- PowerPC 64 LE
- S390X
* - macOS
- MinIO recommends non-EOL macOS versions (10.14+)
* - Microsoft Windows
- MinIO recommends non-EOL Windows versions (Windows 10, Windows Server
2016+)
For unlisted platforms or architectures, please reach out to MinIO at
hello@min.io for additional support and guidance. You can build MinIO from
:minio-git:`source <minio/#install-from-source>` and
`cross-compile
<https://golang.org/doc/install/source#bootstrapFromCrosscompiledSource>`__
for your platform and architecture combo. MinIO generally does not recommend
source-based installations in production environments.
.. toctree::
:titlesonly:
:hidden:
/installation/deploy-minio-distributed
/installation/expand-minio-distributed
/installation/deploy-minio-standalone
/installation/upgrade-minio

336
source/installation/expand-minio-distributed.rst Normal file
View File

@ -0,0 +1,336 @@
.. _expand-minio-distributed:
=====================================
Expand a Distributed MinIO Deployment
=====================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
A distributed MinIO deployment consists of 4 or more drives/volumes managed by
one or more :mc:`minio server` process, where the processes manage pooling the
compute and storage resources into a single aggregated object storage resource.
Each MinIO server has a complete picture of the distributed topology, such that
an application can connect to any node in the deployment and perform S3
operations.
MinIO supports expanding an existing distributed deployment by adding a new
:ref:`Server Pool <minio-intro-server-pool>`. Each Pool expands the total
available storage capacity of the cluster while maintaining the overall
:ref:`availability <minio-erasure-coding>` of the cluster. Each Pool is its
own failure domain, where the loss of one or more disks or nodes in that pool
does not effect the availability of other pools in the deployment.
The procedure on this page expands an existing
:ref:`distributed <deploy-minio-distributed>` MinIO deployment with an
additional server pool.
.. _expand-minio-distributed-prereqs:
Prerequisites
-------------
Networking and Hostnames
~~~~~~~~~~~~~~~~~~~~~~~~
Each node should have full bidirectional network access to every other node in
the new server pool *and* the existing pools in the deployment. For
containerized or orchestrated infrastructures, this may require specific
configuration of networking and routing components such as ingress or load
balancers.
MinIO *requires* using sequentially-numbered hostnames to represent each
:mc:`minio server` process in the server pool. Create the necessary DNS hostname
mappings *prior* to starting this procedure. For example, the following
hostnames would support a 4-node distributed server pool:
- ``minio1.example.com``
- ``minio2.example.com``
- ``minio3.example.com``
- ``minio4.example.com``
Configuring network and DNS to support MinIO is out of scope for this procedure.
Local Storage
~~~~~~~~~~~~~
MinIO strongly recommends local :abbr:`JBOD (Just a Bunch of Disks)` arrays for
best performance. RAID or similar technologies do not provide additional
resilience or availability benefits when used with distributed MinIO
deployments, and typically reduce system performance.
MinIO generally recommends ``xfs`` formatted drives for best performance.
MinIO **requires** using sequentially-numbered drives on each node in the
deployment, where the number sequence is *duplicated* across all nodes.
For example, the following sequence of mounted drives would support a 4-drive
per node distributed deployment:
- ``/mnt/disk1``
- ``/mnt/disk2``
- ``/mnt/disk3``
- ``/mnt/disk4``
Each mount should correspond to a locally-attached drive of the same type and
size. MinIO limits the size used per disk to the smallest drive in the
deployment. For example, if the deployment has 15 10TB disks and 1 1TB disk,
MinIO limits the per-disk capacity to 1TB. Similarly, use the same model NVME,
SSD, or HDD drives consistently across all nodes. Mixing drive types in the
same distributed deployment can result in unpredictable performance.
.. admonition:: Network File System Volumes Break Consistency Guarantees
:class: note
MinIO's strict **read-after-write** and **list-after-write** consistency
model requires local disk filesystems (``xfs``, ``ext4``, etc.).
MinIO cannot provide consistency guarantees if the underlying storage
volumes are NFS or a similar network-attached storage volume.
For deployments that *require* using network-attached storage, use
NFSv4 for best results.
Minimum Drives for Erasure Code Parity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO requires each pool satisfy the deployment
:ref:`erasure code <minio-erasure-coding>` settings. Specifically,
the new pool must have *at least* 2x the number of drives as the
:ref:`Standard <minio-ec-storage-class>` parity storage class. This requirement
ensures the new server pool can satisfy the
expected :abbr:`SLA (Service Level Agreement)` of the deployment.
For example, consider a MinIO deployment with a single 16-node server pool
using the default erasure code parity ``EC:4``. The new server pool
must *at least* 8 drives (``4*2``) to satisfy ``EC:4``.
Considerations
--------------
Homogeneous Node Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends selecting a hardware configuration for all nodes in
the new server pool. Ensure the hardware (CPU, memory, motherboard, storage
adapters) and software (operating system, kernel settings, system services) is
consistent across all nodes in the pool. The new pool may exhibit unpredictable
performance if nodes have heterogeneous hardware or software configurations.
Similarly, MinIO also recommends that the hardware and software configurations
for the new pool nodes are substantially similar to existing server pools. This
ensures consistent performance of operations across the cluster regardless of
which pool a given application performs operations against.
Expansion Requires Downtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adding a new server pool requires restarting *all* MinIO nodes in the
deployment at the same time. This results in a brief period of downtime.
You cannot perform a "rolling" restart while expanding a MinIO
deployment.
Procedure
---------
The following procedure adds a :ref:`Server Pool <minio-intro-server-pool>`
to an existing MinIO deployment. Each Pool expands the total available
storage capacity of the cluster while maintaining the overall
:ref:`availability <minio-erasure-coding>` of the cluster.
Review the :ref:`expand-minio-distributed-prereqs` before starting this
procedure.
1) Install the MinIO Binary on Each Node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the :program:`minio` binary onto each node in the new server pool. Visit
`https://min.io/download <https://min.io/download?ref=docs>`__ and select the
tab most relevant to your use case. Follow the displayed instructions to
install the MinIO server binary on each node. Do *not* run the process yet.
2) Add TLS/SSL Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO enables :ref:`Transport Layer Security (TLS) <minio-TLS>` 1.2+
automatically upon detecting a valid x.509 certificate (``.crt``) and
private key (``.key``) in the MinIO ``certs`` directory:
- For Linux/MacOS: ``${HOME}/.minio/certs``
- For Windows: ``%%USERPROFILE%%\.minio\certs``
Ensure each node has the necessary x.509 certificates in the
``certs`` directory.
You can override the certificate directory using the
:mc-cmd-option:`minio server certs-dir` commandline argument.
You can optionally skip this step to deploy without TLS enabled. MinIO
strongly recommends *against* non-TLS deployments outside of early development.
3) Run the MinIO Server Process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Issue the following command on all nodes in the deployment, including the
existing server pools. This *requires* stopping all MinIO server processes:
The following example assumes that:
- The existing deployment consists of a single server pool reachable via
``https://minio{1...4}.example.com``.
- All nodes in the deployment have sequential hostnames (i.e.
``minio1.example.com``, ``minio2.example.com``, etc.).
- Each node has 4 locally-attached disks mounted using sequential naming
semantics (i.e. ``/mnt/disk1/data``, ``/mnt/disk2/data``, etc.).
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data \
https://minio{5...8}.example.com/mnt/disk{1...4}/data \
--console-address ":9001"
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Specify the *same* unique, random, and long string for all
nodes in the deployment.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Specify the *same* unique, random, and long string for all
nodes in the deployment.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). You can leave this command
commented to deploy MinIO without backend encryption. MinIO strongly
recommends deploying with encryption enabled.
Specify the *same* encryption key used to start the existing
MinIO server pool nodes.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Copy the key to a secure location. MinIO cannot decode the backend
without this key.
Single-key backend encryption provides a baseline of security for most
environments. For production environments with stricter security
requirements, you can migrate to using the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external
Key Management System (KMS) for storing the encryption key.
See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
* - ``minio{1...4}.example.com/``
- The DNS hostname of each existing MinIO server in the deployment.
Each set of hostnames describes a single server pool in the
deployment.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, the hostname
``https://minio{1...4}.example.com`` expands to:
- ``https://minio1.example.com``
- ``https://minio2.example.com``
- ``https://minio3.example.com``
- ``https://minio4.example.com``
These hostnames should match the existing server pool hostname sets used
to start each MinIO server in the deployment.
* - ``minio{5...8}.example.com/``
- The DNS hostname of each server in the new server pool.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, the hostname
``https://minio{1...4}.example.com`` expands to:
- ``https://minio1.example.com``
- ``https://minio2.example.com``
- ``https://minio3.example.com``
- ``https://minio4.example.com``
The expanded set of hostnames must include all MinIO server nodes in the
server pool. Do **not** use a space-delimited series
(e.g. ``"HOSTNAME1 HOSTNAME2"``), as MinIO treats these as individual
server pools instead of grouping the hosts into one server pool.
* - ``/mnt/disk{1...4}/data``
- The path to each disk on the host machine.
``/data`` is an optional folder in which the ``minio`` server stores
all information related to the deployment.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
- ``/mnt/disk1/data``
- ``/mnt/disk2/data``
- ``/mnt/disk3/data``
- ``/mnt/disk4/data``
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
* - ``--console-address ":9001"``
- The static port on which the embedded MinIO Console listens for incoming
connections.
Omit to allow MinIO to select a dynamic port for the MinIO Console.
Browsers opening the root node hostname
``https://minio1.example.com:9000`` are automatically redirected to the
Console.
You may specify other :ref:`environment variables
<minio-server-environment-variables>` as required by your deployment.
4) Open the MinIO Console
~~~~~~~~~~~~~~~~~~~~~~~~~
Open your browser and access any of the MinIO hostnames at port ``:9001`` to
open the MinIO Console login page. For example,
``https://minio1.example.com:9001``.
Log in with the :guilabel:`MINIO_ROOT_USER` and :guilabel:`MINIO_ROOT_PASSWORD`
from the previous step.
.. image:: /images/minio-console-dashboard.png
:width: 600px
:alt: MinIO Console Dashboard displaying Monitoring Data
:align: center
You can use the MinIO Console for general administration tasks like
Identity and Access Management, Metrics and Log Monitoring, or
Server Configuration. Each MinIO server includes its own embedded MinIO
Console.

62
source/installation/upgrade-minio.rst Normal file
View File

@ -0,0 +1,62 @@
.. _minio-upgrade:
==========================
Upgrade a MinIO Deployment
==========================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. admonition:: Test Upgrades Before Applying To Production
:class: important
MinIO **strongly discourages** performing blind updates to production
clusters. You should *always* test upgrades in a lower environment
(dev/QA/staging) *before* applying upgrades to production deployments.
Exercise particular caution if upgrading to a
:minio-git:`release <minio/releases>` that has backwards breaking changes.
MinIO always includes warnings in release notes if a given version does
*not* support downgrades.
For MinIO deployments that are significantly behind latest stable
(6+ months), consider using
`MinIO SUBNET <https://min.io/pricing?ref=docs>`__ for additional support
and guidance during the upgrade procedure.
Use the :mc-cmd:`mc admin update` command to update a :ref:`Standalone
<deploy-minio-standalone>` or :ref:`Distributed <deploy-minio-distributed>`
MinIO deployment to the latest stable :minio-git:`release <minio/releases>`.
.. code-block:: shell
:class: copyable
mc admin update ALIAS
Replace :mc-cmd:`ALIAS <mc admin update ALIAS>` with the
:mc-cmd:`alias <mc alias>` of the MinIO deployment.
:mc-cmd:`mc admin update` affects *all* MinIO servers in the target deployment
at the same time. The update procedure interrupts in-progress API operations on
the MinIO deployment. Exercise caution before issuing an update command on
production environments.
You can specify a custom URL for updating the MinIO deployment using a specific
MinIO server binary:
.. code-block:: shell
:class: copyable
mc admin update ALIAS https://minio-mirror.example.com/minio
You should upgrade your :mc:`mc` binary to match or closely follow the
MinIO server release. You can use the :mc:`mc update` command to update the
binary to the latest stable release:
.. code-block:: shell
:class: copyable
mc update

2
source/reference/minio-cli/minio-mc/mc-alias.rst
View File

@ -1,3 +1,5 @@
.. _minio-mc-alias:
============
``mc alias``
============

2
source/reference/minio-cli/minio-mc/mc-retention.rst
View File

@ -1,3 +1,5 @@
.. _minio-bucket-locking:
================
``mc retention``
================

15
source/reference/minio-server/minio-server.rst
View File

@ -302,9 +302,16 @@ Key Management Service and Encryption
.. versionadded:: RELEASE.2021-04-22T15-44-28Z
The client-provided encryption key to use for encrypting the
MinIO backend (users, groups, policies, and server configuration).
See :minio-git:`KMS IAM/Config Encryption
The client-provided encryption key to use for encrypting the MinIO backend
(users, groups, policies, and server configuration). Single-key backend
encryption provides a baseline of security for non-production environments,
and does not support features like key rotation.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Specify a 32-bit base-64 encrypted string in the following format:
@ -363,6 +370,8 @@ Key Management Service and Encryption
this key for supporting server-side encryption of objects (SSE-S3) and MinIO
backend encryption.
.. _minio-server-envvar-storage-class:
Storage Class
~~~~~~~~~~~~~

463
source/tutorials/minio-installation.rst
View File

@ -1,463 +0,0 @@
.. _minio-installation:
============
Installation
============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
MinIO is a high performance distributed object storage server, designed for
large-scale private cloud infrastructure. MinIO fully supports deployment onto
bare-metal hardware with or without containerization for process management.
Distributed Installation
------------------------
Distributed MinIO deployments consist of multiple ``minio`` servers with
one or more disks each. Distributed deployments are best suited for
staging and production environments.
MinIO *requires* using sequentially-numbered hostnames to represent each
``minio`` server in the deployment. For example, the following hostnames support
a 4-node distributed deployment:
- ``minio1.example.com``
- ``minio2.example.com``
- ``minio3.example.com``
- ``minio4.example.com``
Create the necessary DNS hostname mappings *prior* to starting this
procedure.
1\) Install the ``minio`` Server
Install the :program:`minio` server onto each host machine in the deployment.
Select the tab that corresponds to the host machine operating system or
environment:
.. include:: /includes/minio-server-installation.rst
2\) Add TLS/SSL Certificates (Optional)
Enable TLS/SSL connectivity to the MinIO server by specifying a private key
(``.key``) and public certificate (``.crt``) to the MinIO ``certs`` directory:
- For Linux/MacOS: ``${HOME}/.minio/certs``
- For Windows: ``%%USERPROFILE%%\.minio\certs``
The MinIO server automatically enables TLS/SSL connectivity if it detects
the required certificates in the ``certs`` directory.
.. note::
The MinIO documentation makes a best-effort to provide generally applicable
and accurate information on TLS/SSL connectivity in the context of MinIO
products and services, and is not intended as a complete guide to the larger
topic of TLS/SSL certificate creation and management.
3\) Run the ``minio`` Server
Issue the following command on each host machine in the deployment. The
following example assumes that:
- The deployment has four host machines with sequential hostnames (i.e.
``minio1.example.com``, ``minio2.example.com``).
- Each host machine has *at least* four disks mounted at ``/data``. 4 disks
is the minimum required for :ref:`erasure coding <minio-erasure-coding>`.
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration).
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``minio{1...4}.example.com/``
- The DNS hostname of each server in the distributed deployment.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, the hostname
``https://minio{1...4}.example.com`` expands to:
- ``https://minio1.example.com``
- ``https://minio2.example.com``
- ``https://minio3.example.com``
- ``https://minio4.example.com``
* - ``/mnt/disk{1...4}/data``
- The path to each disk on the host machine.
``/data`` is an optional folder in which the ``minio`` server stores
all information related to the deployment.
The command uses MinIO expansion notation ``{x...y}`` to denote a sequential
series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
- ``/mnt/disk1/data``
- ``/mnt/disk2/data``
- ``/mnt/disk3/data``
- ``/mnt/disk4/data``
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
4\) Connect to the Server
Use the :mc-cmd:`mc alias set` command from a machine with connectivity to any
hostname running the ``minio`` server. See :ref:`mc-install` for documentation
on installing :program:`mc`.
.. code-block:: shell
:class: copyable
mc alias set mylocalminio minio1.example.net minioadmin minio-secret-key-CHANGE-ME
See :ref:`minio-mc-commands` for a list of commands you can run on the
MinIO server.
Docker Installation
-------------------
Stable MinIO
~~~~~~~~~~~~
The following ``docker`` command creates a container running the latest stable
version of the ``minio`` server process:
.. code-block:: shell
:class: copyable
docker run -p 9000:9000 \
-e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
-e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_KMS_SECRET_KEY_FILE=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=" \
-v /mnt/disk1:/disk1 \
-v /mnt/disk2:/disk2 \
-v /mnt/disk3:/disk3 \
-v /mnt/disk4:/disk4 \
minio/minio server /disk{1...4}
The command uses the following options:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER_FILE <MINIO_ROOT_USER>`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD_FILE <MINIO_ROOT_PASSWORD>`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY_FILE <MINIO_KMS_SECRET_KEY>`
- The key to use for encrypting the MinIO backend (S3 objects, users,
groups, policies, and server configuration).
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``-v /mnt/disk<int>:/disk<int>``
- The path to each each disk the ``minio`` server uses.
Bleeding Edge MinIO
~~~~~~~~~~~~~~~~~~~
*Do not use bleeding-edge deployments of MinIO in production environments*
The following ``docker`` command creates a container running the latest
bleeding-edge version of the ``minio`` server process:
.. code-block:: shell
:class: copyable
docker run -p 9000:9000 \
-e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
-e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_KMS_SECRET_KEY_FILE=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=" \
-v /mnt/disk1:/disk1 \
-v /mnt/disk2:/disk2 \
-v /mnt/disk3:/disk3 \
-v /mnt/disk4:/disk4 \
minio/minio:edge server /disk{1...4}
The command uses the following options:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER_FILE <MINIO_ROOT_USER>`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD_FILE <MINIO_ROOT_PASSWORD>`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY_FILE <MINIO_KMS_SECRET_KEY>`
- The key to use for encrypting the MinIO backend (S3 objects, users,
groups, policies, and server configuration).
Replace this value with a 32-bit base64-encrypted string:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``-v /mnt/disk<int>:/disk<int>``
- The path to each each disk the ``minio`` server uses.
Standalone Installation
-----------------------
Standalone MinIO deployments consist of a single ``minio`` server process with
one or more disks. Standalone deployments are best suited for local development
environments.
1\) Install the ``minio`` Server
Install the :program:`minio` server onto the host machine. Select the tab that
corresponds to the host machine operating system or environment:
.. include:: /includes/minio-server-installation.rst
2\) Add TLS/SSL Certificates (Optional)
Enable TLS/SSL connectivity to the MinIO server by specifying a private key
(``.key``) and public certificate (``.crt``) to the MinIO ``certs`` directory:
- For Linux/MacOS: ``${HOME}/.minio/certs``
- For Windows: ``%%USERPROFILE%%\.minio\certs``
The MinIO server automatically enables TLS/SSL connectivity if it detects
the required certificates in the ``certs`` directory.
.. note::
The MinIO documentation makes a best-effort to provide generally applicable
and accurate information on TLS/SSL connectivity in the context of MinIO
products and services, and is not intended as a complete guide to the larger
topic of TLS/SSL certificate creation and management.
3\) Run the ``minio`` Server
Issue the following command to start the :program:`minio` server. The following
example assumes the host machine has *at least* four disks, which is the minimum
required number of disks to enable :ref:`erasure coding <minio-erasure-coding>`:
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server /mnt/disk{1...4}/data
The example command breaks down as follows:
.. list-table::
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ROOT_USER`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration).
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``/mnt/disk{1...4}/data``
- The path to each disk on the host machine.
``/data`` is an optional folder in which the ``minio`` server stores
all information related to the deployment.
See :mc-cmd:`minio server DIRECTORIES` for more information on
configuring the backing storage for the :mc:`minio server` process.
The command uses MinIO expansion notation ``{x...y}`` to denote a
sequential series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
- ``/mnt/disk1/data``
- ``/mnt/disk2/data``
- ``/mnt/disk3/data``
- ``/mnt/disk4/data``
4\) Connect to the Server
Use the :mc-cmd:`mc alias set` command from a machine with connectivity to
the host running the ``minio`` server. See :ref:`mc-install` for documentation
on installing :program:`mc`.
.. code-block:: shell
:class: copyable
mc alias set mylocalminio 192.0.2.10:9000 minioadmin minio-secret-key-CHANGE-ME
Replace the IP address and port with one of the ``minio`` servers endpoints.
See :ref:`minio-mc-commands` for a list of commands you can run on the
MinIO server.
Deployment Recommendations
--------------------------
Minimum Nodes per Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For all production deployments, MinIO recommends a *minimum* of 4 nodes per
cluster. MinIO deployments with *at least* 4 nodes can tolerate the loss of up
to half the nodes *or* half the disks in the deployment while maintaining
read and write availability.
For example, assuming a 4-node deployment with 4 drives per node, the
cluster can tolerate the loss of:
- Any two nodes, *or*
- Any 8 drives.
The minimum recommendation reflects MinIO's experience with assisting enterprise
customers in deploying on a variety of IT infrastructures while
maintaining the desired SLA/SLO. While MinIO may run on less than the
minimum recommended topology, any potential cost savings come at the risk of
decreased reliability.
Recommended Hardware
~~~~~~~~~~~~~~~~~~~~
For MinIO's recommended hardware, please see
`MinIO Reference Hardware <https://min.io/product/reference-hardware>`__.
Bare Metal Infrastructure
~~~~~~~~~~~~~~~~~~~~~~~~~
A distributed MinIO deployment can only provide as much availability as the
bare metal infrastructure on which it is deployed. In particular, consider the
following potential failure points which could result in cluster downtime
when configuring your bare metal infrastructure:
- Shared networking resources (switches, routers, ISP).
- Shared power resources.
- Shared physical location (rack, datacenter, region).
MinIO deployments using virtual machines or containerized environments should
also consider the following:
- Shared physical hardware (CPU, Memory, Storage)
- Shared orchestration management layer (Kubernetes, Docker Swarm)
FreeBSD
-------
MinIO does not provide an official FreeBSD binary. FreeBSD maintains an
`upstream release <https://www.freshports.org/www/minio>`__ you can
install using `pkg <https://github.com/freebsd/pkg>`__:
.. code-block:: shell
:class: copyable
pkg install minio
sysrc minio_enable=yes
sysrc minio_disks=/path/to/disks
service minio start