docs: document OpenSearch Serverless startup version-check workaround - #186
Merged
Merged
Conversation
OpenSearch Serverless (aoss) exposes only a subset of the OpenSearch APIs and does not serve the root/info endpoint (GET /) that the plugin calls to detect the OpenSearch version at startup. With the default verify_os_version_at_startup true, the version probe fails with 404 and the plugin keeps retrying without ever sending data: Could not communicate to OpenSearch, resetting connection and trying again. [404] Expand the "Use OpenSearch Serverless" section to explain this and to recommend disabling the startup version check with a pinned version (verify_os_version_at_startup false / default_opensearch_version 2). Also list the main Serverless limitations: data access policy permissions, unsupported custom document IDs on TIMESERIES collections, and unsupported template/ILM/data-stream APIs. Signed-off-by: Shizuo Fujita <fujita@clear-code.com>
kenhys
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix #126
What
Expands the Use OpenSearch Serverless section of the README to document why fluent-plugin-opensearch fails to start against an
*.aoss.amazonaws.comendpoint, and how to work around it.Why
Fixes the confusion reported in #126. When targeting OpenSearch Serverless, the plugin retries indefinitely at startup with:
The root cause is the startup version detection: with the default
verify_os_version_at_startup true, the plugin calls the root/info endpoint (GET /) to detect the OpenSearch major version, but Serverless only supports a subset of the OpenSearch APIs and does not serveGET /, so it returns404. A plain OpenSearch Ruby client works because it goes straight to_bulkand never performs the version probe.