mirror of
https://github.com/minio/docs.git
synced 2025-06-05 19:57:02 +03:00
parent
4ea1289617
commit
ada852eca3
@ -41,7 +41,8 @@ Multi-Node Multi-Drive (MNMD or "Distributed")
|
||||
Multiple MinIO servers with at least four drives across all servers.
|
||||
The distributed |MNMD| topology supports production-grade object storage with drive and node-level availability and resiliency.
|
||||
|
||||
This documentation provides instructions for |SNSD| and |SNMD| for supporting local development and evaluation of MinIO on a single host machine. For |MNMD| deployments, use the MinIO Kubernetes Operator to deploy and manage MinIO tenants in a containerized and orchestrated environment.
|
||||
This documentation provides instructions for |SNSD| and |SNMD| for supporting local development and evaluation of MinIO on a single host machine **only**.
|
||||
For |MNMD| deployments, use the MinIO Kubernetes Operator to deploy and manage MinIO tenants in a containerized and orchestrated environment.
|
||||
|
||||
.. _minio-installation-platform-support:
|
||||
|
||||
|
142
source/includes/container/steps-upgrade-minio-deployment.rst
Normal file
142
source/includes/container/steps-upgrade-minio-deployment.rst
Normal file
@ -0,0 +1,142 @@
|
||||
MinIO uses an update-then-restart methodology for upgrading a deployment to a newer release:
|
||||
|
||||
1. Update the container MinIO image with the newer release.
|
||||
2. Restart the container.
|
||||
|
||||
This procedure does not require taking downtime and is non-disruptive to ongoing operations.
|
||||
|
||||
Considerations
|
||||
--------------
|
||||
|
||||
Upgrades Are Non-Disruptive
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO's upgrade-then-restart procedure does *not* require taking downtime or scheduling a maintenance period.
|
||||
MinIO restarts are fast, such that restarting all server processes in parallel typically completes in a few seconds.
|
||||
MinIO operations are atomic and strictly consistent, such that applications using MinIO or S3 SDKs can rely on the built-in :aws-docs:`transparent retry <general/latest/gr/api-retries.html>` without further client-side logic.
|
||||
This ensures upgrades are non-disruptive to ongoing operations.
|
||||
|
||||
Check Release Notes
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO publishes :minio-git:`Release Notes <minio/releases>` for your reference as part of identifying the changes applied in each release.
|
||||
Review the associated release notes between your current MinIO version and the newer release so you have a complete view of any changes.
|
||||
|
||||
Pay particular attention to any releases that are *not* backwards compatible.
|
||||
You cannot trivially downgrade from any such release.
|
||||
|
||||
Procedure
|
||||
---------
|
||||
|
||||
You can run the ``podman container inspect`` or ``docker inspect`` command to inspect the container and validate the current container image:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
# For docker, use docker inspect
|
||||
podman container inspect --format='{{.Config.Image}}' CONTAINER_NAME
|
||||
|
||||
The following output indicates the container was created using the most recent stable image tag:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
quay.io/minio/minio:latest
|
||||
|
||||
Use the :ref:`minio-upgrade-latest-tag` steps to upgrade your container.
|
||||
|
||||
The following output indicates the container was created using a specific image tag:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
quay.io/minio/minio:RELEASE.2023-07-21T21-12-44Z
|
||||
|
||||
Use the :ref:`minio-upgrade-specific-tag` steps to upgrade your container.
|
||||
|
||||
.. _minio-upgrade-latest-tag:
|
||||
|
||||
Upgrade Containers using Latest Image Tag
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Update your image registry
|
||||
|
||||
Pull the latest stable MinIO image for the configured image repository:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
# For docker, use docker pull
|
||||
podman pull quay.io/minio/minio:latest
|
||||
|
||||
#. Restart the container
|
||||
|
||||
You must restart the container to load the new image binary for use by MinIO:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
# For docker, use docker restart
|
||||
podman container restart CONTAINER_NAME
|
||||
|
||||
#. Validate the Upgrade
|
||||
|
||||
Use the :mc:`mc admin info` command to check that the MinIO container is online, operational, and reflects the installed MinIO version.
|
||||
|
||||
#. Update MinIO Client
|
||||
|
||||
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
|
||||
|
||||
.. _minio-upgrade-specific-tag:
|
||||
|
||||
Upgrade Containers using Specific Image Tag
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Update your local image registry
|
||||
|
||||
Pull the desired image you want to use for updating the container.
|
||||
The following example uses the latest stable version of MinIO:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
# For docker, use docker pull
|
||||
podman pull quay.io/minio/minio:|minio-tag|
|
||||
|
||||
#. Modify the container start script or configuration
|
||||
|
||||
Specify the new MinIO tag to the container start script or configuration.
|
||||
For Docker, this might be the Compose file used to start MinIO.
|
||||
For Podman, this might be a YAML file used to create the container or pod.
|
||||
|
||||
Ensure the ``image: <VALUE>`` matches the newly pulled image tag.
|
||||
|
||||
#. Restart or re-create the container
|
||||
|
||||
If you started the container using CLI commands, you may need to completely stop, remove, and re-create the container.
|
||||
Use a script to perform this procedure to minimize potential downtime.
|
||||
|
||||
For Docker, this might require running ``docker compose restart``.
|
||||
|
||||
#. Validate the Upgrade
|
||||
|
||||
Use the :mc:`mc admin info` command to check that the MinIO container is online, operational, and reflects the installed MinIO version.
|
||||
|
||||
#. Update MinIO Client
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
|
143
source/includes/linux/steps-upgrade-minio-deployment.rst
Normal file
143
source/includes/linux/steps-upgrade-minio-deployment.rst
Normal file
@ -0,0 +1,143 @@
|
||||
MinIO uses an update-then-restart methodology for upgrading a deployment to a newer release:
|
||||
|
||||
1. Update the MinIO binary with the newer release.
|
||||
2. Restart the deployment using :mc-cmd:`mc admin service restart`.
|
||||
|
||||
This procedure does not require taking downtime and is non-disruptive to ongoing operations.
|
||||
|
||||
This page documents methods for upgrading using the update-then-restart method for both ``systemctl`` and user-managed MinIO deployments.
|
||||
Deployments using Ansible, Terraform, or other management tools can use the procedures here as guidance for implementation within the existing automation framework.
|
||||
|
||||
Considerations
|
||||
--------------
|
||||
|
||||
Upgrades Are Non-Disruptive
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO's upgrade-then-restart procedure does *not* require taking downtime or scheduling a maintenance period.
|
||||
MinIO restarts are fast, such that restarting all server processes in parallel typically completes in a few seconds.
|
||||
MinIO operations are atomic and strictly consistent, such that applications using MinIO or S3 SDKs can rely on the built-in :aws-docs:`transparent retry <general/latest/gr/api-retries.html>` without further client-side logic.
|
||||
This ensures upgrades are non-disruptive to ongoing operations.
|
||||
|
||||
"Rolling" or serial "one-at-a-time" upgrade methods do not provide any advantage over the recommended "parallel" procedure, and can introduce unnecessary complexity to the upgrade procedure.
|
||||
For virtualized environments which *require* rolling updates, you should modify the recommended procedure as follows:
|
||||
|
||||
1. Update the MinIO Binary in the virtual machine or container one at a time.
|
||||
2. Restart the MinIO deployment using :mc-cmd:`mc admin service restart`.
|
||||
3. Update the virtual machine/container configuration to use the matching newer MinIO image.
|
||||
4. Perform the rolling restart of each machine/container with the updated image.
|
||||
|
||||
Check Release Notes
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO publishes :minio-git:`Release Notes <minio/releases>` for your reference as part of identifying the changes applied in each release.
|
||||
Review the associated release notes between your current MinIO version and the newer release so you have a complete view of any changes.
|
||||
|
||||
Pay particular attention to any releases that are *not* backwards compatible.
|
||||
You cannot trivially downgrade from any such release.
|
||||
|
||||
.. _minio-upgrade-systemctl:
|
||||
|
||||
Update ``systemctl``-Managed MinIO Deployments
|
||||
----------------------------------------------
|
||||
|
||||
Use these steps to upgrade a MinIO deployment where the MinIO server process is managed by ``systemctl``, such as those created using the MinIO :ref:`DEB/RPM packages <deploy-minio-distributed-baremetal>`.
|
||||
|
||||
1. Update the MinIO Binary on Each Node
|
||||
|
||||
.. include:: /includes/linux/common-installation.rst
|
||||
:start-after: start-upgrade-minio-binary-desc
|
||||
:end-before: end-upgrade-minio-binary-desc
|
||||
|
||||
2. Restart the Deployment
|
||||
|
||||
Run the :mc-cmd:`mc admin service restart` command to restart all MinIO server processes in the deployment simultaneously.
|
||||
|
||||
The restart process typically completes within a few seconds and is *non-disruptive* to ongoing operations.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin service restart ALIAS
|
||||
|
||||
Replace :ref:`alias <alias>` of the MinIO deployment to restart.
|
||||
|
||||
3. Validate the Upgrade
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
.. _minio-upgrade-mc-admin-update:
|
||||
|
||||
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.
|
||||
For deployments managed using ``systemctl``, see :ref:`minio-upgrade-systemctl`.
|
||||
|
||||
Update using ``mc admin update``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
The following command updates a MinIO deployment with the specified :ref:`alias <alias>` to the latest stable release:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin update ALIAS
|
||||
|
||||
The command may fail if the user which a ``minio`` server process runs as does not have read/write permissions to the path of the binary itself.
|
||||
|
||||
You can specify a URL resolving to a specific MinIO server binary version.
|
||||
Airgapped or internet-isolated deployments may utilize this feature for updating from an internally-accessible server:
|
||||
|
||||
.. 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
|
||||
|
||||
Update by manually replacing the binary
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can download and manually replace the ``minio`` server binary on each of the host nodes in the deployment.
|
||||
You must then restart all nodes simultaneously, such as by using :mc-cmd:`mc admin service restart`.
|
||||
|
||||
For example, the following command downloads the latest stable MinIO binary for Linux and copies it to ``/usr/local/bin``.
|
||||
The command overwrites the existing ``minio`` binary at that path.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
wget https://dl.min.io/server/minio/release/linux-amd64/minio
|
||||
chmod +x ./minio
|
||||
sudo mv -f ./minio /usr/local/bin/
|
||||
|
||||
Once you have replaced the binary on all MinIO hosts in the deployment, you must restart all nodes simultaneously.
|
||||
|
||||
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
|
@ -61,24 +61,37 @@ The :ref:`integrations-nginx-proxy` reference provides a baseline configuration
|
||||
Sequential Hostnames
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO *requires* using expansion notation ``{x...y}`` to denote a sequential
|
||||
series of MinIO hosts when creating a server pool. MinIO therefore *requires*
|
||||
using sequentially-numbered hostnames to represent each
|
||||
:mc:`minio server` process in the deployment.
|
||||
MinIO *requires* using expansion notation ``{x...y}`` to denote a sequential series of MinIO hosts when creating a server pool.
|
||||
MinIO supports using either a sequential series of hostnames *or* IP addresses to represent each :mc:`minio server` process in the deployment.
|
||||
|
||||
This procedure assumes use of sequential hostnames due to the lower overhead of management, especially in larger distributed clusters.
|
||||
|
||||
Create the necessary DNS hostname mappings *prior* to starting this procedure.
|
||||
For example, the following hostnames would support a 4-node distributed
|
||||
deployment:
|
||||
For example, the following hostnames would support a 4-node distributed deployment:
|
||||
|
||||
- ``minio1.example.com``
|
||||
- ``minio2.example.com``
|
||||
- ``minio3.example.com``
|
||||
- ``minio4.example.com``
|
||||
- ``minio-01.example.com``
|
||||
- ``minio-02.example.com``
|
||||
- ``minio-03.example.com``
|
||||
- ``minio-04.example.com``
|
||||
|
||||
You can specify the entire range of hostnames using the expansion notation
|
||||
``minio{1...4}.example.com``.
|
||||
You can specify the entire range of hostnames using the expansion notation ``minio-0{1...4}.example.com``.
|
||||
|
||||
Configuring DNS to support MinIO is out of scope for this procedure.
|
||||
.. dropdown:: Non-Sequential Hostnames or IP Addresses
|
||||
|
||||
MinIO does not support non-sequential hostnames or IP addresses for distributed deployments.
|
||||
You can instead use ``/etc/hosts`` on each node to set a simple DNS scheme that supports expansion notation.
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# /etc/hosts
|
||||
|
||||
198.0.2.10 minio-01.example.net
|
||||
198.51.100.3 minio-02.example.net
|
||||
198.0.2.43 minio-03.example.net
|
||||
198.51.100.12 minio-04.example.net
|
||||
|
||||
The above hosts configuration supports expansion notation of ``minio-0{1...4}.example.net``, mapping the sequential hostnames to the desired IP addresses.
|
||||
|
||||
.. _deploy-minio-distributed-prereqs-storage:
|
||||
|
||||
|
@ -10,16 +10,6 @@ Upgrade a MinIO Deployment
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
MinIO uses an update-then-restart methodology for upgrading a deployment to a newer release:
|
||||
|
||||
1. Update the MinIO binary on all hosts with the newer release.
|
||||
2. Restart the deployment using :mc-cmd:`mc admin service restart`.
|
||||
|
||||
This procedure does not require taking downtime and is non-disruptive to ongoing operations.
|
||||
|
||||
This page documents methods for upgrading using the update-then-restart method for both ``systemctl`` and user-managed MinIO deployments.
|
||||
Deployments using Ansible, Terraform, or other management tools can use the procedures here as guidance for implementation within the existing automation framework.
|
||||
|
||||
.. admonition:: Test Upgrades In a Lower Environment
|
||||
:class: important
|
||||
|
||||
@ -28,110 +18,18 @@ Deployments using Ansible, Terraform, or other management tools can use the proc
|
||||
|
||||
For MinIO deployments that are significantly behind latest stable (6+ months), consider using |SUBNET| for additional support and guidance during the upgrade procedure.
|
||||
|
||||
Considerations
|
||||
--------------
|
||||
.. cond:: linux
|
||||
|
||||
Upgrades Are Non-Disruptive
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. include:: /includes/linux/steps-upgrade-minio-deployment.rst
|
||||
|
||||
MinIO's upgrade-then-restart procedure does *not* require taking downtime or scheduling a maintenance period.
|
||||
MinIO restarts are fast, such that restarting all server processes in parallel typically completes in a few seconds.
|
||||
MinIO operations are atomic and strictly consistent, such that applications using MinIO or S3 SDKs can rely on the built-in :aws-docs:`transparent retry <general/latest/gr/api-retries.html>` without further client-side logic.
|
||||
This ensures upgrades are non-disruptive to ongoing operations.
|
||||
.. cond:: container
|
||||
|
||||
"Rolling" or serial "one-at-a-time" upgrade methods do not provide any advantage over the recommended "parallel" procedure, and can introduce unnecessary complexity to the upgrade procedure.
|
||||
For virtualized environments which *require* rolling updates, you should amend the recommend procedure as follows:
|
||||
.. include:: /includes/container/steps-upgrade-minio-deployment.rst
|
||||
|
||||
1. Update the MinIO Binary in the virtual machine or container one at a time.
|
||||
2. Restart the MinIO deployment using :mc-cmd:`mc admin service restart`.
|
||||
3. Update the virtual machine/container configuration to use the matching newer MinIO image.
|
||||
4. Perform the rolling restart of each machine/container with the updated image.
|
||||
.. cond:: windows
|
||||
|
||||
Check Release Notes
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
.. include:: /includes/windows/steps-upgrade-minio-deployment.rst
|
||||
|
||||
MinIO publishes :minio-git:`Release Notes <minio/releases>` for your reference as part of identifying the changes applied in each release.
|
||||
Review the associated release notes between your current MinIO version and the newer release such that you have a complete view of any changes.
|
||||
.. cond:: macos
|
||||
|
||||
Pay particular attention to any releases that are backwards incompatible.
|
||||
You cannot trivially downgrade from any such release.
|
||||
|
||||
.. _minio-upgrade-systemctl:
|
||||
|
||||
Update ``systemctl``-Managed MinIO Deployments
|
||||
----------------------------------------------
|
||||
|
||||
Use these steps to upgrade a MinIO deployment where the MinIO server process is managed by ``systemctl``, such as those created using the MinIO :ref:`DEB/RPM packages <deploy-minio-distributed-baremetal>`.
|
||||
|
||||
1. Update the MinIO Binary on Each Node
|
||||
|
||||
.. include:: /includes/linux/common-installation.rst
|
||||
:start-after: start-upgrade-minio-binary-desc
|
||||
:end-before: end-upgrade-minio-binary-desc
|
||||
|
||||
2. Restart the Deployment
|
||||
|
||||
Run the :mc-cmd:`mc admin service restart` command to restart all MinIO server processes in the deployment simultaneously.
|
||||
|
||||
The restart process typically completes within a few seconds and is *non-disruptive* to ongoing operations.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin service restart ALIAS
|
||||
|
||||
Replace :ref:`alias <alias>` of the MinIO deployment to restart.
|
||||
|
||||
3. Validate the Upgrade
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
.. _minio-upgrade-mc-admin-update:
|
||||
|
||||
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:`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
|
||||
:ref:`minio-upgrade-systemctl`.
|
||||
|
||||
- For Kubernetes or other containerized environments, defer to the native
|
||||
mechanisms for updating container images across a deployment.
|
||||
|
||||
The following command updates a MinIO deployment with the specified :ref:`alias <alias>` to the latest stable release:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin update ALIAS
|
||||
|
||||
You can specify a URL resolving to a specific MinIO server binary version.
|
||||
Airgapped or internet-isolated deployments may utilize this feature for updating from an internally-accessible server:
|
||||
|
||||
.. 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
|
||||
.. include:: /includes/macos/steps-upgrade-minio-deployment.rst
|
@ -21,11 +21,22 @@ Upgrade
|
||||
Decommission
|
||||
Drain data from an older storage pool in preparation for removing it from the deployment
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
.. cond:: not (linux or k8s)
|
||||
|
||||
/operations/install-deploy-manage/expand-minio-deployment
|
||||
/operations/install-deploy-manage/upgrade-minio-deployment
|
||||
/operations/install-deploy-manage/decommission-server-pool
|
||||
/operations/install-deploy-manage/migrate-fs-gateway
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
|
||||
/operations/install-deploy-manage/upgrade-minio-deployment
|
||||
/operations/install-deploy-manage/migrate-fs-gateway
|
||||
|
||||
.. cond:: linux or k8s
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
|
||||
/operations/install-deploy-manage/expand-minio-deployment
|
||||
/operations/install-deploy-manage/upgrade-minio-deployment
|
||||
/operations/install-deploy-manage/decommission-server-pool
|
||||
/operations/install-deploy-manage/migrate-fs-gateway
|
||||
|
@ -79,6 +79,33 @@ Enabling TLS
|
||||
You can place the generated ``public.crt`` and ``private.key`` into the ``/.minio/certs`` directory to enable TLS for the MinIO deployment.
|
||||
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
|
||||
|
||||
.. cond:: container
|
||||
|
||||
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
|
||||
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
|
||||
|
||||
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the specified directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
/opts/certs
|
||||
private.key
|
||||
public.crt
|
||||
|
||||
You can use the MinIO :minio-git:`certgen <certgen>` to mint self-signed certificates for enabling TLS for evaluating MinIO with TLS enabled.
|
||||
For example, the following command generates a self-signed certificate with a set of IP and DNS SANs associated to the MinIO Server hosts:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
certgen -host "localhost,minio-*.example.net"
|
||||
|
||||
You may need to start the container and set a ``--hostname`` that matches the TLS certificate DNS SAN.
|
||||
|
||||
Move the certificates to the local host machine path that the container mounts to its ``--certs-dir`` path.
|
||||
When the MinIO container starts, the server searches the specified location for certificates and uses them to enable TLS.
|
||||
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
|
||||
|
||||
.. cond:: macos
|
||||
|
||||
The MinIO server searches the following directory for TLS keys and certificates:
|
||||
@ -189,6 +216,48 @@ Multiple Domain-Based TLS Certificates
|
||||
|
||||
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
|
||||
|
||||
|
||||
.. cond:: container
|
||||
|
||||
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
|
||||
When a client connects using a specific hostname, MinIO uses :abbr:`SNI (Server Name Indication)` to select the appropriate TLS certificate for that hostname.
|
||||
|
||||
For example, consider a MinIO deployment reachable through the following hostnames:
|
||||
|
||||
- ``https://minio.example.net`` (default TLS certificates)
|
||||
- ``https://s3.example.net``
|
||||
- ``https://minio.internal-example.net``
|
||||
|
||||
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
|
||||
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
|
||||
|
||||
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the specified directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
|
||||
For other hostnames, create a subfolder whose name matches the domain to improve human readability.
|
||||
Place the TLS private and public key for that domain in the subfolder.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
/opts/certs
|
||||
private.key
|
||||
public.crt
|
||||
s3-example.net/
|
||||
private.key
|
||||
public.crt
|
||||
internal-example.net/
|
||||
private.key
|
||||
public.crt
|
||||
|
||||
When the MinIO container starts, the server searches the mounted location ``/opts/certs`` for certificates and uses them enable TLS.
|
||||
MinIO serves clients connecting to the container using a supported hostname with the associated certificates.
|
||||
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
|
||||
|
||||
While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SAN), this would reveal the ``internal-example.net`` and ``s3-example.net`` hostnames to any client which inspects the server certificate.
|
||||
Using one TLS certificate per hostname better protects each individual hostname from discovery.
|
||||
|
||||
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
|
||||
|
||||
.. cond:: macos
|
||||
|
||||
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
|
||||
@ -317,6 +386,26 @@ Third-Party Certificate Authorities
|
||||
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
|
||||
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
|
||||
|
||||
.. cond:: container
|
||||
|
||||
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
|
||||
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
|
||||
|
||||
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, the server searches in the ``/CAs`` path at that specified directory.
|
||||
For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
/opts/certs
|
||||
private.key
|
||||
public.crt
|
||||
/CAs
|
||||
my-ca.crt
|
||||
|
||||
Place the certificate file for each CA into the ``/CAs`` subdirectory.
|
||||
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
|
||||
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
|
||||
|
||||
.. cond:: macos
|
||||
|
||||
The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.
|
||||
|
@ -82,6 +82,8 @@ excludes:
|
||||
- 'operations/install-deploy-manage/minio-operator-console.rst'
|
||||
- 'operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst'
|
||||
- 'operations/install-deploy-manage/multi-site-replication.rst'
|
||||
- 'operations/install-deploy-manage/decommission-server-pool.rst'
|
||||
- 'operations/install-deploy-manage/expand-minio-deployment.rst'
|
||||
- 'operations/deploy-manage-tenants.rst'
|
||||
- 'reference/kubectl-minio-plugin*'
|
||||
- 'reference/minio-server*'
|
||||
|
Loading…
x
Reference in New Issue
Block a user