From ffce37d2060bc983ab4d1b35b750d5088d3a43e6 Mon Sep 17 00:00:00 2001 From: Jan-Kazlouski-elastic Date: Tue, 6 Oct 2026 18:13:37 +0300 Subject: [PATCH] docs: clarify ES version compatibility and downgrade guidance (#4568) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Documentation-only change: clarify how self-managed connector service versions relate to Elasticsearch (including serverless), simplify the README compatibility table, and warn against downgrading the connector service when connector configs may have changed. No GitHub issue — follow-up from internal Slack discussion on Serverless / support matrix (matrix links to README for version pairing). ## Checklists #### Pre-Review Checklist - [x] this PR does NOT contain credentials of any kind, such as API keys or username/passwords (double check `config.yml.example`) - [x] this PR has a meaningful title - [ ] this PR links to all relevant github issues that it fixes or partially addresses — **N/A (no issue; ad-hoc docs)** - [x] if there is no GH issue, please create it. Each PR should have a link to an issue — **skipped per team agreement for this docs follow-up** - [x] this PR has a thorough description - [ ] Covered the changes with automated tests — **N/A (docs only)** - [x] Tested the changes locally — reviewed markdown rendering - [x] Added a label for each target release version (`v9.6.0`) - [ ] For bugfixes: backport safely to all minor branches still receiving patch releases — **N/A** - [x] Considered corresponding documentation changes - [ ] Contributed any configuration settings changes to the configuration reference — **N/A** - [ ] if you added or changed Rich Configurable Fields — **N/A** #### Changes Requiring Extra Attention - [ ] Security-related changes (encryption, TLS, SSRF, etc) - [ ] New external service dependencies added. ## Related Pull Requests * https://github.com/elastic/search-team/pull/15961 (release runbook — support matrix executor) ## Release Note N/A — documentation clarity for operators; no product behavior change. --------- Co-authored-by: Elastic Machine --- README.md | 41 +++++++++++++++++-------------- app/connectors_service/NOTICE.txt | 4 +-- docs/UPGRADING.md | 3 +++ 3 files changed, 27 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index f83f8cea0..f6de120be 100644 --- a/README.md +++ b/README.md @@ -98,22 +98,25 @@ The framework serves two distinct, but related use cases: ### Version compatibility with Elasticsearch > [!NOTE] -> Version compatibility will not be checked if Elasticsearch is serverless. - -The Connector will perform a version compatibility check with the configured Elasticsearch server on startup. -If the versions are incompatible, the Connector will terminate and output the incompatible versions in the shell. -If the versions are different but otherwise compatible, the Connector will output a warning in the shell but will continue operating. - -We recommend running on the same version as Elasticsearch. -However, if you want to hold back upgrading one or the other for any reason, use this table to determine if your versions will be compatible. - -| Situation | Example Connector Framework version | Example ES version | Outcome | -|---------------------------------|-------------------------------------|--------------------| ------- | -| Versions are the same. | 8.15.1.0 | 8.15.1 | 💚 OK | -| Connectors has a build version. | 8.15.1.3 | 8.15.1 | 💚 OK | -| ES patch number is newer. | 8.15.__0__.0 | 8.15.__1__ | ⚠️ Logged warning | -| ES minor number is newer. | 8.__14__.2.0 | 8.__15__.0 | ⚠️ Logged warning | -| ES major number is newer. | __8__.15.1.0 | __9__.0.0 | 🚫 Fatal error | -| ES patch number is older. | 8.15.__1__.0 | 8.15.__0__ | ⚠️ Logged warning | -| ES minor number is older. | 8.__15__.1.0 | 8.__14__.2 | 🚫 Fatal error | -| ES major number is older. | __9__.0.0.0 | __8__.15.1 | 🚫 Fatal error | +> Version compatibility is not checked when Elasticsearch is **serverless** (the connector service skips the check on startup). + +The connector service compares its version to the configured Elasticsearch server on startup. +If the versions are incompatible, the service exits and logs the mismatch. +If the versions differ but are compatible, the service logs a warning and continues. + +We recommend running the connector service on the same stack version as Elasticsearch. +Use this table to decide whether a deliberate version skew is supported. + +Do **not downgrade** the connector service to an older release than the one used when connectors were created. +If you downgrade anyway, connector configuration stored in Elasticsearch may no longer match what the older service expects — you may need to **recreate** affected connectors. + +| Situation | Example connector version | Example ES version | Outcome | +|-----------|---------------------------|--------------------|---------| +| Versions match | 8.15.1.0 | 8.15.1 | OK | +| Connector has a build suffix | 8.15.1.3 | 8.15.1 | OK | +| ES patch is newer | 8.15.__0__.0 | 8.15.__1__ | Warning | +| ES minor is newer | 8.__14__.2.0 | 8.__15__.0 | Warning | +| ES major is newer | __8__.15.1.0 | __9__.0.0 | Fatal error | +| ES patch is older | 8.15.__1__.0 | 8.15.__0__ | Warning | +| ES minor is older | 8.__15__.1.0 | 8.__14__.2 | Fatal error | +| ES major is older | __9__.0.0.0 | __8__.15.1 | Fatal error | diff --git a/app/connectors_service/NOTICE.txt b/app/connectors_service/NOTICE.txt index de6393389..109fb389d 100644 --- a/app/connectors_service/NOTICE.txt +++ b/app/connectors_service/NOTICE.txt @@ -4241,7 +4241,7 @@ Apache Software License google-auth -2.59.1 +2.60.0 Apache Software License Apache License Version 2.0, January 2004 @@ -7114,7 +7114,7 @@ THE SOFTWARE. pyspnego -0.12.3 +0.12.4 MIT MIT License diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index bb1519aca..bdfdf04a9 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -33,6 +33,9 @@ As Elastic adds new features to the framework, internal classes are renamed, mov Periodically, the [connector protocol](./CONNECTOR_PROTOCOL.md) changes. If you find a change that needs to be made at the framework level, [submit a PR](./CONTRIBUTING.md#pull-request-etiquette) for the fix, so that your branch does not differ from the Elastic-maintained remote. +### Version compatibility with Elasticsearch +See [Version compatibility with Elasticsearch](../README.md#version-compatibility-with-elasticsearch) in the repository README (including serverless and supported version skew). Do not downgrade the connector service below the version used when connectors were configured. + ### Upgrade all stack components beforehand Before upgrading `connectors`, you should first stop your running connectors services, upgrade-and-start Elasticsearch, upgrade-and-start Enterprise Search, upgrade-and-start Kibana, and only then upgrade-and-start `connectors`. As a part of Enterprise Search, the connectors framework's data migrations live inside Enterprise Search.