diff --git a/source/includes/common-installation.rst b/source/includes/common-installation.rst index de462847..2b088247 100644 --- a/source/includes/common-installation.rst +++ b/source/includes/common-installation.rst @@ -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 ` should also match across all hosts. .. end-upgrade-minio-binary-desc diff --git a/source/installation/upgrade-minio.rst b/source/installation/upgrade-minio.rst index 0dae5490..d5a63708 100644 --- a/source/installation/upgrade-minio.rst +++ b/source/installation/upgrade-minio.rst @@ -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 - ` 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 `__ 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 ` 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 ` 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 ` 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 `, -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 `. -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 ` 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 ` to the latest stable release: +The following command updates a MinIO deployment with the specified :ref:`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 ` for the target deployment. - - .. include:: /includes/common-installation.rst - :start-after: start-nondisruptive-upgrade-desc - :end-before: end-nondisruptive-upgrade-desc + mc update