Compatibility rubric
Canonical Severity + Lane vocabulary for the Feature Gap Register in
report-template.md, elasticsearch-report-template.md,
solr-report-template.md, and the §7 split in assessment-shape-full-assessment.md.
Every gap-register row MUST carry both a Severity and a Lane. The Lane is what determines whether the row is a risk/blocker (something that genuinely constrains the migration) or a migration specific (something the migration plan already handles via a documented remediation). Severity is the magnitude of the behavioral impact; Lane is the framing for the customer.
§1. Severity vocabulary (BLOCKING / HIGH / MEDIUM / LOW)
| Severity | Meaning |
|---|---|
| BLOCKING | No workaround in OpenSearch; customer must rearchitect, accept feature loss, or stop. |
| HIGH | Major behavioral difference or required rewrite — affects code or queries. |
| MEDIUM | Configuration / mapping difference handled at migration time. |
| LOW | Cosmetic / negligible (terminology rename, metric name change). |
You MUST use this four-tier vocabulary verbatim in every Severity column. You MUST NOT use the legacy Breaking / Warning / Info labels — the canonical rubric is BLOCKING / HIGH / MEDIUM / LOW only, and mixed labels confuse downstream consumers.
§2. Lane vocabulary (migration-specific / risk-blocker)
| Lane | When to use |
|---|---|
| migration-specific | The item has a well-trodden, prescribed remediation that the migration plan already includes: a transformer flag, a config rewrite, an SDK/plugin substitution, a metadata-migration sanitizer, or a one-line behavior toggle. Frame these to the customer as "this is how the migration handles X" — not as a hazard. Most MEDIUM items, and HIGH items where the documented Migration Assistant for Amazon OpenSearch Service transformer (or equivalent) handles the conversion automatically, route here. |
| risk-blocker | The item genuinely constrains the migration: no known fix, capacity-plan implications, irreversible target choices, customer-action dependencies that can fail late, or "no equivalent on Serverless". BLOCKING is almost always this lane. HIGH items without a documented remediation also live here. |
Routing rule: if the migration plan already includes the fix and applies it on the customer's behalf (transformer, sanitizer, default override), the row is migration-specific. If the customer must make a decision, accept feature loss, or rearchitect to land it, the row is risk-blocker.
§3. Combining Severity + Lane
| Severity \ Lane | migration-specific | risk-blocker |
|---|---|---|
| BLOCKING | (rare — only when an automatic remediation exists for an otherwise-blocking item) | typical — most BLOCKING items |
| HIGH | typical when transformer-handled | typical when manual rewrite |
| MEDIUM | typical | uncommon |
| LOW | typical | uncommon |
Examples grounded in the always-flag list at assessment-workflow.md §3:
| Feature | Severity | Lane | Why |
|---|---|---|---|
q.op=AND |
HIGH | migration-specific |
One-line default_operator: AND rewrite; documented; transformer applies it. |
fielddata: true on text |
BLOCKING | migration-specific |
OOM risk if untouched, but Migration Assistant for Amazon OpenSearch Service's metadata transformer strips it automatically and adds the .keyword subfield. |
| Snapshot from ES ≥ 7.11 | BLOCKING | risk-blocker |
License lockout — no snapshot path exists; customer must change tools (Migration Assistant Historical Data Migration / _reindex). |
_type placeholder (ES 7) |
HIGH | migration-specific |
Migration Assistant metadata transformer flattens automatically. |
Custom Java JARs in <lib> |
HIGH | risk-blocker |
Manual port to OS plugin API; not supported on Serverless NextGen — constrains target choice. |
| NMSLIB engine on OS source crossing to OS 3.x | HIGH | risk-blocker |
Engine removed; reindex into FAISS required before crossing 3.x. |
<copyField> |
LOW | migration-specific |
One-line copy_to mapping change; trivial. |
| Cross-Cluster Search (CCS) | HIGH | risk-blocker |
Not supported on Serverless; partial on Managed — constrains target. |
§4. Plugin rename cheat-sheet
The Open Distro → OpenSearch plugin rename is mostly mechanical but is cited often enough to warrant a single canonical lookup.
| Open Distro plugin | OpenSearch plugin | Notes |
|---|---|---|
opendistro-anomaly-detection |
opensearch-anomaly-detection |
Drop-in. |
opendistro-alerting |
opensearch-alerting |
API contract preserved; Watcher rewrite is a separate task. |
opendistro-asynchronous-search |
opensearch-asynchronous-search |
Drop-in. |
opendistro-index-management |
opensearch-index-management |
ISM policies; ILM JSON does NOT import. |
opendistro-job-scheduler |
opensearch-job-scheduler |
Drop-in. |
opendistro-knn |
opensearch-knn |
Engine selection rules in vector-knn.md. |
opendistro-observability |
opensearch-observability |
Drop-in. |
opendistro-performance-analyzer |
opensearch-performance-analyzer |
Drop-in. |
opendistro-reports-scheduler |
opensearch-reports-scheduler |
Drop-in. |
opendistro-security |
opensearch-security |
Config schema preserved; backend wiring may differ on Managed. |
opendistro-security-advanced-modules |
opensearch-security |
Folded into opensearch-security. |
opendistro-sql |
opensearch-sql |
Drop-in; verify edge cases. |
The supported-plugin list on managed AOS is [verify] against supported-plugins.html — the plugin catalog drifts.
