Documentation

Upgrade a MinIO Deployment

Important

For deployments older than RELEASE.2024-03-30T09-41-56Z running with AD/LDAP enabled, you must read through the release notes for RELEASE.2024-04-18T19-09-19Z before starting this procedure. You must take the extra steps documented in the linked release as part of the upgrade.

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 transparent retry without further client-side logic. This ensures upgrades are non-disruptive to ongoing operations.

Check Release Notes

MinIO publishes 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 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:

# 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:

quay.io/minio/minio:latest

Use the Upgrade Containers using Latest Image Tag steps to upgrade your container.

The following output indicates the container was created using a specific image tag:

quay.io/minio/minio:RELEASE.2023-07-21T21-12-44Z

Use the Upgrade Containers using Specific Image Tag steps to upgrade your container.

Upgrade Containers using Latest Image Tag

  1. Update your image registry

    Pull the latest stable MinIO image for the configured image repository:

    # For docker, use docker pull
    podman pull quay.io/minio/minio:latest
    
  2. Restart the container

    You must restart the container to load the new image binary for use by MinIO:

    # For docker, use docker restart
    podman container restart CONTAINER_NAME
    
  3. Validate the Upgrade

    Use the mc admin info command to check that the MinIO container is online, operational, and reflects the installed MinIO version.

  4. Update MinIO Client

    You should upgrade your mc binary to match or closely follow the MinIO server release. You can use the mc update command to update the binary to the latest stable release:

    mc update
    

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:

    # For docker, use docker pull
    podman pull quay.io/minio/minio:RELEASE.2024-05-10T01-41-38Z
    
  2. 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.

  3. 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.

  4. Validate the Upgrade

    Use the mc admin info command to check that the MinIO container is online, operational, and reflects the installed MinIO version.

  5. Update MinIO Client

    You should upgrade your mc binary to match or closely follow the MinIO server release. You can use the mc update command to update the binary to the latest stable release:

    mc update