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

Clarify Upgrade Procedure

Browse Source
This commit is contained in:
Ravind Kumar
2022-08-03 17:43:19 -04:00
parent 78f558c5b9
commit a9e05b5131
2 changed files with 90 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
source/includes/common-installation.rst
View File

@ -51,8 +51,9 @@ recommends using RPM or DEB installation routes.
.. start-upgrade-minio-binary-desc
The following tabs provide examples of updating MinIO onto 64-bit Linux
operating systems using RPM, DEB, or binary:
The following tabs provide examples of updating MinIO onto 64-bit Linux operating systems using RPM, DEB, or binary executable.
For infrastructure managed by tools such as Ansible or Terraform, defer to your internal procedures for updating packages or binaries across multiple managed hosts.
.. tab-set::
@ -66,7 +67,7 @@ operating systems using RPM, DEB, or binary:
:class: copyable
:substitutions:
wget |minio-rpm| -O minio.deb
curl |minio-rpm| --output minio.rpm
sudo dnf update minio.rpm
.. tab-item:: DEB (Debian/Ubuntu)
@ -79,7 +80,7 @@ operating systems using RPM, DEB, or binary:
:class: copyable
:substitutions:
wget |minio-deb| -O minio.deb
curl |minio-deb| --output minio.deb
sudo dpkg -i minio.deb
.. tab-item:: Binary
@ -91,12 +92,21 @@ operating systems using RPM, DEB, or binary:
.. code-block:: shell
:class: copyable
wget https://dl.min.io/server/minio/release/linux-amd64/minio
curl https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/
Replace ``/usr/local/bin`` with the location of the existing MinIO
binary. Run ``which minio`` to identify the path if not already known.
Replace ``/usr/local/bin`` with the location of the existing MinIO binary.
Run ``which minio`` to identify the path if not already known.
You can validate the upgrade by computing the ``SHA256`` checksum of each binary and ensuring the checksum matches across all hosts:
.. code-block:: shell
:class: copyable
shasum -a 256 /usr/local/bin/minio
The output of :mc-cmd:`minio --version <minio server>` should also match across all hosts.
.. end-upgrade-minio-binary-desc

196
source/installation/upgrade-minio.rst
View File

@ -10,98 +10,102 @@ Upgrade a MinIO Deployment
:local:
:depth: 2
.. admonition:: Test Upgrades Before Applying To Production
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
MinIO **strongly discourages** performing blind updates to production
clusters. You should *always* test upgrades in a lower environment
(dev/QA/staging) *before* applying upgrades to production deployments.
Your unique deployment topology, workload patterns, or overall environment requires testing of any MinIO upgrades in a lower environment (Dev/QA/Staging) *before* applying those upgrades to Production deployments, or any other environment containing critical data.
Performing "blind" updates to production environments is done at your own risk.
Exercise particular caution if upgrading to a :minio-git:`release
<minio/releases>` that has backwards breaking changes. MinIO includes
warnings in release notes for any version known to not support
downgrades.
For MinIO deployments that are significantly behind latest stable (6+ months), consider using |SUBNET| for additional support and guidance during the upgrade procedure.
For MinIO deployments that are significantly behind latest stable
(6+ months), consider using
`MinIO SUBNET <https://min.io/pricing?ref=docs>`__ for additional support
and guidance during the upgrade procedure.
Considerations
--------------
Upgrade Checklist
-----------------
Upgrades Are Non-Disruptive
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Review all items on the following checklist before performing an upgrade on
your MinIO deployments:
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.
.. list-table::
:stub-columns: 1
:widths: 25 75
:width: 100%
"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:
* - Test in Lower Environments
- Test all upgrades in a lower environment such as a dedicated
testing, development, or QA deployment.
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.
**Never** perform blind upgrades on production deployments.
Check Release Notes
~~~~~~~~~~~~~~~~~~~
* - Upgrade Only When Necessary
- MinIO follows a rapid development model where there may be multiple
releases in a week. There is no requirement to follow these updates
if your deployment is otherwise stable and functional.
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.
Upgrade only if there is a specific feature, bug fix, or other
requirement necessary for your workload. Review the
:minio-git:`Release Notes <minio/releases>` for each Server release
between your current MinIO version and the target version.
* - Upgrades require Simultaneous Restart
- Ensure your preferred method of node management supports operating on
all nodes simultaneously.
.. include:: /includes/common-installation.rst
:start-after: start-nondisruptive-upgrade-desc
:end-before: end-nondisruptive-upgrade-desc
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
----------------------------------------------
Deployments managed using ``systemctl``, such as those created
using the MinIO :ref:`DEB/RPM packages <deploy-minio-distributed-baremetal>`,
require manual update and simultaneous restart of all nodes in the
MinIO deployment.
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**
1. Update the MinIO Binary on Each Node
.. include:: /includes/common-installation.rst
:start-after: start-upgrade-minio-binary-desc
:end-before: end-upgrade-minio-binary-desc
2. **Restart the Deployment**
2. Restart the Deployment
Run ``systemctl restart minio`` simultaneously across all nodes in the
deployment. Utilize your preferred method for coordinated execution of
terminal/shell commands.
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.
.. include:: /includes/common-installation.rst
:start-after: start-nondisruptive-upgrade-desc
:end-before: end-nondisruptive-upgrade-desc
.. 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-cmd:`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 MinIO Deployments using ``mc admin update``
--------------------------------------------------
Update Non-System Managed MinIO Deployments
-------------------------------------------
.. include:: /includes/common-installation.rst
:start-after: start-nondisruptive-upgrade-desc
:end-before: end-nondisruptive-upgrade-desc
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.
:mc-cmd:`mc admin update` is intended for baremetal (non-orchestrated)
deployments using manual management of server binaries.
The :mc-cmd:`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`.
@ -109,79 +113,25 @@ deployments using manual management of server binaries.
- For Kubernetes or other containerized environments, defer to the native
mechanisms for updating container images across a deployment.
:mc-cmd:`mc admin update` requires write access to the directory in which
the MinIO binary is saved (e.g. ``/usr/local/bin``).
The following command updates a MinIO deployment with the specified
:ref:`alias <alias>` to the latest stable release:
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 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
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:
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
Update MinIO Manually
---------------------
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:
The following steps manually download the MinIO binary and restart the
deployment. These steps are intended for fully manual baremetal deployments
without ``systemctl`` or similar process management. These steps may also
apply to airgapped or similarly internet-isolated deployments which
cannot use :mc-cmd:`mc admin update` to retrieve the binary over the network.
.. code-block:: shell
:class: copyable
1. **Add the MinIO Binary to each node in the deployment**
Follow your organizations preferred procedure for adding a new binary
to the node. The following command downloads the latest stable MinIO
binary:
.. code-block:: shell
:class: copyable
wget https://dl.min.io/server/minio/release/linux-amd64/minio
2. **Overwrite the existing MinIO binary with the newer version**
The following command sets the binary to executable and copies it to
``/usr/local/bin``. Replace this path with the location of the existing
MinIO binary:
.. code-block:: shell
:class: copyable
chmod +x minio
sudo mv minio /usr/local/bin/
3. **Restart the deployment**
Once all nodes have the updated binary, restart all nodes simultaneously
using the :mc-cmd:`mc admin service` command:
.. code-block:: shell
:class: copyable
mc admin service restart ALIAS
Replace ``ALIAS`` with the :ref:`alias <alias>` for the target deployment.
.. include:: /includes/common-installation.rst
:start-after: start-nondisruptive-upgrade-desc
:end-before: end-nondisruptive-upgrade-desc
mc update