Skip to content

Clarify MinIO nonfunctional requirements #2021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

DaveCTurner
Copy link
Contributor

It is apparently nonobvious that if you run MinIO on poorly-configured
infrastructure then you're not going to get S3-like performance. This
commit spells out that the responsibility for the infrastructure
underneath MinIO lies with the user.

It is apparently nonobvious that if you run MinIO on poorly-configured
infrastructure then you're not going to get S3-like performance. This
commit spells out that the responsibility for the infrastructure
underneath MinIO lies with the user.
@DaveCTurner DaveCTurner requested a review from ywangd July 3, 2025 09:47
@DaveCTurner DaveCTurner requested a review from a team as a code owner July 3, 2025 09:47
@DaveCTurner DaveCTurner added the documentation Improvements or additions to documentation label Jul 3, 2025
Copy link

github-actions bot commented Jul 3, 2025

🔍 Preview links for changed docs

Copy link
Contributor

@yetanothertw yetanothertw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, the change looks good!

I've left a minor suggestion for style and clarity, in case you'd like to implement it.

@@ -380,7 +380,7 @@ There are a number of storage systems that provide an S3-compatible API, and the

By default {{es}} communicates with your storage system using HTTPS, and validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the JVM-wide truststore includes an entry for your repository. If you wish to use unsecured HTTP communication instead of HTTPS, set `s3.client.CLIENT_NAME.protocol` to `http`.

[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Note however that the performance, reliability and durability of a MinIO-backed repository are dependent on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure, and configure MinIO, so that your MinIO-backed repository has performance, reliability and durability characteristics which match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Note however that the performance, reliability and durability of a MinIO-backed repository are dependent on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure, and configure MinIO, so that your MinIO-backed repository has performance, reliability and durability characteristics which match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. However, note that the performance, reliability, and durability of a MinIO-backed repository depend on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure and configure MinIO in a way that ensures your MinIO-backed repository has the performance, reliability, and durability characteristics that match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.

minor style suggestion to improve readability

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DaveCTurner , what if we include the entire MinIO paragraph in a highlighted note with three paragraphs inside?

Something like:

::::{admonition} MinIO considerations
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3.

Note that the performance, reliability, and durability of a MinIO-backed repository depend on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure and configure MinIO in a way that ensures your MinIO-backed repository has the performance, reliability, and durability characteristics that match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team.

Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
::::

Considering that the section is about compatible S3 services in general, but MinIO is actually the most important for us, I think highlighting this paragraph would be beneficial for the doc, and could look like:

image

Copy link
Contributor

@eedugon eedugon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a comment to change a bit the format of the paragraph, for your consideration.

I believe it's worthy to highlight the statements about MinIO in the doc, also considering that we have a doc that covers MinIO with ECE and refers to this section of the doc too.

@@ -380,7 +380,7 @@ There are a number of storage systems that provide an S3-compatible API, and the

By default {{es}} communicates with your storage system using HTTPS, and validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the JVM-wide truststore includes an entry for your repository. If you wish to use unsecured HTTP communication instead of HTTPS, set `s3.client.CLIENT_NAME.protocol` to `http`.

[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3. Note however that the performance, reliability and durability of a MinIO-backed repository are dependent on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure, and configure MinIO, so that your MinIO-backed repository has performance, reliability and durability characteristics which match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team. Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DaveCTurner , what if we include the entire MinIO paragraph in a highlighted note with three paragraphs inside?

Something like:

::::{admonition} MinIO considerations
[MinIO](https://minio.io) is an example of a storage system that provides an S3-compatible API. The `s3` repository type allows {{es}} to work with MinIO-backed repositories as well as repositories stored on AWS S3.

Note that the performance, reliability, and durability of a MinIO-backed repository depend on the properties of the underlying infrastructure, as well as on the details of your MinIO configuration. You must design your storage infrastructure and configure MinIO in a way that ensures your MinIO-backed repository has the performance, reliability, and durability characteristics that match AWS S3. If you need assistance with your MinIO configuration, please contact the MinIO support team.

Other S3-compatible storage systems may also work with {{es}}, but these are not covered by the {{es}} test suite.
::::

Considering that the section is about compatible S3 services in general, but MinIO is actually the most important for us, I think highlighting this paragraph would be beneficial for the doc, and could look like:

image

Copy link
Member

@ywangd ywangd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants