Migrating to Cassandra 4.0.x and OpenSearch 1.3.x

This document describes operator-facing changes when moving from the legacy 6.8 line on Cassandra 3.11.x to the modern stack maintained at https://elassandra.org/ (Cassandra 4.0.x + OpenSearch 1.3.x).

There is no supported in-place upgrade of the embedded Lucene indices from the legacy 6.8 line to OpenSearch 1.3. Plan one of:

  • Rebuild search from Cassandra — use Elassandra’s Cassandra-backed tables as source of truth and recreate indices/mappings on the new cluster (typical for deployments that always index from C*).

  • Reindex via snapshot/restore — only if you have a compatible snapshot workflow; legacy 6.8 indices are not directly compatible with OpenSearch 1.3 Lucene codecs. Expect a full reindex using an external tool or dual-write period.

HTTP API and clients

  • OpenSearch 1.3 follows the typeless REST conventions used by the current OpenSearch 1.x line, not the legacy 6.8 APIs.

  • Remove document types from URLs and mappings and standardize on the single _doc model.

  • Use OpenSearch REST clients aligned with OpenSearch 1.3.

Dashboards

  • The legacy 6.8 dashboard application is not compatible with OpenSearch. Use OpenSearch Dashboards 1.x aligned with your server minor version.

Java runtime

  • Target runtime is Java 11 (or newer LTS supported by your chosen Cassandra 4.0 and OpenSearch 1.3 patch releases).

Cassandra

  • All nodes in an Elassandra cluster must run the same Elassandra build (Cassandra 4.0–based).

  • Review secondary index and schema extension behavior after upgrade; validate rebuild and repair procedures in a staging cluster.

Implementation status (repository)

Component

Pin / branch (check buildSrc/version.properties and submodules)

Elassandra application repo

incloudsio/elassandra (integration branches may track modernization work).

Cassandra fork

incloudsio/cassandra — 4.0 line cassandra-4.0.x-elassandra (Maven groupId io.inclouds.cassandra), which is the baseline used by this repository today.

OpenSearch port

Main server/ tree is OpenSearch 1.3.20-based; keep scripts/opensearch-port-bootstrap.sh and the side-car flow as the rebase harness for future upstream updates and regression waves.

Legacy version verify

Root Gradle verifyVersions still validates both the legacy ancestry and the OpenSearch 1.x line. The optional -Pelassandra.skipLegacyVersionVerify escape hatch remains only for exceptional local debugging.

Target pins (modern stack)

These values are recorded in buildSrc/version.properties as opensearch_port and lucene_opensearch (they match upstream OpenSearch 1.3.20). The Cassandra 4.0 artifact version tracks server/cassandra/build.xml base.version after scripts/use-cassandra-40-submodule.sh (typically 4.0.20 on branch cassandra-4.0.x-elassandra).

Operator validation (staging)

  • Exercise rebuild-from-Cassandra or full reindex flows before production; Lucene indices are not upgraded in place from the legacy 6.8 line to OpenSearch 1.3.

Suggested staging checklist

  1. Provision a non-production cluster with the target Elassandra build (same C* + search versions as production).

  2. Snapshot or otherwise record baseline index names, mappings, and critical CQL schemas.

  3. Run your chosen migration path: rebuild indices from Cassandra (nodetool / Elassandra rebuild procedures as documented for your release) or full reindex into fresh OpenSearch 1.3–compatible indices.

  4. Validate search correctness (spot queries, aggregations, per–DC routing if used) and operational metrics (heap, GC, repair).

  5. Roll dashboards and REST clients to OpenSearch 1.3-compatible APIs and retire legacy-only plugins.

Further reading

  • Cassandra fork inventory (legacy 3.11 line to Apache 4.0.x) — Cassandra-side commit inventory and 4.0 branch strategy.

  • Cassandra 4.0.x porting playbook — step-by-step patch export, 4.0 clone, and git am workflow.

  • Cassandra 4.0 JVM port (Elassandra integration code) — Elassandra Java integration points for Cassandra 4.0.

  • OpenSearch 1.3.x porting guide (codebase map) — developer map for rebasing onto OpenSearch 1.3.x.

  • Repository scripts: scripts/check-cassandra-submodule.sh (version alignment), scripts/use-cassandra-40-submodule.sh (move submodule to Cassandra 4.0), scripts/clone-opensearch-upstream.sh / scripts/opensearch-port-bootstrap.sh (OpenSearch 1.3.20 port branch), scripts/sync-elassandra-to-opensearch-sidecar.sh / scripts/rewrite-elassandra-imports-for-opensearch.sh (copy org.elassandra.* into the side-car), scripts/build-elassandra-cassandra-jar.sh (Ant Cassandra jar for the side-car classpath), scripts/sync-elassandra-fork-minimal-to-opensearch-sidecar.sh (minimal org.opensearch fork stubs), scripts/patch-opensearch-forbidden-deps-for-elassandra.sh (temporarily allow Guava in the side-car tree), scripts/opensearch-sidecar-prepare.sh (sync + patches only; no Gradle), scripts/opensearch-sidecar-compile-try.sh (runs :server:compileJava, :test:framework:compileJava, and :server:compileTestJava in the side-car by default; set OPENSEARCH_SIDECAR_TASKS=:server:compileJava to skip test compilation; uses gradle/opensearch-sidecar-elassandra.init.gradle and GRADLE_OPTS), scripts/opensearch-sidecar-test-try.sh (optional :server:test slice; integration tests expect full Elassandra bootstrap), scripts/export-elassandra-mapper-fork-for-opensearch-merge.sh (export forked index/mapper for merge), scripts/print-opensearch-port-pins.sh (target pins).

Packaging (when the OpenSearch port ships)

  • Revisit tarball, deb, and rpm naming and keep user-visible branding aligned with OpenSearch.

  • Rebuild container images from the merged tree; re-check JVM flags for Cassandra 4.0 plus the embedded search engine.

  • Pins: ./scripts/print-opensearch-port-pins.sh prints opensearch_port / lucene_opensearch from buildSrc/version.properties; full artifact convergence is tracked in OpenSearch 1.3.x porting guide (codebase map).