An OpenSearch Cluster is a managed OpenSearch 3.9.0 deployment split into two dedicated roles: a cluster-manager quorum of 1 or 3 virtual machines that holds the metadata and runs the elections, and 1..N data nodes that hold the shards and answer queries. Every member runs on its own virtual machine, and the cluster is described as one resource — spec.dataNodes and spec.clusterManagers each hold one entry per member, listing only its name and subnet. There is no combined cluster-manager+data node and no mode flag: a data node under merge, GC or disk pressure would stall the metadata quorum while every shard kept answering, which is a silent outage, so the platform ships one topology and one playbook path.

Key concepts

• Two roles, sized independently — data nodes hold your data, cluster managers hold only the cluster metadata. Sizing is one offer triplet per role (dataVmOfferId/dataVolumeOfferId/dataVolumeSizeGiB and the manager* equivalents) rather than per member, so a role's members are interchangeable by design. An omitted offer is resolved to that role's default server-side and written back, never left null

• Cluster managers: exactly 1 or 3, never 2 or 4 — a majority is more than half, so an even count tolerates no more failures than the odd count below it while costing more. 1 is a documented non-HA tier (no quorum HA) that can be grown to 3; both joiners arrive in a single request, because 2 is not a valid quorum

• Data nodes: 1..N, scale-out only — a modify may add data nodes. OpenSearch has no scale-in path here, so removing one is rejected outright rather than silently ignored. The minimum cluster is therefore 2 VMs: 1 manager + 1 data node

• Node name is the real identity — the server resolves each entry against this cluster's existing members by name and reuses the same member (and its VM) when it matches. Renaming is indistinguishable from remove+add, and since scale-in is refused the rename is rejected rather than rebuilt, so do not rename a member you want to keep

• Indices are yours — there is no shard, replica, ISM or index-template field on this resource. The platform sets only cluster.default_number_of_replicas cluster-wide: 0 on a single-data-node cluster (so its indices are not permanently yellow) and 1 otherwise. Fields you cannot set are not offered rather than accepted and ignored

• Public access is TLS-only — private by default. Setting spec.createPublicIpv4 attaches a floating IP to every data node so the REST port 9200 is reachable from outside the VPC; a cluster manager never receives one, because client traffic must not be sent to the voting configuration. There is no plaintext listener at all: even a private client pins the cluster CA

• The CA certificate is in status — status.caCertificate is the credential-free thing a client pins (--cacert, or verify_certs plus ca_certs). It is minted once at create and never regenerated on reconcile, so a client that pinned it keeps working

• No cluster-wide credential on this resource — the break-glass admin credential is generated and stored server-side only. Create an OpenSearch User to get a real, tenant-facing credential

• Disk watermarks are platform-managed — past flood_stage (95%) every index with a shard on a full node gets a read-only block and writes start failing with index read-only. That threshold is deliberately not settable: it is the last thing between a tenant and a full volume. The low/high watermarks are tunable through a Parameter Set — see the error's own explanation if you try to set flood_stage there

• Backups and Dashboards are not in v1 — there is no snapshot repository, no restore and no OpenSearch Dashboards deployment. A cluster is a derived copy of data you can re-index, not a system of record

Notes

• Adding a data node does not raise number_of_replicas on indices that already exist. The platform changes the cluster default, which applies to indices created from then on — raising an existing index is your own PUT <pattern>/_settings

• On a single-data-node cluster there is no redundancy at all, and with backups deferred there is no restore path. Treat three data nodes as the production floor and raise the data-node offer before the node count

• index.number_of_shards is final for an index: it can only be set at creation, so plan the shard count up front — over-sharding a small cluster is the other classic mistake

• action.destructive_requires_name is true, so DELETE /logs-* and DELETE /_all are refused. Delete by explicit name, or use _delete_by_query

Examples

One cluster manager and two data nodes — the smallest topology that is both real and shard-safe, plus a parameter set and an index-granted user.

Terraform

Python SDK

kc CLI

Related pages

Resource docs

• Parameter Set resource docs
• OpenSearch User resource docs
• VPC Subnet resource docs

Examples

• CLI OpenSearch example
• Terraform OpenSearch example
• Python SDK OpenSearch example

Guides

• Migrating a cluster into this service