OpenSearch: API reference

Run real OpenSearch and Elasticsearch clusters as Docker containers. Create domains with the AWS API, query with standard REST calls.

Want a runnable walkthrough? See OpenSearch: demo & walkthrough.

Starting LocalEmu

$ localemu start

# The OpenSearch Docker backend turns on automatically when LocalEmu
# can reach a Docker socket. No env var required.
#
# Without Docker, CreateDomain still succeeds (the AWS-shaped record is
# stored) but no real OpenSearch container sits behind the endpoint.

The Docker backend wires itself up at OpenSearch provider init when Docker is reachable on the host (same pattern as ECS, EKS and RDS). To force the metadata-only path (no container, AWS-shaped responses only), point at a host without Docker or stop the Docker daemon before localemu start. The optional OPENSEARCH_DOCKER_SECURITY=1 env var flips the OpenSearch security plugin on if your test code needs to exercise the master-user / fine-grained access control paths; it is off by default to keep the demo zero-friction.

Supported Versions

Create a Domain

$ awsemu opensearch create-domain \
    --domain-name my-search \
    --engine-version OpenSearch_2.11

DomainStatus:
  DomainName: my-search
  Endpoint: localhost:49464
  EngineVersion: OpenSearch_2.11

Domain Endpoint

The endpoint is available from describe-domain. It points to the container's mapped port on localhost.

$ awsemu opensearch describe-domain --domain-name my-search

DomainStatus:
  DomainName: my-search
  Endpoint: localhost:49464
  EngineVersion: OpenSearch_2.11

Direct API Access

Use the domain endpoint to interact with the OpenSearch REST API directly. All standard endpoints are available.

Check cluster health

$ curl -s "http://localhost:49464/_cluster/health" | python3 -m json.tool

{
    "cluster_name": "docker-cluster",
    "status": "green",
    "number_of_nodes": 1,
    "active_primary_shards": 3,
    "active_shards": 3,
    "active_shards_percent_as_number": 100.0
}

Status green means the cluster is healthy and ready.

Index a document

$ curl -s -X PUT "http://localhost:49464/products/_doc/1" \
    -H 'Content-Type: application/json' \
    -d '{"name": "Widget", "price": 9.99}'

{"result": "created"}

Search across all indices

$ curl -s "http://localhost:49464/_search" | python3 -m json.tool

Single-Node Mode

Each domain runs as a single-node cluster with the security plugin disabled. This keeps startup fast and removes the need for certificates or authentication when connecting locally.

Container and volume naming

Each domain runs in a Docker container named localemu-opensearch-<domain-name> (or localemu-opensearch-<account-id>-<domain-name> in cross-account setups), with the cluster data living in a named volume localemu-opensearch-<domain-name>-data so that indexes survive container restart.

$ docker ps --filter "name=localemu-opensearch-"

CONTAINER ID   IMAGE                                  STATUS       NAMES
e3a9665b6cc6   opensearchproject/opensearch:2.11.1     Up 49s       localemu-opensearch-my-search

Health Check

Use the /_cluster/health endpoint to verify the cluster is ready. A response with "status": "green" confirms the cluster is healthy and all shards are allocated.

Cleanup

Containers are removed automatically when you delete a domain with delete-domain or when LocalEmu stops. No orphaned containers.

$ awsemu opensearch delete-domain --domain-name my-search

DomainStatus:
  DomainName: my-search
  Deleted: true

(container removed automatically)