Elasticsearch OpenSearch Migration — check your stack for free

Migrate from Elasticsearch to OpenSearch: 6 lines in a sample docker-compose.yml that break the cutover

6 lines in a sample Elasticsearch 8.15.0 docker-compose.yml break an OpenSearch cutover, and platform engineers in teams moving off Elastic find most of them only when the new node refuses to start. Elastic moved Elasticsearch and Kibana from Apache-2.0 to SSPL / Elastic License 2.0 with version 7.11, and Elasticsearch 7.17 reached end of support on 2026-01-15. OpenSearch forked from 7.10.2 and stayed Apache-2.0, so it is where many self-managed clusters go next.

The sample file

The stack is the one you find in many repositories: one Elasticsearch node, Kibana, and Filebeat shipping container logs, all on 8.15.0.

elasticsearch:
  image: docker.elastic.co/elasticsearch/elasticsearch:8.15.0
  environment:
    - xpack.security.enabled=true
    - ELASTIC_PASSWORD=changeme
kibana:
  image: docker.elastic.co/kibana/kibana:8.15.0
  environment:
    - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
filebeat:
  image: docker.elastic.co/beats/filebeat:8.15.0

The 6 findings

Why each one matters:

• xpack settings. OpenSearch refuses to start when it reads a setting it does not know. One forgotten xpack.security.enabled stops the node at boot.
• The admin password. From OpenSearch 2.12 on, the security demo setup needs OPENSEARCH_INITIAL_ADMIN_PASSWORD. ELASTIC_PASSWORD is simply ignored.
• Kibana. OpenSearch Dashboards reads OPENSEARCH_HOSTS, not ELASTICSEARCH_HOSTS, and saved objects from Kibana newer than 7.10.2 do not import.
• Beats. OpenSearch's compatibility table covers OSS Beats up to 7.12.1. A Filebeat 8.15.0 container needs to become Fluent Bit, Data Prepper or filebeat-oss 7.12.1.

Rewritten for OpenSearch 2.17.0, the same file gives 0 findings.

The part grep misses: clients

Search the repository for elasticsearch and you get every service name, volume path and URL. The dangerous hits are in the dependency files. elasticsearch-py 7.14.0 added a product check that raises UnsupportedProductError on any server that is not Elasticsearch, and the Node, Java, Go and Ruby clients do the same. A requirements.txt with elasticsearch==8.15.1 and elasticsearch-dsl==8.15.3 gives 2 findings; the fix is opensearch-py.

Mappings and APIs

Index templates carry their own blockers: dense_vector becomes knn_vector with index.knn: true, flattened becomes flat_object (OpenSearch 2.7 and later), ILM policies become ISM policies under _plugins/_ism, and ES|QL queries on /_query need to be rewritten as PPL or SQL.

Checking your own files

OpenSearch Migration Check is a VS Code extension with 25 rules covering images, settings, clients, pipelines, mappings and APIs. Open a file and the findings appear in the Problems panel with the line number and the replacement. For a 7.x image it also counts the days since the 2026-01-15 end of support, from the date you run it. The same engine runs in the free web version in the browser.

Staying on Elastic hosting is a monthly bill: Elastic Cloud Hosted Standard starts at $99 per month. It does not move data; it lists the lines to change first.