Core
Guides v2.x
2

Upgrading from 2.60 #

This page covers Kuzzle 2.61, starting with its first beta, 2.61.0-beta.1 (2.61.0-beta.2 adds the built-in drivers as packages). If you upgrade from an older version, read the previous upgrade notes too.

The API, the configuration and the TypeScript declarations stay compatible with v2.60.1. An Elasticsearch 7 or 8 setup needs no change. Items that may need an action on your side are marked Action.

The changelog is generated from the commits and says what was done. This page says what you may have to check.

Operators #

Elasticsearch 7 and 8 run as built-in storage drivers #

Kuzzle now talks to its database through a storage driver. Elasticsearch 7 and 8 are its built-in drivers, still selected by services.storageEngine.majorVersion: their behavior and their configuration do not change.

Since 2.61.0-beta.2, their code lives in two packages, kuzzle-storage-es-7 and kuzzle-storage-es-8, which kuzzle depends on at pinned versions. npm install brings them with Kuzzle: there is nothing to add to your package.json. npm ls kuzzle-storage-es-8 shows the version your Kuzzle uses.

A rolling upgrade from v2.60 works as before: nodes running the built-in drivers are not compared when they join the cluster.

Running another storage engine #

Setting services.storageEngine.driver to the name of a driver package, installed next to kuzzle, runs Kuzzle on that driver's engine. In that case:

  • services.storageEngine.majorVersion is ignored, and the rest of services.storageEngine is handed to the driver. If your configuration sets majorVersion too, Kuzzle logs a warning at startup: remove it;
  • Kuzzle logs [ℹ] Storage driver: <name>@<version> at startup, instead of the Elasticsearch major version;
  • Kuzzle does not start when the driver is missing, when its manifest.json is invalid, when its kuzzleVersion range excludes this Kuzzle version, or when it lacks a method of a capability it declares (the services.storage_driver.* errors);
  • a request needing a capability the driver does not declare is rejected with services.storage_driver.unsupported_capability (400).

Action, only if you use an external driver in a cluster: every node must run the same driver in the same version. A node running another one fails its startup with cluster.join.storage_driver_mismatch. Upgrading a driver therefore means restarting every node on the new version, not a rolling restart.

majorVersion is deprecated #

services.storageEngine.majorVersion is deprecated in the documentation: Kuzzle 3 will select the storage engine with driver alone. It keeps working unchanged in Kuzzle 2, where it still chooses between the built-in Elasticsearch 7 and 8 drivers, and Kuzzle logs no deprecation warning for it.

To run Elasticsearch 9, install kuzzle-storage-es-9 next to kuzzle and set services.storageEngine.driver to "kuzzle-storage-es-9".

Index cache of a joining node #

A node joining a cluster could keep, in its cache, an index or a collection that another node had deleted before it joined, and a collection write lock already released: the deletion was announced to the nodes already in the cluster only. When it loads its cache, a node now replaces it with what the storage holds.

Plugin and application developers #

Raw storage clients #

app.storage.storageClient, app.storage.StorageClient and context.constructors.ESClient are now built by the storage driver. With the built-in drivers, they give the same Elasticsearch client as before, in the same version and with the same API. With an external driver, they give that driver's engine client.

Since 2.61.0-beta.2, that client comes from the driver package's own copy of @elastic/elasticsearch. Action, only if your code checks it with instanceof against a Client class it imports itself: compare its behavior instead, or import the class from the driver's dependencies. To type it, see the drivers' TypeScript page.

New exports #

kuzzle now exports the StorageDriver contract and its types, the conformance kit describeStorageDriverConformance, and storageError, which builds Kuzzle's services.storage.* errors. They are meant for driver authors: see the Write storage drivers guide.