minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

Final pass on platformization (#555)

Browse Source
This commit is contained in:
Ravind Kumar
2022-09-16 16:40:20 -04:00
committed by GitHub
parent 5efcffbff1
commit d815aa9ce8
144 changed files with 1510 additions and 1102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
source/operations/checklists/hardware.rst
View File

@ -21,10 +21,13 @@ When selecting hardware for your MinIO implementation, take into account the fol
- Average retention time of data in years
- Number of sites to be deployed
Hardware Requirements
---------------------
.. _deploy-minio-distributed-recommendations:
The following checklist provides a minimum hardware specification for production MinIO deployments.
Production Hardware Requirements
--------------------------------
The following checklist provides a minimum hardware specification for production MinIO deployments.
MinIO takes full advantage of the modern hardware improvements such as AVX-512 SIMD acceleration, 100GbE networking, and NVMe SSDs, when available.
While MinIO can run on commodity or "budget" hardware, we strongly recommend using this table as guidance for best results in production environments.
.. note::
@ -38,47 +41,222 @@ While MinIO can run on commodity or "budget" hardware, we strongly recommend usi
:width: 100%
* - :octicon:`circle`
- | Sufficient CPU cores to achieve performance goals for hashing (for example, for healing) and encryption
| MinIO recommends Dual Intel® Xeon® Scalable Gold CPUs (minimum 8 cores per socket) or any CPU with AVX512 instructions
- Sufficient CPU cores to achieve performance goals for hashing (for example, for healing) and encryption
MinIO recommends Dual Intel® Xeon® Scalable Gold CPUs (minimum 8 cores per socket) or any CPU with AVX512 instructions
* - :octicon:`circle`
- | Sufficient RAM to achieve performance goals based on the number of drives and anticipated concurrent requests (see the :ref:`formula and reference table <minio-requests-per-node>`)
| Refer to the information on :ref:`memory allocation <minio-k8s-production-considerations-memory>` for recommended RAM amounts
- Sufficient RAM to achieve performance goals based on the number of drives and anticipated concurrent requests (see the :ref:`formula and reference table <minio-hardware-checklist-memory>`).
MinIO recommends a minimum of 128GB of memory per node for best performance.
* - :octicon:`circle`
- | Four nodes or servers
| For containers or Kubernetes in virtualized environments, MinIO requires four distinct physical nodes.
- Minimum of four nodes dedicated to object storage.
For containers or Kubernetes in virtualized environments, MinIO requires four distinct physical nodes.
Colocating multiple high-performance softwares on the same nodes can result in resource contention and reduced overall performance.
* - :octicon:`circle`
- | SATA/SAS drives for capacity and NVMe SSDs for high-performance
| MinIO recommends a minimum of 8 drives per server
- | SATA/SAS drives for balanced capacity-to-performance
| NVMe SSDs for high-performance.
| MinIO recommends a minimum of 8 drives per server.
Use the same type of drive (NVMe, SSD, or HDD) with the same capacity across all nodes in the deployment.
* - :octicon:`circle`
- | 25GbE network for capacity
| 100GbE Network interface cards for high performance
- | 25GbE Network as a baseline
| 100GbE Network for high performance
.. important::
The following areas have the greatest impact on MinIO performance, listed in order of importance:
- Network infrastructure (insufficient or limited throughput)
- Storage controller (old firmware; limited throughput)
- Storage (old firmware; slow, aged, or failing drives)
.. list-table::
:stub-columns: 1
:widths: auto
:width: 100%
Prioritize upgrading these areas before focusing on compute-related performance constraints.
* - Network Infrastructure
- Insufficient or limited throughput constrains performance
* - Storage Controller
- Old firmware, limited throughput, or failing hardware constrains performance and affects reliability
* - Storage (Drive)
- Old firmware, or slow/aging/failing hardware constrains performance and affects reliability
Prioritize securing the necessary components for each of these areas before focusing on other hardware resources, such as compute-related constraints.
Minimum Nodes per Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: k8s
MinIO requires a *minimum* of 4 worker nodes per MinIO Tenant with 4 drives per node.
Each drive must consist of a Persistent Volume associated to a storage resource.
.. cond:: linux or container or macos or windows
MinIO recommends a *minimum* of 4 host servers per deployment with 4 locally attached drives per server.
The "4x4" topology provides a baseline of performance with tolerance for the loss of up to 4 drives *or* one node while maintaining read and write operations.
You can increase the :ref:`erasure code parity <minio-erasure-coding>` of the deployment to improve resiliency at the cost of available storage.
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.
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 a general guideline for the maximum storage throughput supported by a given physical or virtual network interface.
This table assumes all network infrastructure components, such as routers, switches, and physical cabling, also supports the NIC bandwidth.
.. list-table::
:widths: auto
:width: 100%
* - NIC Bandwidth (Gbps)
- Estimated Aggregated Storage Throughput (GBps)
* - 10GbE
- 1.25GBps
* - 25GbE
- 3.125GBps
* - 50GbE
- 6.25GBps
* - 100GbE
- 12.5GBps
Networking has the greatest impact on MinIO performance, where low per-host bandwidth artificially constrains the potential performance of the storage.
The following examples of network throughput constraints assume spinning disks with ~100MB/S sustained I/O
- 1GbE network link can support up to 125MB/s, or one spinning disk
- 10GbE network can support approximately 1.25GB/s, potentially supporting 10-12 spinning disk
- 25GbE network can support approximately 3.125GB/s, potentially supporting ~30 disks
The recommended minimum MinIO cluster of 4 nodes with 4 drives each (16 total disks) requires a 25GbE network to support the total potential aggregate throughput.
.. _minio-hardware-checklist-memory:
Memory
~~~~~~
Memory primarily constrains the number of concurrent simultaneous connections per node.
You can calculate the maximum number of concurrent requests per node with this formula:
:math:`totalRam / ramPerRequest`
To calculate the amount of RAM used for each request, use this formula:
:math:`((2MiB + 128KiB) * driveCount) + (2 * 10MiB) + (2 * 1 MiB)`
10MiB is the default erasure block size v1.
1 MiB is the default erasure block size v2.
The following table lists the maximum concurrent requests on a node based on the number of host drives and the *free* system RAM:
.. list-table::
:header-rows: 1
:width: 100%
* - Number of Drives
- 32 GiB of RAM
- 64 GiB of RAM
- 128 GiB of RAM
- 256 GiB of RAM
- 512 GiB of RAM
* - 4 Drives
- 1,074
- 2,149
- 4,297
- 8,595
- 17,190
* - 8 Drives
- 840
- 1,680
- 3,361
- 6,722
- 13,443
* - 16 Drives
- 585
- 1,170
- 2.341
- 4,681
- 9,362
The following table provides general guidelines for allocating memory for use by MinIO based on the total amount of local storage on the node:
.. 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
For example:
* - Up to 1 Pebibyte (Pi)
- 64GiB
The following examples of network throughput constraints assume spinning disks with ~100MB/S sustained I/O
* - More than 1 Pebibyte (Pi)
- 128GiB
- 1GbE network link can support up to 125MB/s, or one spinning disk
- 10GbE network can support approximately 1.25GB/s, potentially supporting 10-12 spinning disk
- 25GbE network can support approximately 3.125GB/s, potentially supporting ~30 disks
Storage
~~~~~~~
The recommended minimum MinIO cluster of 4 nodes with 4 drives each (16 total disks) requires a 25GbE network to support the total potential aggregate throughput.
For best performance, have a minimum of eight drives per node.
MinIO recommends selecting the type of drive based on your performance objectives.
The following table highlights the general use case for each drive type based on cost and performance:
MinIO takes full advantage of the modern hardware improvements such as AVX-512 SIMD acceleration, 100GbE networking, and NVMe SSDs, when available.
NVMe/SSD - Hot Tier
HDD - Warm
.. list-table::
:header-rows: 1
:widths: auto
:width: 100%
* - Type
- Cost
- Performance
- Tier
* - NVMe
- High
- High
- Hot
* - SSD
- Balanced
- Balanced
- Hot/Warm
* - HDD
- Low
- Low
- Cold/Archival
Use the same type of disk (NVME, SSD, HDD) with the same capacity across all nodes in a MinIO deployment.
MinIO does not distinguish drive types when using the underlying storage and does not benefit from mixed storage types.
Use the same capacity of disk across all nodes in the MinIO :ref:`server pool <minio-intro-server-pool>`.
MinIO limits the maximum usable size per disk to the smallest size in the deployment.
For example, if a deployment has 15 10TB disks and 1 1TB disk, MinIO limits the per-disk capacity to 1TB.
Recommended Hardware Tests
--------------------------
@ -94,7 +272,7 @@ If you have access to :ref:`SUBNET <minio-docs-subnet>`, you can upload the resu
mc support diag ALIAS --airgap
Replace ALIAS with the :mc-cmd:`~mc alias` defined for the deployment.
Replace ALIAS with the :mc:`~mc alias` defined for the deployment.
MinIO Support Diagnostic Tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

14
source/operations/checklists/software.rst
View File

@ -40,7 +40,19 @@ MinIO Pre-requisites
MinIO Install
-------------
See the :ref:`Multi Node Multi Drive deployment guide <deploy-minio-distributed>` and the :ref:`Minio Tenant deployment guide <minio-k8s-deploy-minio-tenant>`.
Install the MinIO server binary across all nodes, ensuring that each node uses the same version of that binary.
.. cond:: linux
See the :ref:`Multi Node Multi Drive deployment guide <minio-mnmd>` for more information.
.. cond:: container or macos or windows
See the :ref:`Single Node Single Drive deployment guide <minio-snsd>` for more information.
.. cond:: k8s
See the :ref:`Deploy MinIO Operator <minio-operator-installation>` and :ref:`Minio Tenant deployment guide <minio-k8s-deploy-minio-tenant>` for more information.
Post Install Tasks

33
source/operations/concepts.rst
View File

@ -30,13 +30,20 @@ MinIO can deploy to three types of topologies:
#. :ref:`Single Node Single Drive <minio-snsd>`, one MinIO server with a single drive or folder for data
For example, testing on a local PC using a folder on the computer's hard drive.
#. :ref:`Single Node Multi Drive <minio-snmd>`, one MinIO server with multiple mounted drives or folders for data
For example, a single container with two or more mounted volumes.
#. :ref:`Multi Node Multi Drive <minio-mnmd>`, multiple MinIO servers with multiple mounted drives or volumes for data
For example, a production deployment using Kubernetes to manage and deploy pods with multiple persistent volume claims.
.. cond:: linux
For example, a production deployment using Ansible, Terraform, or manual processes
.. cond:: k8s
For example, a production deployment using Kubernetes to manage and deploy pods and their associated persistent volume claims.
How does a distributed MinIO deployment work?
---------------------------------------------
@ -93,23 +100,29 @@ MinIO strongly recommends production clusters consist of a *minimum* of 4 :mc:`m
Can I change the size of an existing MinIO deployment?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can move objects from an existing server pool on to other server pools on the deployment to reduce the size of a deployment by decommissioning a server pool.
Likewise, you can add on a new server pool to an existing deployment to expand the total size of a deployment with a horizontal expansion.
MinIO :ref:`distributed deployments <minio-mnmd>` support expansion and decommissioning as functions to increase or decrease the available storage.
When the time comes to retire or replace a server pool, :ref:`decommissioning <minio-decommissioning>` is the process of draining the objects of a pool to other active pools on the deployment.
MinIO rewrites objects from the decommissioned pool and does not allow additional writes to the pool while it is in decommissioning.
Expansion consists of adding one or more :ref:`server pools <minio-intro-server-pool>` to an existing deployment.
Each server pool consists of dedicated nodes and storage that contribute to the overall capacity of the deployment.
.. cond:: linux
See :ref:`Expand a MinIO deployment <expand-minio-distributed>` for more information
.. cond:: k8s
See :ref:`Expand a MinIO Tenant <minio-k8s-expand-minio-tenant>` for more information.
For deployments which have multiple server pools, you can :ref:`decommission <minio-decommissioning>` the older pools and migrate that data to the newer pools in the deployment.
Once started, decommissioning cannot be stopped.
In a distributed MinIO deployment, you can upgrade the total available size of a :ref:`deployment <expand-minio-distributed>` or :ref:`cluster <minio-k8s-expand-minio-tenant>` by adding one or more additional server pools.
The addition of a server pool is an expansion.
MinIO intends decommissioning for use with removing older pools with aged hardware, and not as an operation performed regularly within any deployment.
How do I manage one or more MinIO instances or clusters?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several options to manage your MinIO deployments and clusters:
- Use the command line with :mc-cmd:`mc` and :mc-cmd:`mc admin`
- Use the command line with :mc:`mc` and :mc:`mc admin`
- The :ref:`MinIO Console <minio-console>` graphical user interface for individual instances
- In Kubernetes, with the :ref:`MinIO Operator Console <minio-operator-console>`

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

@ -103,12 +103,12 @@ The command should result in remounting of all of the replaced drives.
5) Monitor MinIO for Drive Detection and Healing Status
-------------------------------------------------------
Use :mc-cmd:`mc admin console` command *or* ``journalctl -u minio`` for
Use :mc:`mc admin console` command *or* ``journalctl -u minio`` for
``systemd``-managed installations to monitor the server log output after
remounting drives. The output should include messages identifying each formatted
and empty drive.
Use :mc-cmd:`mc admin heal` to monitor the overall healing status on the
Use :mc:`mc admin heal` to monitor the overall healing status on the
deployment. MinIO aggressively heals replaced drive(s) to ensure rapid recovery
from the degraded state.

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

@ -70,13 +70,13 @@ in the deployment.
------------------------------------
Start the MinIO server process on the node and monitor the process output
using :mc-cmd:`mc admin console` or by monitoring the MinIO service logs
using :mc:`mc admin console` or by monitoring the MinIO service logs
using ``journalctl -u minio`` for ``systemd`` managed installations.
The server output should indicate that it has detected the other nodes
in the deployment and begun healing operations.
Use :mc-cmd:`mc admin heal` to monitor overall healing status on the
Use :mc:`mc admin heal` to monitor overall healing status on the
deployment. MinIO aggressively heals the node to ensure rapid recovery
from the degraded state.

228
source/operations/external-iam.rst
View File

@ -15,68 +15,45 @@ MinIO supports offloading identity management onto one of the following supporte
- :ref:`OpenID Connect <minio-external-iam-oidc>`
- :ref:`Active Directory / LDAP <minio-external-iam-ad-ldap>`
.. admonition:: MinIO Supports At Most One Configured IDentity Provider
:class: important
Configuring an external IDP disables the :ref:`MinIO internal IDP
<minio-internal-idp>` and prevents the configuration of any other
external IDP.
The external :abbr:`IDP (IDentity Provider)` must have *at least* one
configured user identity with the required :ref:`policy claims
<minio-external-identity-management-ad-ldap-access-control>`. If no such user
exists, the MinIO server is effectively inaccessible outside of using the
:ref:`root <minio-users-root>` user.
The external :abbr:`IDP (IDentity Provider)` must have *at least* one configured user identity with the required :ref:`policy claims <minio-external-identity-management-ad-ldap-access-control>`.
If no such user exists, the MinIO server is effectively inaccessible outside of using the :ref:`root <minio-users-root>` user.
.. _minio-external-iam-oidc:
OpenID Connect (OIDC)
---------------------
MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP)
such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user
identities. Configuring an external :abbr:`IDP (IDentity Provider)` enables
Single-Sign On workflows, where applications authenticate against the external
:abbr:`IDP (IDentity Provider)` before accessing MinIO.
MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP) such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user identities.
Configuring an external :abbr:`IDP (IDentity Provider)` enables Single-Sign On workflows, where applications authenticate against the external :abbr:`IDP (IDentity Provider)` before accessing MinIO.
MinIO uses :ref:`Policy Based Access Control (PBAC) <minio-access-management>`
to define the actions and resources to which an authenticated user has access.
MinIO supports creating and managing :ref:`policies <minio-policy>` which an
externally managed user can claim.
MinIO uses :ref:`Policy Based Access Control (PBAC) <minio-access-management>` to define the actions and resources to which an authenticated user has access.
MinIO supports creating and managing :ref:`policies <minio-policy>` which an externally managed user can claim.
For identities managed by the external OpenID Connect (OIDC) compatible
provider, MinIO uses a `JSON Web Token claim
<https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ to identify the
:ref:`policy <minio-policy>` to assign to the authenticated user.
For identities managed by the external OpenID Connect (OIDC) compatible provider, MinIO uses a `JSON Web Token claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ to identify the :ref:`policy <minio-policy>` to assign to the authenticated user.
See :ref:`minio-external-identity-management-openid-access-control` for more information on mapping MinIO policies to an OIDC-managed identity.
MinIO by default looks for a ``policy`` claim and reads a list of one or more
policies to assign. MinIO attempts to match existing policies to those
specified in the JWT claim. If none of the specified policies exist on the MinIO
deployment, MinIO denies authorization for any and all operations issued
by that user. For example, consider a claim with the following key-value
assignment:
MinIO by default looks for a ``policy`` claim and reads a list of one or more policies to assign. MinIO attempts to match existing policies to those specified in the JWT claim.
If none of the specified policies exist on the MinIO deployment, MinIO denies authorization for any and all operations issued by that user.
For example, consider a claim with the following key-value assignment:
.. code-block:: shell
policy="readwrite_data,read_analytics,read_logs"
The specified policy claim directs MinIO to attach the policies with names
matching ``readwrite_data``, ``read_analytics``, and ``read_logs`` to the
authenticated user.
The specified policy claim directs MinIO to attach the policies with names matching ``readwrite_data``, ``read_analytics``, and ``read_logs`` to the authenticated user.
You can set a custom policy claim using the
:envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable
*or* by using :mc-cmd:`mc admin config set` to set the
:mc-conf:`identity_openid claim_name <identity_openid.claim_name>` setting.
.. cond:: linux or container or macos or windows
You can use a `JWT Debugging tool <https://jwt.io/>`__ to decode the returned
JWT token and validate that the user attributes include the specified claim. See
`RFC 7519: JWT Claim
<https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ for more
information on JWT claims. Defer to the documentation for your preferred OIDC
provider for instructions on configuring user claims.
You can set a custom policy claim using the
:envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable
*or* by using :mc-cmd:`mc admin config set` to set the
:mc-conf:`identity_openid claim_name <identity_openid.claim_name>` setting.
See :ref:`minio-external-identity-management-openid-access-control` for more information on mapping MinIO policies to an OIDC-managed identity.
You can use a `JWT Debugging tool <https://jwt.io/>`__ to decode the returned JWT token and validate that the user attributes include the specified claim.
See `RFC 7519: JWT Claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ for more information on JWT claims.
Defer to the documentation for your preferred OIDC provider for instructions on configuring user claims.
.. _minio-external-iam-ad-ldap:
@ -111,38 +88,38 @@ for backwards compatibility only.
Lookup-Bind Mode
++++++++++++++++
In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum
privileges required to authenticate to the AD/LDAP server and perform user and
group lookups.
In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum privileges required to authenticate to the AD/LDAP server and perform user and group lookups.
The following tabs provide a reference of the environment variables and
configuration settings required for enabling Lookup-Bind mode.
.. cond:: linux or container or macos or windows
.. tab-set::
The following tabs provide a reference of the environment variables and
configuration settings required for enabling Lookup-Bind mode.
.. tab-item:: Environment Variable
.. tab-set::
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER`
.. tab-item:: Environment Variable
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on these variables. The
:ref:`minio-authenticate-using-openid-generic` tutorial includes complete
instructions on setting these values.
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER`
.. tab-item:: Configuration Setting
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on these variables. The
:ref:`minio-authenticate-using-openid-generic` tutorial includes complete
instructions on setting these values.
- :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
- :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
- :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
- :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
.. tab-item:: Configuration Setting
See the :mc-conf:`identity_ldap` reference documentation for more
information on these settings. The
:ref:`minio-authenticate-using-openid-generic` tutorial includes complete
instructions on setting these variables.
- :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
- :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
- :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
- :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
See the :mc-conf:`identity_ldap` reference documentation for more
information on these settings. The
:ref:`minio-authenticate-using-openid-generic` tutorial includes complete
instructions on setting these variables.
Lookup-Bind is incompatible and mutually exclusive with
:ref:`minio-external-identity-management-ad-ldap-username-bind`.
@ -152,31 +129,36 @@ Lookup-Bind is incompatible and mutually exclusive with
Username-Bind Mode
++++++++++++++++++
In Username-Bind mode, MinIO uses the AD/LDAP credentials provided by the client
attempting authentication to login to the AD/LDAP server and perform and group
lookups.
In Username-Bind mode, MinIO uses the AD/LDAP credentials provided by the client attempting authentication to login to the AD/LDAP server and perform and group lookups.
Username-Bind mode is preserved for compatibility only. MinIO recommends
using :ref:`minio-external-identity-management-ad-ldap-lookup-bind` wherever possible.
.. cond:: k8s
The following tabs provide a reference of the environment variables and
configuration settings required for enabling Username-Bind mode.
The MinIO Operator Console does not support enabling Username-Bind mode.
MinIO generally discourages using Username-Bind over :ref:`minio-external-identity-management-ad-ldap-lookup-bind`.
.. tab-set::
.. tab-item:: Environment Variable
.. cond:: linux or container or macos or windows
- :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT`
Username-Bind mode is preserved for compatibility only.
MinIO recommends using :ref:`minio-external-identity-management-ad-ldap-lookup-bind` wherever possible.
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on this variable.
The following tabs provide a reference of the environment variables and
configuration settings required for enabling Username-Bind mode.
.. tab-item:: Configuration Setting
.. tab-set::
.. tab-item:: Environment Variable
- :mc-conf:`identity_ldap username_format <identity_ldap.username_format>`
- :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT`
See the :mc-conf:`identity_ldap` reference documentation for more
information on this setting.
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on this variable.
.. tab-item:: Configuration Setting
- :mc-conf:`identity_ldap username_format <identity_ldap.username_format>`
See the :mc-conf:`identity_ldap` reference documentation for more
information on this setting.
Username-bind is incompatible and mutually exclusive with
:ref:`minio-external-identity-management-ad-ldap-lookup-bind`.
@ -186,65 +168,63 @@ Username-bind is incompatible and mutually exclusive with
Access Control for AD/LDAP-Managed Identities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO uses :ref:`Policy Based Access Control (PBAC) <minio-access-management>`
to define the actions and resources to which an authenticated user has access.
When using an Active Directory/LDAP server for identity management
(authentication), MinIO maintains control over access (authorization)
through PBAC.
MinIO uses :ref:`Policy Based Access Control (PBAC) <minio-access-management>` to define the actions and resources to which an authenticated user has access.
When using an Active Directory/LDAP server for identity management (authentication), MinIO maintains control over access (authorization) through PBAC.
When a user successfully authenticates to MinIO using their AD/LDAP
credentials, MinIO searches for all :ref:`policies <minio-policy>` which
are explicitly associated to that user's Distinguished Name (DN).
Specifically, the policy must be assigned to a user with a matching DN
using the :mc-cmd:`mc admin policy set` command.
When a user successfully authenticates to MinIO using their AD/LDAP credentials, MinIO searches for all :ref:`policies <minio-policy>` which are explicitly associated to that user's Distinguished Name (DN).
Specifically, the policy must be assigned to a user with a matching DN using the :mc-cmd:`mc admin policy set` command.
MinIO also supports querying for the user's AD/LDAP group membership. MinIO
attempts to match existing policies to the DN for each of the user's groups. The
authenticated users complete set of permissions consists of its explicitly
assigned and group-inherited policies. See
:ref:`minio-external-identity-management-ad-ldap-access-control-group-lookup`
for more information.
MinIO also supports querying for the user's AD/LDAP group membership.
MinIO attempts to match existing policies to the DN for each of the user's groups.
The authenticated users complete set of permissions consists of its explicitly assigned and group-inherited policies.
See :ref:`minio-external-identity-management-ad-ldap-access-control-group-lookup` for more information.
MinIO uses deny-by-default behavior where a user with no explicitly assigned or
group-inherited policies cannot access any resource on the MinIO deployment.
MinIO uses deny-by-default behavior where a user with no explicitly assigned or group-inherited policies cannot access any resource on the MinIO deployment.
MinIO provides :ref:`built-in policies <minio-policy-built-in>` for basic access
control. You can create new policies using the :mc:`mc admin policy` command.
MinIO provides :ref:`built-in policies <minio-policy-built-in>` for basic access control.
You can create new policies using the :mc:`mc admin policy` command.
.. _minio-external-identity-management-ad-ldap-access-control-group-lookup:
Group Lookup
++++++++++++
MinIO supports querying the Active Directory / LDAP server for a list of groups in which the authenticated user has membership. MinIO attempts to match existing :ref:`policies <minio-policy>` to each group DN and assigns each matching policy to the authenticated user.
MinIO supports querying the Active Directory / LDAP server for a list of groups in which the authenticated user has membership.
MinIO attempts to match existing :ref:`policies <minio-policy>` to each group DN and assigns each matching policy to the authenticated user.
The following tabs provide a reference of the environment variables and
configuration settings required for enabling group lookups:
.. cond:: k8s
.. tab-set::
The MinIO Operator Console provides the necessary fields for configuring Group Lookup as part of configuring AD/LDAP identity management for new or existing MinIO Tenants.
.. tab-item:: Environment Variable
.. cond:: linux or container or macos or windows
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER`
The following tabs provide a reference of the environment variables and configuration settings required for enabling group lookups:
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on these variables. The
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
instructions on setting these values.
.. tab-set::
.. tab-item:: Configuration Setting
.. tab-item:: Environment Variable
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER`
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
reference documentation for more information on these variables. The
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
instructions on setting these values.
.. tab-item:: Configuration Setting
- :mc-conf:`identity_ldap group_search_base_dn <identity_ldap.group_search_base_dn>`
- :mc-conf:`identity_ldap group_search_filter <identity_ldap.group_search_filter>`
- :mc-conf:`identity_ldap group_search_base_dn <identity_ldap.group_search_base_dn>`
- :mc-conf:`identity_ldap group_search_filter <identity_ldap.group_search_filter>`
See the :mc-conf:`identity_ldap` reference documentation for more
information on these settings. The
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
instructions on setting these variables.
See the :mc-conf:`identity_ldap` reference documentation for more
information on these settings. The
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
instructions on setting these variables.
.. toctree::
:glob:
:hidden:
/operations/external-iam/*

350
source/operations/external-iam/configure-ad-ldap-external-identity-management.rst
View File

@ -13,217 +13,255 @@ Configure MinIO for Authentication using Active Directory / LDAP
Overview
--------
MinIO supports using an Active Directory / LDAP Connect for external management of user
identities. The procedure on this page provides instructions for:
MinIO supports using an Active Directory / LDAP Connect for external management of user identities.
The procedure on this page provides instructions for:
- Configuring a MinIO cluster for an external AD/LDAP provider.
- Logging into the cluster using the MinIO Console and AD/LDAP credentials.
- Using the MinIO ``AssumeRoleWithLDAPIdentity`` Security Token Service (STS)
API to generate temporary credentials for use by applications.
.. cond:: k8s
This procedure is generic for AD/LDAP services. Defer to the documentation for
the AD/LDAP provider of your choice for specific instructions or procedures on
configuration of user identities.
- Configuring a MinIO Tenant to use an external AD/LDAP provider
- Accessing the Tenant Console using AD/LDAP Credentials.
- Using the MinIO ``AssumeRoleWithLDAPIdentity`` Security Token Service (STS) API to generate temporary credentials for use by applications.
.. cond:: linux or macos or container or windows
- Configuring a MinIO cluster for an external AD/LDAP provider.
- Accessing the MinIO Console using AD/LDAP credentials.
- Using the MinIO ``AssumeRoleWithLDAPIdentity`` Security Token Service (STS) API to generate temporary credentials for use by applications.
This procedure is generic for AD/LDAP services. Defer to the documentation for the AD/LDAP provider of your choice for specific instructions or procedures on configuration of user identities.
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-operator.rst
:start-after: start-requires-operator-plugin
:end-before: end-requires-operator-plugin
Active Directory / LDAP Compatible IDentity Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure assumes an existing Active Directory or LDAP service.
Instructions on configuring AD/LDAP are out of scope for this procedure.
MinIO requires a read-only service account with which it
:ref:`binds <minio-external-identity-management-ad-ldap-lookup-bind>` to perform
authenticated user and group queries.
.. cond:: k8s
Ensure each AD/LDAP user and group intended for use with MinIO has a
corresponding :ref:`policy
<minio-external-identity-management-ad-ldap-access-control>` on the MinIO
deployment. An AD/LDAP user with no assigned policy *and* with membership in
groups with no assigned policy has no permission to access any action or
resource on the MinIO cluster.
- For AD/LDAP deployments within the same Kubernetes cluster as the MinIO Tenant, you can use Kubernetes service names to allow the MinIO Tenant to establish connectivity to the AD/LDAP service.
MinIO Cluster
~~~~~~~~~~~~~
- For AD/LDAP deployments external to the Kubernetes cluster, you must ensure the cluster supports routing communications between Kubernetes services and pods and the external network.
This may require configuration or deployment of additional Kubernetes network components and/or enabling access to the public internet.
This procedure assumes an existing MinIO cluster running the
:minio-git:`latest stable MinIO version <minio/releases/latest>`.
This procedure *may* work as expected for older versions of MinIO.
MinIO requires a read-only service account with which it :ref:`binds <minio-external-identity-management-ad-ldap-lookup-bind>` to perform authenticated user and group queries.
Install and Configure ``mc`` with Access to the MinIO Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ensure each AD/LDAP user and group intended for use with MinIO has a corresponding :ref:`policy <minio-external-identity-management-ad-ldap-access-control>` on the MinIO deployment.
An AD/LDAP user with no assigned policy *and* with membership in groups with no assigned policy has no permission to access any action or resource on the MinIO cluster.
This procedure uses :mc:`mc` for performing operations on the
MinIO cluster. Install ``mc`` on a machine with network access to the cluster.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on
downloading and installing ``mc``.
.. cond:: k8s
This procedure assumes a configured :mc:`alias <mc alias>` for the MinIO
cluster.
MinIO Tenant
~~~~~~~~~~~~
.. _minio-external-identity-management-ad-ldap-configure:
This procedure assumes your Kubernetes cluster has sufficient resources to :ref:`deploy a new MinIO Tenant <minio-k8s-deploy-minio-tenant>`.
Procedure
---------
You can also use this procedure as guidance for modifying an existing MinIO Tenant to enable AD/LDAP Identity Management.
1) Set the Active Directory / LDAP Configuration Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: linux or container or macos or windows
You can configure the AD/LDAP provider using either
environment variables *or* server runtime configuration settings. Both
methods require starting/restarting the MinIO deployment to apply changes. The
following tabs provide a quick reference of all required and optional
environment variables and configuration settings respectively:
MinIO Deployment
~~~~~~~~~~~~~~~~
.. tab-set::
This procedure assumes an existing MinIO cluster running the :minio-git:`latest stable MinIO version <minio/releases/latest>`.
Defer to the :ref:`minio-installation` for more complete documentation on new MinIO deployments.
.. tab-item:: Environment Variables
This procedure *may* work as expected for older versions of MinIO.
MinIO supports specifying the AD/LDAP provider
settings using :ref:`environment variables
<minio-server-envvar-external-identity-management-ad-ldap>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, specify these settings across all
nodes in the deployment using the *same* values consistently.
.. cond:: linux or container or macos or windows
The following example code sets *all* environment variables related to
configuring an AD/LDAP provider for external
identity management. The minimum *required* variable are:
- :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER`
Install and Configure ``mc`` with Access to the MinIO Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
This procedure uses :mc:`mc` for performing operations on the MinIO cluster.
Install ``mc`` on a machine with network access to the cluster.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
export MINIO_IDENTITY_LDAP_SERVER_ADDR="ldaps.example.net:636"
export MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN="dc=example,dc=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER="(&(objectCategory=user)(sAMAccountName=%s))"
export MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD="xxxxxxxxx"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER="(&(objectClass=group)(member=%d))"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN="ou=MinIO Users,dc=example,dc=net"
This procedure assumes a configured :mc:`alias <mc alias>` for the MinIO cluster.
For complete documentation on these variables, see
:ref:`minio-server-envvar-external-identity-management-ad-ldap`
.. Lightly modeled after the SSE tutorials
.. tab-item:: Configuration Settings
.. cond:: k8s
MinIO supports specifying the AD/LDAP provider
settings using :mc-conf:`configuration settings <identity_ldap>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, the :mc-cmd:`mc admin config`
command applies the configuration to all nodes in the deployment.
.. _minio-external-identity-management-ad-ldap-configure:
The following example code sets *all* configuration settings related to
configuring an AD/LDAP provider for external
identity management. The minimum *required* setting are:
- :mc-conf:`identity_ldap server_addr <identity_ldap.server_addr>`
.. include:: /includes/k8s/steps-configure-ad-ldap-external-identity-management.rst
- :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
- :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
- :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
- :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
.. Doing this the quick and dirty way. Need to revise later to be proper full includes via stepfiles
.. code-block:: shell
:class: copyable
.. cond:: linux or container or macos or windows
mc admin config set ALIAS/ identity_ldap \
server_addr="ldaps.example.net:636" \
lookup_bind_dn="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net" \
lookup_bind_password="xxxxxxxx" \
user_dn_search_base_dn="DC=example,DC=net" \
user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))" \
group_search_filter= "(&(objectClass=group)(member=%d))" \
group_search_base_dn="ou=MinIO Users,dc=example,dc=net"
.. _minio-external-identity-management-ad-ldap-configure:
For more complete documentation on these settings, see
:mc-conf:`identity_ldap`.
Procedure
---------
2) Restart the MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Set the Active Directory / LDAP Configuration Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must restart the MinIO deployment to apply the configuration changes.
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
You can configure the AD/LDAP provider using either
environment variables *or* server runtime configuration settings. Both
methods require starting/restarting the MinIO deployment to apply changes. The
following tabs provide a quick reference of all required and optional
environment variables and configuration settings respectively:
.. code-block:: shell
:class: copyable
.. tab-set::
mc admin service restart ALIAS
.. tab-item:: Environment Variables
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
MinIO supports specifying the AD/LDAP provider
settings using :ref:`environment variables
<minio-server-envvar-external-identity-management-ad-ldap>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, specify these settings across all
nodes in the deployment using the *same* values consistently.
3) Use the MinIO Console to Log In with AD/LDAP Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example code sets *all* environment variables related to
configuring an AD/LDAP provider for external
identity management. The minimum *required* variable are:
- :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN`
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER`
The MinIO Console supports the full workflow of authenticating to the
AD/LDAP provider, generating temporary credentials using
the MinIO :ref:`minio-sts-assumerolewithldapidentity` Security Token Service
(STS) endpoint, and logging the user into the MinIO deployment.
.. code-block:: shell
:class: copyable
Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is
embedded in the MinIO server. You can access the Console by opening the root URL
for the MinIO cluster. For example, ``https://minio.example.net:9000``.
export MINIO_IDENTITY_LDAP_SERVER_ADDR="ldaps.example.net:636"
export MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN="dc=example,dc=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER="(&(objectCategory=user)(sAMAccountName=%s))"
export MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD="xxxxxxxxx"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER="(&(objectClass=group)(member=%d))"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN="ou=MinIO Users,dc=example,dc=net"
From the Console, click :guilabel:`BUTTON` to begin the Active Directory / LDAP
authentication flow.
For complete documentation on these variables, see
:ref:`minio-server-envvar-external-identity-management-ad-ldap`
Once logged in, you can perform any action for which the authenticated
user is :ref:`authorized
<minio-external-identity-management-ad-ldap-access-control>`.
.. tab-item:: Configuration Settings
You can also create :ref:`service accounts <minio-idp-service-account>` for
supporting applications which must perform operations on MinIO. Service accounts
are long-lived credentials which inherit their privileges from the parent user.
The parent user can further restrict those privileges while creating the service
account.
MinIO supports specifying the AD/LDAP provider
settings using :mc-conf:`configuration settings <identity_ldap>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, the :mc:`mc admin config`
command applies the configuration to all nodes in the deployment.
4) Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example code sets *all* configuration settings related to
configuring an AD/LDAP provider for external
identity management. The minimum *required* setting are:
- :mc-conf:`identity_ldap server_addr <identity_ldap.server_addr>`
MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
- :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
Applications can generate temporary access credentials as-needed using the
:ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API
endpoint and AD/LDAP user credentials. MinIO provides an example Go application
:minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` with an example of
managing this workflow.
- :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
- :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
- :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
.. code-block:: shell
.. code-block:: shell
:class: copyable
POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&Policy={}
mc admin config set ALIAS/ identity_ldap \
server_addr="ldaps.example.net:636" \
lookup_bind_dn="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net" \
lookup_bind_password="xxxxxxxx" \
user_dn_search_base_dn="DC=example,DC=net" \
user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))" \
group_search_filter= "(&(objectClass=group)(member=%d))" \
group_search_base_dn="ou=MinIO Users,dc=example,dc=net"
- Replace the ``LDAPUsername`` with the username of the AD/LDAP user.
For more complete documentation on these settings, see
:mc-conf:`identity_ldap`.
- Replace the ``LDAPPassword`` with the password of the AD/LDAP user.
2) Restart the MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Replace the ``Policy`` with an inline URL-encoded JSON
:ref:`policy <minio-policy>` that further restricts the permissions associated
to the temporary credentials. Omit to use the
:ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>`
the Distinguished Name (DN) of the AD/LDAP user.
You must restart the MinIO deployment to apply the configuration changes.
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
The API response consists of an XML document containing the
access key, secret key, session token, and expiration date. Applications
can use the access key and secret key to access and perform operations on
MinIO.
.. code-block:: shell
:class: copyable
See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation.
mc admin service restart ALIAS
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
3) Use the MinIO Console to Log In with AD/LDAP Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The MinIO Console supports the full workflow of authenticating to the
AD/LDAP provider, generating temporary credentials using
the MinIO :ref:`minio-sts-assumerolewithldapidentity` Security Token Service
(STS) endpoint, and logging the user into the MinIO deployment.
Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is
embedded in the MinIO server. You can access the Console by opening the root URL
for the MinIO cluster. For example, ``https://minio.example.net:9000``.
From the Console, click :guilabel:`BUTTON` to begin the Active Directory / LDAP
authentication flow.
Once logged in, you can perform any action for which the authenticated
user is :ref:`authorized
<minio-external-identity-management-ad-ldap-access-control>`.
You can also create :ref:`service accounts <minio-idp-service-account>` for
supporting applications which must perform operations on MinIO. Service accounts
are long-lived credentials which inherit their privileges from the parent user.
The parent user can further restrict those privileges while creating the service
account.
4) Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
Applications can generate temporary access credentials as-needed using the
:ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API
endpoint and AD/LDAP user credentials. MinIO provides an example Go application
:minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` with an example of
managing this workflow.
.. code-block:: shell
POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&Policy={}
- Replace the ``LDAPUsername`` with the username of the AD/LDAP user.
- Replace the ``LDAPPassword`` with the password of the AD/LDAP user.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
Omit to use the :ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>` the Distinguished Name (DN) of the AD/LDAP user.
The API response consists of an XML document containing the
access key, secret key, session token, and expiration date. Applications
can use the access key and secret key to access and perform operations on
MinIO.
See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation.

359
source/operations/external-iam/configure-openid-external-identity-management.rst
View File

@ -13,218 +13,257 @@ Configure MinIO for Authentication using OpenID
Overview
--------
MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP)
such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user
identities. The procedure on this page provides instructions for:
MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP) such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user identities.
The procedure on this page provides instructions for:
- Configuring a MinIO cluster for an external OIDC provider.
- Logging into the cluster using the MinIO Console and OIDC credentials.
- Using the MinIO ``AssumeRoleWithWebIdentity`` Security Token Service (STS)
API to generate temporary credentials for use by applications.
.. cond:: k8s
This procedure is generic for OIDC compatible providers. Defer to
the documentation for the OIDC provider of your choice for specific instructions
or procedures on authentication and JWT retrieval.
- Configuring a MinIO Tenant to use an external OIDC provider.
- Accessing the Tenant Console using AD/LDAP Credentials.
- Using the MinIO ``AssumeRoleWithWebIdentity`` Security Token Service (STS) API to generate temporary credentials for use by applications.
.. cond:: linux or container or macos or windows
- Configuring a MinIO cluster for an external OIDC provider.
- Logging into the cluster using the MinIO Console and OIDC credentials.
- Using the MinIO ``AssumeRoleWithWebIdentity`` Security Token Service (STS) API to generate temporary credentials for use by applications.
This procedure is generic for OIDC compatible providers.
Defer to the documentation for the OIDC provider of your choice for specific instructions or procedures on authentication and JWT retrieval.
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-operator.rst
:start-after: start-requires-operator-plugin
:end-before: end-requires-operator-plugin
OpenID-Connect (OIDC) Compatible IDentity Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure assumes an existing OIDC provider such as Okta,
KeyCloak, Dex, Google, or Facebook. Instructions on configuring these services
are out of scope for this procedure.
This procedure assumes an existing OIDC provider such as Okta, KeyCloak, Dex, Google, or Facebook.
Instructions on configuring these services are out of scope for this procedure.
Ensure each user identity intended for use with MinIO has the appropriate
:ref:`claim <minio-external-identity-management-openid-access-control>` configured such that
MinIO can associate a :ref:`policy <minio-policy>` to the authenticated user.
An OpenID user with no assigned policy has no permission to access any action
or resource on the MinIO cluster.
.. cond:: k8s
MinIO Cluster
~~~~~~~~~~~~~
- For OIDC services within the same Kubernetes cluster as the MinIO Tenant, you can use Kubernetes service names to allow the MinIO Tenant to establish connectivity to the OIDC service.
This procedure assumes an existing MinIO cluster running the
:minio-git:`latest stable MinIO version <minio/releases/latest>`.
This procedure *may* work as expected for older versions of MinIO.
- For OIDC services external to the Kubernetes cluster, you must ensure the cluster supports routing communications between Kubernetes services and pods and the external network.
This may require configuration or deployment of additional Kubernetes network components and/or enabling access to the public internet.
Install and Configure ``mc`` with Access to the MinIO Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ensure each user identity intended for use with MinIO has the appropriate :ref:`claim <minio-external-identity-management-openid-access-control>` configured such that MinIO can associate a :ref:`policy <minio-policy>` to the authenticated user.
An OpenID user with no assigned policy has no permission to access any action or resource on the MinIO cluster.
This procedure uses :mc:`mc` for performing operations on the
MinIO cluster. Install ``mc`` on a machine with network access to the cluster.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on
downloading and installing ``mc``.
.. cond:: k8s
This procedure assumes a configured :mc:`alias <mc alias>` for the MinIO
cluster.
MinIO Tenant
~~~~~~~~~~~~
.. _minio-external-identity-management-openid-configure:
This procedure assumes your Kubernetes cluster has sufficient resources to :ref:`deploy a new MinIO Tenant <minio-k8s-deploy-minio-tenant>`.
Procedure
---------
You can also use this procedure as guidance for modifying an existing MinIO Tenant to enable AD/LDAP Identity Management.
1) Set the OpenID Configuration Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: linux or container or macos or windows
You can configure the :abbr:`OIDC (OpenID Connect)` provider using either
environment variables *or* server runtime configuration settings. Both
methods require starting/restarting the MinIO deployment to apply changes. The
following tabs provide a quick reference of all required and optional
environment variables and configuration settings respectively:
MinIO Deployment
~~~~~~~~~~~~~~~~
.. tab-set::
This procedure assumes an existing MinIO cluster running the :minio-git:`latest stable MinIO version <minio/releases/latest>`.
Defer to the :ref:`minio-installation` for more complete documentation on new MinIO deployments.
.. tab-item:: Environment Variables
This procedure *may* work as expected for older versions of MinIO.
MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider
settings using :ref:`environment variables
<minio-server-envvar-external-identity-management-openid>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, specify these settings across all
nodes in the deployment using the *same* values consistently.
.. cond:: linux or container or macos or windows
The following example code sets *all* environment variables related to
configuring an :abbr:`OIDC (OpenID Connect)` provider for external
identity management. The minimum *required* variable is
:envvar:`MINIO_IDENTITY_OPENID_CONFIG_URL`:
Install and Configure ``mc`` with Access to the MinIO Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
This procedure uses :mc:`mc` for performing operations on the MinIO cluster.
Install ``mc`` on a machine with network access to the cluster.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration"
export MINIO_IDENTITY_OPENID_CLIENT_ID="<string>"
export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<string>"
export MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
export MINIO_IDENTITY_OPENID_SCOPES="<string>"
export MINIO_IDENTITY_OPENID_REDIRECT_URI="<string>"
export MINIO_IDENTITY_OPENID_COMMENT="<string>"
This procedure assumes a configured :mc:`alias <mc alias>` for the MinIO cluster.
Replace the ``MINIO_IDENTITY_OPENID_CONFIG_URL`` with the URL endpoint of
the :abbr:`OIDC (OpenID Connect)` provider discovery document.
.. Lightly modeled after the SSE tutorials
For complete documentation on these variables, see
:ref:`minio-server-envvar-external-identity-management-openid`
.. cond:: k8s
.. tab-item:: Configuration Settings
.. _minio-external-identity-management-openid-configure:
MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider
settings using :mc-conf:`configuration settings <identity_openid>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, the :mc-cmd:`mc admin config`
command applies the configuration to all nodes in the deployment.
.. include:: /includes/k8s/steps-configure-openid-external-identity-management.rst
The following example code sets *all* configuration settings related to
configuring an :abbr:`OIDC (OpenID Connect)` provider for external
identity management. The minimum *required* setting is
:mc-conf:`identity_openid config_url <identity_openid.config_url>`:
.. code-block:: shell
:class: copyable
.. Doing this the quick and dirty way. Need to revise later to be proper full includes via stepfiles
mc admin config set ALIAS/ identity_openid \
config_url="https://openid-provider.example.net/.well-known/openid-configuration" \
client_id="<string>" \
client_secret="<string>" \
claim_name="<string>" \
claim_prefix="<string>" \
scopes="<string>" \
redirect_uri="<string>" \
comment="<string>"
.. cond:: linux or container or macos or windows
Replace the ``config_url`` with the URL endpoint of the
:abbr:`OIDC (OpenID Connect)` provider discovery document.
.. _minio-external-identity-management-openid-configure:
For more complete documentation on these settings, see
:mc-conf:`identity_openid`.
Procedure
---------
2) Restart the MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Set the OpenID Configuration Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must restart the MinIO deployment to apply the configuration changes.
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
You can configure the :abbr:`OIDC (OpenID Connect)` provider using either
environment variables *or* server runtime configuration settings. Both
methods require starting/restarting the MinIO deployment to apply changes. The
following tabs provide a quick reference of all required and optional
environment variables and configuration settings respectively:
.. code-block:: shell
:class: copyable
.. tab-set::
mc admin service restart ALIAS
.. tab-item:: Environment Variables
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider
settings using :ref:`environment variables
<minio-server-envvar-external-identity-management-openid>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, specify these settings across all
nodes in the deployment using the *same* values consistently.
3) Use the MinIO Console to Log In with OIDC Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example code sets *all* environment variables related to
configuring an :abbr:`OIDC (OpenID Connect)` provider for external
identity management. The minimum *required* variable is
:envvar:`MINIO_IDENTITY_OPENID_CONFIG_URL`:
The MinIO Console supports the full workflow of authenticating to the
:abbr:`OIDC (OpenID Connect)` provider, generating temporary credentials using
the MinIO :ref:`minio-sts-assumerolewithwebidentity` Security Token Service
(STS) endpoint, and logging the user into the MinIO deployment.
.. code-block:: shell
:class: copyable
Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is
embedded in the MinIO server. You can access the Console by opening the root URL
for the MinIO cluster. For example, ``https://minio.example.net:9000``.
export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration"
export MINIO_IDENTITY_OPENID_CLIENT_ID="<string>"
export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<string>"
export MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
export MINIO_IDENTITY_OPENID_SCOPES="<string>"
export MINIO_IDENTITY_OPENID_REDIRECT_URI="<string>"
export MINIO_IDENTITY_OPENID_COMMENT="<string>"
From the Console, click :guilabel:`BUTTON` to begin the OpenID authentication
flow.
Replace the ``MINIO_IDENTITY_OPENID_CONFIG_URL`` with the URL endpoint of
the :abbr:`OIDC (OpenID Connect)` provider discovery document.
Once logged in, you can perform any action for which the authenticated
user is :ref:`authorized
<minio-external-identity-management-openid-access-control>`.
For complete documentation on these variables, see
:ref:`minio-server-envvar-external-identity-management-openid`
You can also create :ref:`service accounts <minio-idp-service-account>` for
supporting applications which must perform operations on MinIO. Service accounts
are long-lived credentials which inherit their privileges from the parent user.
The parent user can further restrict those privileges while creating the service
account.
.. tab-item:: Configuration Settings
4) Generate S3-Compatible Temporary Credentials using OIDC Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider
settings using :mc-conf:`configuration settings <identity_openid>`. The
:mc:`minio server` process applies the specified settings on its next
startup. For distributed deployments, the :mc:`mc admin config`
command applies the configuration to all nodes in the deployment.
MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
The following example code sets *all* configuration settings related to
configuring an :abbr:`OIDC (OpenID Connect)` provider for external
identity management. The minimum *required* setting is
:mc-conf:`identity_openid config_url <identity_openid.config_url>`:
Applications can generate temporary access credentials as-needed using the
:ref:`minio-sts-assumerolewithwebidentity` Security Token Service (STS)
API endpoint and the JSON Web Token (JWT) returned by the
:abbr:`OIDC (OpenID Connect)` provider.
.. code-block:: shell
:class: copyable
The application must provide a workflow for logging into the
:abbr:`OIDC (OpenID Connect)` provider and retrieving the
JSON Web Token (JWT) associated to the authentication session. Defer to the
provider documentation for obtaining and parsing the JWT token after successful
authentication. MinIO provides an example Go application
:minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` with
an example of managing this workflow.
mc admin config set ALIAS/ identity_openid \
config_url="https://openid-provider.example.net/.well-known/openid-configuration" \
client_id="<string>" \
client_secret="<string>" \
claim_name="<string>" \
claim_prefix="<string>" \
scopes="<string>" \
redirect_uri="<string>" \
comment="<string>"
Once the application retrieves the JWT token, use the
``AssumeRoleWithWebIdentity`` endpoint to generate the temporary credentials:
Replace the ``config_url`` with the URL endpoint of the
:abbr:`OIDC (OpenID Connect)` provider discovery document.
.. code-block:: shell
:class: copyable
For more complete documentation on these settings, see
:mc-conf:`identity_openid`.
POST https://minio.example.net?Action=AssumeRoleWithWebIdentity
&WebIdentityToken=TOKEN
&Version=2011-06-15
&DurationSeconds=86400
&Policy=Policy
2) Restart the MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Replace the ``TOKEN`` with the JWT token returned in the previous step.
- Replace the ``DurationSeconds`` with the duration in seconds until the
temporary credentials expire. The example above specifies a period of
``86400`` seconds, or 24 hours.
- Replace the ``Policy`` with an inline URL-encoded JSON
:ref:`policy <minio-policy>` that further restricts the permissions associated
to the temporary credentials. Omit to use the policy associated to the
OpenID user :ref:`policy claim <minio-external-identity-management-openid-access-control>`.
You must restart the MinIO deployment to apply the configuration changes.
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
The API response consists of an XML document containing the
access key, secret key, session token, and expiration date. Applications
can use the access key and secret key to access and perform operations on
MinIO.
.. code-block:: shell
:class: copyable
See the :ref:`minio-sts-assumerolewithwebidentity` for reference documentation.
mc admin service restart ALIAS
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
restart.
3) Use the MinIO Console to Log In with OIDC Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The MinIO Console supports the full workflow of authenticating to the
:abbr:`OIDC (OpenID Connect)` provider, generating temporary credentials using
the MinIO :ref:`minio-sts-assumerolewithwebidentity` Security Token Service
(STS) endpoint, and logging the user into the MinIO deployment.
Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is
embedded in the MinIO server. You can access the Console by opening the root URL
for the MinIO cluster. For example, ``https://minio.example.net:9000``.
From the Console, click :guilabel:`BUTTON` to begin the OpenID authentication
flow.
Once logged in, you can perform any action for which the authenticated
user is :ref:`authorized
<minio-external-identity-management-openid-access-control>`.
You can also create :ref:`service accounts <minio-idp-service-account>` for
supporting applications which must perform operations on MinIO. Service accounts
are long-lived credentials which inherit their privileges from the parent user.
The parent user can further restrict those privileges while creating the service
account.
4) Generate S3-Compatible Temporary Credentials using OIDC Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
Applications can generate temporary access credentials as-needed using the
:ref:`minio-sts-assumerolewithwebidentity` Security Token Service (STS)
API endpoint and the JSON Web Token (JWT) returned by the
:abbr:`OIDC (OpenID Connect)` provider.
The application must provide a workflow for logging into the
:abbr:`OIDC (OpenID Connect)` provider and retrieving the
JSON Web Token (JWT) associated to the authentication session. Defer to the
provider documentation for obtaining and parsing the JWT token after successful
authentication. MinIO provides an example Go application
:minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` with
an example of managing this workflow.
Once the application retrieves the JWT token, use the
``AssumeRoleWithWebIdentity`` endpoint to generate the temporary credentials:
.. code-block:: shell
:class: copyable
POST https://minio.example.net?Action=AssumeRoleWithWebIdentity
&WebIdentityToken=TOKEN
&Version=2011-06-15
&DurationSeconds=86400
&Policy=Policy
- Replace the ``TOKEN`` with the JWT token returned in the previous step.
- Replace the ``DurationSeconds`` with the duration in seconds until the temporary credentials expire. The example above specifies a period of ``86400`` seconds, or 24 hours.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
Omit to use the policy associated to the OpenID user :ref:`policy claim <minio-external-identity-management-openid-access-control>`.
The API response consists of an XML document containing the
access key, secret key, session token, and expiration date. Applications
can use the access key and secret key to access and perform operations on
MinIO.
See the :ref:`minio-sts-assumerolewithwebidentity` for reference documentation.

6
source/operations/install-deploy-manage/decommission-server-pool.rst
View File

@ -170,7 +170,7 @@ Decommission a Server Pool
1) Review the MinIO Deployment Topology
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mc-cmd:`mc admin decommission` command returns a list of all
The :mc:`mc admin decommission` command returns a list of all
pools in the MinIO deployment:
.. code-block:: shell
@ -280,7 +280,7 @@ the next step once decommissioning is completed.
If :guilabel:`Status` reads as failed, you can re-run the
:mc-cmd:`mc admin decommission start` command to resume the process.
For persistent failures, use :mc-cmd:`mc admin console` or review
For persistent failures, use :mc:`mc admin console` or review
the ``systemd`` logs (e.g. ``journalctl -u minio``) to identify more specific
errors.
@ -340,5 +340,5 @@ to restart the MinIO service:
:start-after: start-nondisruptive-upgrade-desc
:end-before: end-nondisruptive-upgrade-desc
Once the deployment is online, use :mc-cmd:`mc admin info` to confirm the
Once the deployment is online, use :mc:`mc admin info` to confirm the
uptime of all remaining servers in the deployment.

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

@ -366,208 +366,3 @@ MinIO service:
- :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.
Use the same type of disk (NVMe, SSD, or HDD) with the same capacity
across all nodes in the deployment. MinIO does not distinguish drive
types when using the underlying storage and does not benefit from mixed
storage types. Additionally. 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.
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.
.. _minio-k8s-production-considerations-memory:
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
.. _minio-requests-per-node:
Requests Per Node
~~~~~~~~~~~~~~~~~
You can calculate the maximum number of concurrent requests per host with this formula:
:math:`totalRam / ramPerRequest`
To calculate the amount of RAM used for each request, use this formula:
:math:`((2MiB + 128KiB) * driveCount) + (2 * 10MiB) + (2 * 1 MiB)`
10MiB is the default erasure block size v1.
1 MiB is the default erasure block size v2.
The following table lists the maximum concurrent requests on a node based on the number of host drives and the *free* system RAM:
.. list-table::
:header-rows: 1
:width: 100%
* - Number of Drives
- 32 GiB of RAM
- 64 GiB of RAM
- 128 GiB of RAM
- 256 GiB of RAM
- 512 GiB of RAM
* - 4 Drives
- 1,074
- 2,149
- 4,297
- 8,595
- 17,190
* - 8 Drives
- 840
- 1,680
- 3,361
- 6,722
- 13,443
* - 16 Drives
- 585
- 1,170
- 2.341
- 4,681
- 9,362

13
source/operations/install-deploy-manage/deploy-minio-tenant.rst
View File

@ -1,6 +1,12 @@
.. The following label handles links from content to distributed MinIO in K8s context
.. _deploy-minio-distributed:
.. Redirect all references to tenant topologies here
.. _minio-snsd:
.. _minio-snmd:
.. _minio-mnmd:
.. _minio-k8s-deploy-minio-tenant:
=====================
@ -21,6 +27,9 @@ This procedure documents deploying a MinIO Tenant using the MinIO Operator Conso
:class: no-scaled-link
:alt: MinIO Operator Console
The MinIO Operator supports only the Distributed (Multi-Node Multi-Drive) MinIO topology.
You can use basic Kubernetes YAML resource definitions to deploy Single-Node Single-Drive and Single-Node Multi-Drive topologies for local testing and evaluation as necessary.
The Operator Console provides a rich user interface for deploying and managing MinIO Tenants on Kubernetes infrastructure.
Installing the MinIO :ref:`Kubernetes Operator <deploy-operator-kubernetes>` automatically installs and configures the Operator Console.
@ -228,7 +237,7 @@ Settings marked with an asterisk :guilabel:`*` are *required*:
* - :guilabel:`Memory per Node [Gi]`
- Specify the total amount of memory (RAM) to allocate per MinIO server pod.
See :ref:`minio-k8s-production-considerations-memory` for guidance on setting this value.
See :ref:`minio-hardware-checklist-memory` for guidance on setting this value.
The Kubernetes cluster *must* have worker nodes with sufficient free RAM to match the pod request.
@ -374,7 +383,7 @@ This includes configuring an external IDP such as :ref:`OpenID <minio-external-i
- Configure additional internal MinIO users for the Operator to create as part of deploying the Tenant.
* - :guilabel:`OpenID`
- Configure an OpenID Connect-compatible servce as an external Identity Provider (e.g. Keycloak, Okta, Google, Facebook, Dex) to manage MinIO users.
- Configure an OpenID Connect-compatible service as an external Identity Provider (e.g. Keycloak, Okta, Google, Facebook, Dex) to manage MinIO users.
* - :guilabel:`Active Directory`
- Configure an Active Directory or OpenLDAP service as the external Identity Provider to manage MinIO users.

8
source/operations/install-deploy-manage/multi-site-replication.rst
View File

@ -152,7 +152,7 @@ Configure Site Replication
To add additional sites beyond two, select the ``+`` button to the side of one of the Site entries.
To remove a site previously added, select the ``-`` button to the side of the site.
Site replication adds a :mc-cmd:`~mc admin user svcacct` under the ``root`` user to perform replication activities.
Site replication adds a :mc:`~mc admin user svcacct` under the ``root`` user to perform replication activities.
#. Select **Save**
@ -178,7 +178,7 @@ Configure Site Replication
For example, for three MinIO sites, you might create aliases ``minio1``, ``minio2``, and ``minio3``.
Use :mc-cmd:`mc alias set`
Use :mc:`mc alias set`
.. code-block:: shell
@ -300,11 +300,11 @@ The new site must meet the following requirements:
#. Configure an alias for each site
To check the existing aliases, use :mc-cmd:`mc alias list`.
To check the existing aliases, use :mc:`mc alias list`.
For example, for three MinIO sites, you might create aliases ``minio1``, ``minio2``, and ``minio3``.
Use :mc-cmd:`mc alias set`
Use :mc:`mc alias set`
.. code-block:: shell

4
source/operations/install-deploy-manage/upgrade-minio-deployment.rst
View File

@ -84,7 +84,7 @@ Use these steps to upgrade a MinIO deployment where the MinIO server process is
3. Validate the Upgrade
Use the :mc-cmd:`mc admin info` command to check that all MinIO servers are online, operational, and reflect the installed MinIO version.
Use the :mc:`mc admin info` command to check that all MinIO servers are online, operational, and reflect the installed MinIO version.
4. Update MinIO Client
@ -104,7 +104,7 @@ Update Non-System Managed MinIO Deployments
Use these steps to upgrade a MinIO deployment where the MinIO server process is managed outside of the system (``systemd``, ``systemctl``), such as by a user, an automated script, or some other process management tool.
This procedure only works for systems where the user running the MinIO process has write permissions for the path to the MinIO binary.
The :mc-cmd:`mc admin update` command updates all MinIO server binaries in the target MinIO deployment before restarting all nodes simultaneously.
The :mc:`mc admin update` command updates all MinIO server binaries in the target MinIO deployment before restarting all nodes simultaneously.
The restart process typically completes within a few seconds and is *non-disruptive* to ongoing operations.
- For deployments managed using ``systemctl``, see

9
source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst
View File

@ -89,7 +89,7 @@ The root KMS provides stateful and secured storage of External Keys (EK) while |
#. Create a new |EK| on Vault for use with |SSE|.
#. Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
For productoin baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.
For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.
.. important::
@ -105,10 +105,9 @@ Prerequisites
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The procedures on this page *requires* a valid installation of the MinIO
Kubernetes Operator and assumes the local host has a matching installation of
the MinIO Kubernetes Operator. This procedure assumes the latest stable Operator
and Plugin version |operator-version-stable|.
.. include:: /includes/k8s/common-operator.rst
:start-after: start-requires-operator-plugin
:end-before: end-requires-operator-plugin
See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator.

10
source/operations/troubleshooting.rst
View File

@ -69,9 +69,9 @@ Registering Your MinIO Deployment with SUBNET
You can register for SUBNET from the command line.
Refer to :mc-cmd:`mc support register` for instructions.
Refer to :mc:`mc support register` for instructions.
For clusters without direct Internet access, refer to the instructions in the :ref:`airgap example <minio-support-register-airgap>` of the :mc-cmd:`mc support register` documentation.
For clusters without direct Internet access, refer to the instructions in the :ref:`airgap example <minio-support-register-airgap>` of the :mc:`mc support register` documentation.
SUBNET Issues
@ -115,7 +115,7 @@ Deployment Health
~~~~~~~~~~~~~~~~~
The deployment's details include a summary of the deployment's configuration and the number of checks run and failed.
You can select :guilabel:`Upload` to add diagnostic health data obtained from the :mc-cmd:`mc support diagnostics` command or the MinIO Console's Support > Health page.
You can select :guilabel:`Upload` to add diagnostic health data obtained from the :mc:`mc support diagnostics` command or the MinIO Console's Support > Health page.
If you need support from MinIO Engineering, you can create a :guilabel:`New Issue` for the deployment.
@ -145,7 +145,7 @@ If you registered the cluster with SUBNET, Performance and Inspection files can
For clusters with an airgap, firewall, or otherwise blocked from SUBNET directly, you can manually upload files to SUBNET after logging in.
#. Generate the file(s) to upload from the command line with :mc-cmd:`mc support diagnostics` or :mc-cmd:`mc support inspect`
#. Generate the file(s) to upload from the command line with :mc:`mc support diagnostics` or :mc:`mc support inspect`
#. Sign in to `SUBNET <https://subnet.min.io>`_
#. Select :guilabel:`Deployments`
#. Select :guilabel:`Diagnostics`
@ -155,7 +155,7 @@ For clusters with an airgap, firewall, or otherwise blocked from SUBNET directly
Encrypting Data
~~~~~~~~~~~~~~~
Data from the Inspect tool in :ref:`Console <minio-console>` or the :mc-cmd:`mc support inspect` command can be encrypted.
Data from the Inspect tool in :ref:`Console <minio-console>` or the :mc:`mc support inspect` command can be encrypted.
For more details about encrypting or decrypting such files, see :ref:`Encrypting Files <minio-support-encryption>`.

4
source/operations/troubleshooting/encrypting-files.rst
View File

@ -13,7 +13,7 @@ Encrypting Files
Description
-----------
You can encrypt the output of the :mc-cmd:`mc support inspect` command for enhanced security when transmitting the files to |SUBNET|.
You can encrypt the output of the :mc:`mc support inspect` command for enhanced security when transmitting the files to |SUBNET|.
Encryption
----------
@ -41,7 +41,7 @@ As the output says, MinIO only displays the encryption key this one time, and it
Decryption
----------
MinIO provides a decryption tool to use on the files generated by :mc-cmd:`mc support inspect`.
MinIO provides a decryption tool to use on the files generated by :mc:`mc support inspect`.
To install the decryption tool, install `Go <https://golang.org/dl/>`_, then run