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 a8acf13e1..8d98e35b9 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.