diff --git a/source/conf.py b/source/conf.py index 51804c0d..bbcf44d6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -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',''), } diff --git a/source/index.rst b/source/index.rst index ff4b4987..c04ec5df 100644 --- a/source/index.rst +++ b/source/index.rst @@ -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 ` 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 diff --git a/source/installation/deploy-minio-distributed.rst b/source/installation/deploy-minio-distributed.rst new file mode 100644 index 00000000..4a021312 --- /dev/null +++ b/source/installation/deploy-minio-distributed.rst @@ -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'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 `, 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 ` +- :ref:`Write-Once Read-Many Locking ` +- :ref:`Object 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 ` 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 `. You can set a custom parity +level by setting the appropriate +:ref:`MinIO Storage Class environment variable +`. Consider using the MinIO +`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 `. + +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 `__ 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) ` 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 ` 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 ` 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) ` 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 + ` for more information. + + Specify the *same* encryption key for all nodes in the deployment. + + Use the following format when specifying the encryption key: + + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` 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 +` 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 ` for accessing the deployment using + :mc:`mc`. + +- :ref:`Create users and policies to control access to the deployment + `. + +.. _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 ` with 4 drives per server. +With the default :ref:`erasure code parity ` 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 `__ 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 + \ No newline at end of file diff --git a/source/installation/deploy-minio-standalone.rst b/source/installation/deploy-minio-standalone.rst new file mode 100644 index 00000000..d3c69c1a --- /dev/null +++ b/source/installation/deploy-minio-standalone.rst @@ -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 `. + +For extended development or production environments, *or* to access +:ref:`advanced MinIO functionality ` 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 `__ 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) ` 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 ` 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 ` 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) ` 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 + ` for more information. + + Use the following format when specifying the encryption key: + + ``:`` + + - Replace the ```` 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 + ` for more information. + + - Replace ```` 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 +` 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 `__ 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 ` 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 ` 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 ` 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) ` 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 + ` for more information. + + Use the following format when specifying the encryption key: + + ``:`` + + - Replace the ```` 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 + ` for more information. + + - Replace ```` 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 +` as required by your deployment. + +2) Add TLS Certificates +~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO supports enabling :ref:`Transport Layer Security (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. \ No newline at end of file diff --git a/source/installation/deployment-and-management.rst b/source/installation/deployment-and-management.rst new file mode 100644 index 00000000..1b31fa6b --- /dev/null +++ b/source/installation/deployment-and-management.rst @@ -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 ` + + * - Versioning + - No + - :ref:`Object Versioning ` + + * - Retention + - No + - :ref:`Write-Once Read-Many Locking ` + + * - High Availability / Redundancy + - Drive Level Only (RAID and similar) + - :ref:`Erasure Coding ` + + * - Scaling + - No + - :ref:`Server Pool Expansion `. + +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 +` + +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 ` and +`cross-compile +`__ +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 \ No newline at end of file diff --git a/source/installation/expand-minio-distributed.rst b/source/installation/expand-minio-distributed.rst new file mode 100644 index 00000000..c8f637e0 --- /dev/null +++ b/source/installation/expand-minio-distributed.rst @@ -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 `. Each Pool expands the total +available storage capacity of the cluster while maintaining the overall +:ref:`availability ` 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 ` 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 ` settings. Specifically, +the new pool must have *at least* 2x the number of drives as the +:ref:`Standard ` 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 ` +to an existing MinIO deployment. Each Pool expands the total available +storage capacity of the cluster while maintaining the overall +:ref:`availability ` 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 `__ 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) ` 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 ` 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 ` 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: + + ``:`` + + - Replace the ```` with any string. + + - Replace ```` 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) ` and an external + Key Management System (KMS) for storing the encryption key. + See :minio-git:`KMS IAM/Config Encryption + ` 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 +` 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. diff --git a/source/installation/upgrade-minio.rst b/source/installation/upgrade-minio.rst new file mode 100644 index 00000000..5cb96342 --- /dev/null +++ b/source/installation/upgrade-minio.rst @@ -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 ` 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 `__ for additional support + and guidance during the upgrade procedure. + +Use the :mc-cmd:`mc admin update` command to update a :ref:`Standalone +` or :ref:`Distributed ` +MinIO deployment to the latest stable :minio-git:`release `. + +.. code-block:: shell + :class: copyable + + mc admin update ALIAS + +Replace :mc-cmd:`ALIAS ` with the +:mc-cmd:`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 \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-alias.rst b/source/reference/minio-cli/minio-mc/mc-alias.rst index a9c1d226..07c0de3d 100644 --- a/source/reference/minio-cli/minio-mc/mc-alias.rst +++ b/source/reference/minio-cli/minio-mc/mc-alias.rst @@ -1,3 +1,5 @@ +.. _minio-mc-alias: + ============ ``mc alias`` ============ diff --git a/source/reference/minio-cli/minio-mc/mc-retention.rst b/source/reference/minio-cli/minio-mc/mc-retention.rst index e6e3bb8d..fc8dad2f 100644 --- a/source/reference/minio-cli/minio-mc/mc-retention.rst +++ b/source/reference/minio-cli/minio-mc/mc-retention.rst @@ -1,3 +1,5 @@ +.. _minio-bucket-locking: + ================ ``mc retention`` ================ diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index 717e1829..e52ecf9e 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -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) ` 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 ` 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 ~~~~~~~~~~~~~ diff --git a/source/tutorials/minio-installation.rst b/source/tutorials/minio-installation.rst deleted file mode 100644 index d1cfccc2..00000000 --- a/source/tutorials/minio-installation.rst +++ /dev/null @@ -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 `. - - .. 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 ` 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 ` 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: - - ``:`` - - - Replace the ```` with any string. You must use this - key name if you later migrate to using a dedicated KMS for - managing encryption keys. - - - Replace ```` 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 ` - - The access key for the :ref:`root ` user. - - Replace this value with a unique, random, and long string. - - * - :envvar:`MINIO_ROOT_PASSWORD_FILE ` - - The corresponding secret key to use for the - :ref:`root ` user. - - Replace this value with a unique, random, and long string. - - * - :envvar:`MINIO_KMS_SECRET_KEY_FILE ` - - 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: - - ``:`` - - - Replace the ```` with any string. You must use this - key name if you later migrate to using a dedicated KMS for - managing encryption keys. - - - Replace ```` with a 32-bit base64 encoded value. - For example: - - .. code-block:: shell - :class: copyable - - cat /dev/urandom | head -c 32 | base64 - - - * - ``-v /mnt/disk:/disk`` - - 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 ` - - The access key for the :ref:`root ` user. - - Replace this value with a unique, random, and long string. - - * - :envvar:`MINIO_ROOT_PASSWORD_FILE ` - - The corresponding secret key to use for the - :ref:`root ` user. - - Replace this value with a unique, random, and long string. - - * - :envvar:`MINIO_KMS_SECRET_KEY_FILE ` - - 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: - - ``:`` - - - Replace the ```` with any string. You must use this - key name if you later migrate to using a dedicated KMS for - managing encryption keys. - - - Replace ```` with a 32-bit base64 encoded value. - For example: - - .. code-block:: shell - :class: copyable - - cat /dev/urandom | head -c 32 | base64 - - - * - ``-v /mnt/disk:/disk`` - - 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 `: - - .. 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 ` 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 ` 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: - - ``:`` - - - Replace the ```` with any string. You must use this - key name if you later migrate to using a dedicated KMS for - managing encryption keys. - - - Replace ```` 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 `__. - -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 `__ you can -install using `pkg `__: - -.. code-block:: shell - :class: copyable - - pkg install minio - sysrc minio_enable=yes - sysrc minio_disks=/path/to/disks - service minio start