More S3-compat rewording#6725
Conversation
Apparently some users still struggle to understand this bit. Reordered the text a bit to try and make it even harder to misinterpret.
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
🔍 Preview links for changed docs |
Vale Linting ResultsSummary: 1 warning found
|
| File | Line | Rule | Message |
|---|---|---|---|
| deploy-manage/tools/snapshot-and-restore/s3-repository.md | 219 | Elastic.DontUse | Don't use 'please'. |
The Vale linter checks documentation changes against the Elastic Docs style guide.
To use Vale locally or report issues, refer to Elastic style guide for Vale.
shainaraskas
left a comment
shainaraskas
left a comment
There was a problem hiding this comment.
reorg lgtm. one small thing you could drop from the original content to make the docs a little friendlier (take or leave)
| 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.endpoint` to a URL which starts with `http://`. | ||
|
|
||
| There are many systems, including some from very well-known storage vendors, which claim to offer an S3-compatible API despite failing to emulate S3's behavior in full. If you are using such a system for your snapshots, consider using a [shared filesystem repository](shared-file-system-repository.md) based on a standardized protocol such as NFS to access your storage system instead. The `s3` repository type requires full compatibility with S3. In particular it must support the same set of API endpoints, with the same parameters, return the same errors in case of failures, and offer consistency, performance, and reliability at least as good as S3 even when accessed concurrently by multiple nodes. You will need to work with the supplier of your storage system to address any incompatibilities you encounter. Don't report {{es}} issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository. | ||
| The `s3` repository type requires your storage API to be _fully_ compatible with AWS S3. This means it must support all the same API endpoints, with all the same parameters, return the same errors in case of failures, and offer consistency, performance, and reliability at least as good as S3 even when accessed concurrently by multiple nodes. Some storage products, including some from very well-known storage vendors, claim to offer a S3-compatible API but actually only support a subset of its features. Others offer an API which matches that of AWS S3 but with different behavior, especially when accessed concurrently. Such storage products are demonstrably _not_ fully S3-compatible, despite claims from their vendors. Using a storage product which is not fully S3-compatible puts your snapshot data at risk. If you are using such a system for your snapshots, consider using a [shared filesystem repository](shared-file-system-repository.md) based on a standardized protocol such as NFS to access your storage system instead. Ensure that your storage supplier offers a full compatibility guarantee. Work with the supplier of your storage system to address any incompatibilities you encounter. Don't report {{es}} issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository. |
There was a problem hiding this comment.
nit: can we possibly cut this bit? it's a little severe
Don't report {{es}} issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository.
| The `s3` repository type requires your storage API to be _fully_ compatible with AWS S3. This means it must support all the same API endpoints, with all the same parameters, return the same errors in case of failures, and offer consistency, performance, and reliability at least as good as S3 even when accessed concurrently by multiple nodes. Some storage products, including some from very well-known storage vendors, claim to offer a S3-compatible API but actually only support a subset of its features. Others offer an API which matches that of AWS S3 but with different behavior, especially when accessed concurrently. Such storage products are demonstrably _not_ fully S3-compatible, despite claims from their vendors. Using a storage product which is not fully S3-compatible puts your snapshot data at risk. If you are using such a system for your snapshots, consider using a [shared filesystem repository](shared-file-system-repository.md) based on a standardized protocol such as NFS to access your storage system instead. Ensure that your storage supplier offers a full compatibility guarantee. Work with the supplier of your storage system to address any incompatibilities you encounter. Don't report {{es}} issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository. | |
| The `s3` repository type requires your storage API to be _fully_ compatible with AWS S3. This means it must support all the same API endpoints, with all the same parameters, return the same errors in case of failures, and offer consistency, performance, and reliability at least as good as S3 even when accessed concurrently by multiple nodes. Some storage products, including some from very well-known storage vendors, claim to offer a S3-compatible API but actually only support a subset of its features. Others offer an API which matches that of AWS S3 but with different behavior, especially when accessed concurrently. Such storage products are demonstrably _not_ fully S3-compatible, despite claims from their vendors. Using a storage product which is not fully S3-compatible puts your snapshot data at risk. If you are using such a system for your snapshots, consider using a [shared filesystem repository](shared-file-system-repository.md) based on a standardized protocol such as NFS to access your storage system instead. Ensure that your storage supplier offers a full compatibility guarantee. |
There was a problem hiding this comment.
it's a little severe
Unfortunately severe is what we need here - even with this warning in place we still waste a lot of time redirecting users to their storage vendors for bug fixes.
There was a problem hiding this comment.
(i.e. before we added it, it was even worse)
There was a problem hiding this comment.
@DaveCTurner : I agree with being severe here, as I was suspecting this comes from support related issues.
But i'd suggest to maybe highlight that part in an admonition Support on S3-compatible repositories or just a note, explaining up to what level the S3-compatible services are supported and what's expected from Elastic to work on this type of issues (reproducing the issue in a genuine AWS S3 repository).
The problem with the current statement is that it's a bit hidden at the end of a huge paragraph:
There was a problem hiding this comment.
Sure, I'm open to further improvements here but I have severe doubts that the users in question are struggling to find this information because of how it's structured. They mostly don't look at these docs in the first place. It's vital that we have these sentences in the docs so that we can quote them in support cases, but feel free to suggest a better way to format this.
3 participants
Apparently some users still struggle to understand this bit. Reordered
the text a bit to try and make it even harder to misinterpret.