OpenSearch Service
Protocol: REST JSON
Endpoint: http://localhost:4566/2021-01-01/...
Credential scope: es
Implementation Modes
OpenSearch supports two modes controlled by FLOCI_SERVICES_OPENSEARCH_MOCK.
Mock mode (mock: true)
Domain metadata is stored in-process. No Docker containers are started. Domains appear Created: true and Processing: false immediately. Use this in CI or whenever you only need the management API shape, not a real search cluster.
Real mode (mock: false, default)
Floci starts an OpenSearch Docker container per domain, choosing the image based on the requested EngineVersion (e.g. OpenSearch_3.6 → opensearchproject/opensearch:3.6.0, Elasticsearch_7.10 → docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2). The container is exposed on a host port from the configured range (9400–9499). Once /_cluster/health returns green or yellow, the domain transitions to Created: true and the Endpoint field is populated with the container's address.
The returned Endpoint contains the host and port without a scheme. Use http:// when connecting to the local data plane.
OpenSearch 2.12+ requires an initial admin password even when the security plugin is disabled; Floci sets OPENSEARCH_INITIAL_ADMIN_PASSWORD=FlociAdmin1! automatically for those versions. The security plugin itself stays disabled.
Docker socket required
Real mode starts Docker containers. Mount the Docker socket and set the Docker network so containers can reach each other. For private registry authentication and other Docker settings see Docker Configuration.
services:
floci:
image: floci/floci:latest
volumes:
- /var/run/docker.sock:/var/run/docker.sock
ports:
- "4566:4566"
environment:
FLOCI_SERVICES_DOCKER_NETWORK: my_project_default
Supported Operations
Domain Lifecycle
| Operation | Method + Path | Description |
|---|---|---|
CreateDomain |
POST /2021-01-01/opensearch/domain |
Create a new domain |
DescribeDomain |
GET /2021-01-01/opensearch/domain/{name} |
Get domain details |
DescribeDomains |
POST /2021-01-01/opensearch/domain-info |
Batch describe domains |
DescribeDomainConfig |
GET /2021-01-01/opensearch/domain/{name}/config |
Get domain configuration |
UpdateDomainConfig |
POST /2021-01-01/opensearch/domain/{name}/config |
Update cluster config, EBS options, engine version, access policies |
DeleteDomain |
DELETE /2021-01-01/opensearch/domain/{name} |
Delete a domain |
ListDomainNames |
GET /2021-01-01/domain |
List the caller's Region's domains (supports ?engineType= filter) |
Tags
| Operation | Method + Path | Description |
|---|---|---|
AddTags |
POST /2021-01-01/tags |
Add tags to a domain by ARN |
ListTags |
GET /2021-01-01/tags/?arn= |
List tags for a domain |
RemoveTags |
POST /2021-01-01/tags-removal |
Remove tag keys from a domain |
Under IAM enforcement, a CreateDomain or CreateElasticsearchDomain that carries a TagList also needs es:AddTags on the domain it names, and its own action is checked with the tags as aws:RequestTag/<key> and aws:TagKeys: the Service Reference lists both keys for it, and the developer guide's policy for creating a domain only with a tag grants es:CreateDomain and es:AddTags. A TagList that is not a list of tags, each with a Key of 1 to 128 characters and a Value of up to 256, gets a ValidationException, on AddTags too, as the model requires both.
VPC Endpoints
OpenSearch Service-managed VPC endpoints, which Terraform's aws_opensearch_vpc_endpoint manages.
| Operation | Method + Path | Description |
|---|---|---|
CreateVpcEndpoint |
POST /2021-01-01/opensearch/vpcEndpoints |
Create an endpoint for a domain, idempotent on ClientToken |
DescribeVpcEndpoints |
POST /2021-01-01/opensearch/vpcEndpoints/describe |
Describe endpoints by id; an unknown id is a VpcEndpointErrors entry |
UpdateVpcEndpoint |
POST /2021-01-01/opensearch/vpcEndpoints/update |
Replace an endpoint's subnets and security groups |
DeleteVpcEndpoint |
DELETE /2021-01-01/opensearch/vpcEndpoints/{id} |
Delete an endpoint |
ListVpcEndpoints |
GET /2021-01-01/opensearch/vpcEndpoints |
List the Region's endpoints |
ListVpcEndpointsForDomain |
GET /2021-01-01/opensearch/domain/{name}/vpcEndpoints |
List one domain's endpoints |
Legacy Elasticsearch Service API
The 2015-01-01 API used by aws es and Terraform's aws_elasticsearch_domain is served over the same domains. It differs only in spelling: ElasticsearchVersion (bare, e.g. 7.10, stored as Elasticsearch_7.10; OS_2.11 and OpenSearch_2.11 both store and report as OpenSearch_2.11) for EngineVersion, ElasticsearchClusterConfig for ClusterConfig, and instance types ending in .elasticsearch, for InstanceType and DedicatedMasterType (t3.small.elasticsearch is stored, and reported by the 2021 API, as t3.small.search). A domain created without ElasticsearchVersion gets 7.10.
| Operation | Method + Path |
|---|---|
CreateElasticsearchDomain |
POST /2015-01-01/es/domain |
DescribeElasticsearchDomain |
GET /2015-01-01/es/domain/{name} |
DescribeElasticsearchDomains |
POST /2015-01-01/es/domain-info |
DescribeElasticsearchDomainConfig |
GET /2015-01-01/es/domain/{name}/config |
UpdateElasticsearchDomainConfig |
POST /2015-01-01/es/domain/{name}/config |
DeleteElasticsearchDomain |
DELETE /2015-01-01/es/domain/{name} |
ListDomainNames |
GET /2015-01-01/domain |
AddTags / ListTags / RemoveTags |
POST /2015-01-01/tags, GET /2015-01-01/tags/?arn=, POST /2015-01-01/tags-removal |
Versions & Instance Types
| Operation | Method + Path | Description |
|---|---|---|
ListVersions |
GET /2021-01-01/opensearch/versions |
List supported engine versions |
GetCompatibleVersions |
GET /2021-01-01/opensearch/compatibleVersions |
List valid upgrade paths |
ListInstanceTypeDetails |
GET /2021-01-01/opensearch/instanceTypeDetails/{version} |
List available instance types |
DescribeInstanceTypeLimits |
GET /2021-01-01/opensearch/instanceTypeLimits/{version}/{type} |
Get limits for an instance type |
Stubs (SDK-compatible, no-op responses)
| Operation | Notes |
|---|---|
DescribeDomainChangeProgress |
Returns empty ChangeProgressStatus |
DescribeDomainAutoTunes |
Returns empty AutoTunes list |
DescribeDryRunProgress |
Returns empty DryRunProgressStatus |
DescribeDomainHealth |
Returns ClusterHealth: Green |
GetUpgradeHistory |
Returns empty list |
GetUpgradeStatus |
Returns StepStatus: SUCCEEDED |
UpgradeDomain |
Stores new engine version, returns immediately with a generated UpgradeId |
CancelDomainConfigChange |
Returns empty CancelledChangeIds |
StartServiceSoftwareUpdate |
Returns no-op ServiceSoftwareOptions |
CancelServiceSoftwareUpdate |
Returns no-op ServiceSoftwareOptions |
Configuration
| Variable | Default | Description |
|---|---|---|
FLOCI_SERVICES_OPENSEARCH_ENABLED |
true |
Enable/disable the service |
FLOCI_SERVICES_OPENSEARCH_MOCK |
false |
true = metadata only (no Docker) |
FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE |
(unset) | Optional fixed image used for every domain regardless of EngineVersion. Useful for private registry mirrors. When unset, images resolve per-version from the built-in version map. |
FLOCI_SERVICES_OPENSEARCH_DATA_VOLUME |
(unset) | Data volume for the spawned domain containers. An absolute path bind-mounts <path>/<account-id>/<region>/<domain-name> (nested under a <namespace> subdirectory when FLOCI_DOCKER_RESOURCE_NAMESPACE is set); any other value is a Docker volume name and each domain gets its own <name>-<account-id>-<region>-<domain-name> volume of it (<name>-<namespace>-<account-id>-<region>-<domain-name> when a resource namespace is set), so no two domains or namespaced deployments sharing a Docker daemon share a data directory. Storage named here is never removed on domain delete. When unset, each domain gets a Floci-managed volume. |
FLOCI_SERVICES_OPENSEARCH_PROXY_BASE_PORT |
9400 |
Port range start for real mode |
FLOCI_SERVICES_OPENSEARCH_PROXY_MAX_PORT |
9499 |
Port range end for real mode |
FLOCI_SERVICES_OPENSEARCH_KEEP_RUNNING_ON_SHUTDOWN |
false |
Leave containers running after Floci stops |
FLOCI_SERVICES_DOCKER_NETWORK |
(unset) | Shared Docker network for all container-based services including OpenSearch |
FLOCI_STORAGE_SERVICES_OPENSEARCH_FLUSH_INTERVAL_MS |
5000 |
Flush interval (ms) |
Mock mode (CI / tests)
Use FLOCI_SERVICES_OPENSEARCH_MOCK=true when you only need the API shape:
# docker-compose.yml — CI / test environment
services:
floci:
image: floci/floci:latest
environment:
FLOCI_SERVICES_OPENSEARCH_MOCK: "true"
Emulation Behaviour
- Domain name validation: 3–28 characters, must start with a lowercase letter, only lowercase letters, digits, and hyphens.
- Regional scoping: a domain name is unique within one account and one Region, exactly as AWS scopes it. Describe, update, delete, upgrade and list resolve only in the Region the request is signed for, so the same name can exist in two Regions and one Region's requests never see, change or delete another Region's domain. Domain records persisted before regional scoping are migrated onto their Region on first use, taking it from the domain's ARN, which has always carried it.
- ARN format:
arn:aws:es:{region}:{accountId}:domain/{domainName} - Domains in a VPC: a domain created with
VPCOptionsreports its address underEndpoints.vpcand has noEndpoint, as AWS answers and as the Terraform AWS provider requires. In mock mode the address isvpc-<domain>-<suffix>.<region>.es.amazonaws.com; in real mode it is the container's address.Endpointsis left out until the address is known. - VPC endpoints:
- An id reads
aos-followed by 12 hexadecimal digits, and endpoints are scoped to an account and a Region like domains. CreateVpcEndpoint,UpdateVpcEndpointandDeleteVpcEndpointanswerCREATING,UPDATINGandDELETING, and the next read sees the endpointACTIVEor gone: the change takes effect at once.VPCIdandAvailabilityZonesare filled from the EC2 subnets the request names; a subnet EC2 does not know stays unresolved. WithoutSecurityGroupIdsthe endpoint takes the VPC's default security group, as in AWS.Endpointis the domain's own address, since Floci serves a domain at one address; no network interface is created.- A list returns every endpoint in one page, without
NextToken. A domain name that names no domain lists nothing. - An unknown domain ARN on
CreateVpcEndpoint, or the ARN of a domain in another Region, is aValidationException, and an unknown id onUpdateVpcEndpointorDeleteVpcEndpointaResourceNotFoundException, as the API reference lists for each operation. Deleting a domain does not delete its VPC endpoints.
- An id reads
- Domain ID format:
{accountId}/{domainName} Createdflag:trueimmediately in mock mode; set totrueby the readiness poller in real mode once/_cluster/healthreportsgreenoryellow.Processingflag:falseimmediately in mock mode;trueuntil the container is ready in real mode.- Engine version default:
OpenSearch_2.19 - Supported engine versions:
OpenSearch_3.7,OpenSearch_3.6,OpenSearch_3.5,OpenSearch_3.4,OpenSearch_3.3,OpenSearch_3.2,OpenSearch_3.1,OpenSearch_3.0,OpenSearch_2.19,OpenSearch_2.17,OpenSearch_2.15,OpenSearch_2.13,OpenSearch_2.11,OpenSearch_2.9,OpenSearch_2.7,OpenSearch_2.5,OpenSearch_2.3,OpenSearch_1.3,OpenSearch_1.2,OpenSearch_1.1,OpenSearch_1.0,Elasticsearch_7.10,Elasticsearch_7.9,Elasticsearch_7.8,Elasticsearch_7.7,Elasticsearch_7.4,Elasticsearch_7.1 - Elasticsearch 7.1, 7.4 and 7.7 images: published for amd64 only, so on arm64 hosts Docker runs them under emulation (slower; emulation must be enabled).
- Version validation:
CreateDomain,UpdateDomainConfig, andUpgradeDomainreject unknown engine versions withValidationException.UpgradeDomainalso rejects targets that aren't reachable from the current version per AWS's documented upgrade matrix. - Cluster defaults:
m5.large.search, 1 instance, EBS enabled with 10 GiBgp2volume. - Stored settings:
CreateDomainandUpdateDomainConfigkeep, andDescribeDomainandDescribeDomainConfigreport,ClusterConfig.ZoneAwarenessConfig,DedicatedMasterTypeandDedicatedMasterCount, EBSIopsandThroughput,AdvancedOptions,IPAddressType,OffPeakWindowOptionsandSoftwareUpdateOptions. An update changes only the members it gives;AdvancedOptionsreplaces the whole map. None of them changes how the domain's container runs. - Defaults for those settings: a domain created without them reports
IPAddressTypeipv4, an emptyAdvancedOptions, automatic software updates off, and an enabled off-peak window starting at 22:00, as AWS does for a new domain. AWS reads 10:00 P.M. in the Region's local time; Floci keeps no time zone per Region and reports 22:00 UTC. A window enabled without a start time gets the same default. - Instance type families:
t3.*/m5/m6g/m7g.*/r5/r6g/r7g.*/c5/c6g/c7g.*are EBS-backed (3584 GiB max).i3.*are local-NVMe instance-store.or1.*are S3-backed and surface a much larger volume ceiling onDescribeInstanceTypeLimits(8–36 TiB depending on size). Floci still boots one Docker container per domain regardless of family — the metadata fidelity matters for SDK clients that introspect, not for runtime data placement. - Container identity: containers are named
floci-aws-opensearch-<account-id>-<region>-<domain-name>, orfloci-aws-<namespace>-opensearch-<account-id>-<region>-<domain-name>whenFLOCI_DOCKER_RESOURCE_NAMESPACEis set. Account and Region come from the domain's stored ARN and are also recorded in its container labels. Restarts remove older containers by their persisted container ID and preserve the stored volume name. Legacy names that omit account and Region are never removed solely by name, because another domain may own them. - Container storage: each domain gets a named Docker volume (
floci-aws-opensearch-{volumeId}) created automatically. In memory mode the volume is removed on domain delete; in persistent modes it is retained unlessFLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true. SetFLOCI_SERVICES_OPENSEARCH_DATA_VOLUMEto choose the storage yourself: an absolute path bind-mounts<path>/<account-id>/<region>/<domain-name>(a directory on the Docker daemon's host), and any other value is a Docker volume name the domain gets its own<name>-<account-id>-<region>-<domain-name>volume of. WhenFLOCI_DOCKER_RESOURCE_NAMESPACEis set, the namespace is inserted into both forms, so two namespaced deployments sharing a Docker daemon never converge on one data directory through the same configured base. Linux daemon paths starting with/retain Linux path syntax when Floci runs on Windows; native Windows absolute paths retain their native handling. Before a configured bind directory is mounted, a temporary root container using the selected OpenSearch image copies ownership from the image's data directory and grants the owner write access. Only the directory itself is adjusted; existing files retain their ownership and permissions. Preparation failures abort domain startup. Storage named that way is never removed on domain delete, and a volume created when absent carries no Floci label, so neither a floci-scoped volume prune nor a testcontainers run's labelled-children sweep collects it: the operator named it, so its lifecycle is theirs. Legacy host-path mode (FLOCI_STORAGE_HOST_PERSISTENT_PATHset to an absolute path) gives each domain its own<host-path>/[<namespace>/]opensearch/floci-aws[-<namespace>]-opensearch-<account-id>-<region>-<domain-name>directory, so two domains sharing a name across Regions or accounts never share one data directory; a domain whose record predates regional scoping keeps the bare<domain-name>directory while it still exists, since that is where its data lives.
Examples
export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
# Create a domain
aws opensearch create-domain \
--domain-name my-search \
--engine-version "OpenSearch_2.11" \
--cluster-config InstanceType=m5.large.search,InstanceCount=1 \
--ebs-options EBSEnabled=true,VolumeType=gp2,VolumeSize=10
# Describe the domain
aws opensearch describe-domain --domain-name my-search
# List all domains
aws opensearch list-domain-names
# Update cluster config
aws opensearch update-domain-config \
--domain-name my-search \
--cluster-config InstanceCount=3
# Add tags
aws opensearch add-tags \
--arn arn:aws:es:us-east-1:000000000000:domain/my-search \
--tag-list Key=env,Value=dev
# List tags
aws opensearch list-tags \
--arn arn:aws:es:us-east-1:000000000000:domain/my-search
# Delete domain
aws opensearch delete-domain --domain-name my-search
SDK Example (Java)
OpenSearchClient os = OpenSearchClient.builder()
.endpointOverride(URI.create("http://localhost:4566"))
.region(Region.US_EAST_1)
.credentialsProvider(StaticCredentialsProvider.create(
AwsBasicCredentials.create("test", "test")))
.build();
// Create a domain
CreateDomainResponse created = os.createDomain(req -> req
.domainName("my-search")
.engineVersion("OpenSearch_2.11")
.clusterConfig(c -> c
.instanceType(OpenSearchPartitionInstanceType.M5_LARGE_SEARCH)
.instanceCount(1))
.ebsOptions(e -> e
.ebsEnabled(true)
.volumeType(VolumeType.GP2)
.volumeSize(10)));
System.out.println("ARN: " + created.domainStatus().arn());
// Wait for domain to be ready (real mode)
// created.domainStatus().created() == true when ready
// Describe the domain
DescribeDomainResponse desc = os.describeDomain(req -> req
.domainName("my-search"));
System.out.println("Version: " + desc.domainStatus().engineVersion());
System.out.println("Endpoint: " + desc.domainStatus().endpoint());
// List domains
os.listDomainNames(req -> req.build())
.domainNames()
.forEach(d -> System.out.println(d.domainName()));
// Delete
os.deleteDomain(req -> req.domainName("my-search"));
SDK Example (Python)
import boto3
os_client = boto3.client(
"opensearch",
endpoint_url="http://localhost:4566",
region_name="us-east-1",
aws_access_key_id="test",
aws_secret_access_key="test"
)
# Create a domain
response = os_client.create_domain(
DomainName="my-search",
EngineVersion="OpenSearch_2.11",
ClusterConfig={"InstanceType": "m5.large.search", "InstanceCount": 1},
EBSOptions={"EBSEnabled": True, "VolumeType": "gp2", "VolumeSize": 10}
)
print(response["DomainStatus"]["ARN"])
# List domains
domains = os_client.list_domain_names()
for d in domains["DomainNames"]:
print(d["DomainName"])
# Delete
os_client.delete_domain(DomainName="my-search")
Limitations
- In mock mode, no data-plane endpoints (
/_search,/_index, etc.) are served — only the management API is emulated. - No Elasticsearch-compatible management endpoints (
/2015-01-01/es/domain/...). AccessPolicies,VPCOptions,AdvancedSecurityOptions,EncryptionAtRestOptions,NodeToNodeEncryptionOptions, andDomainEndpointOptionsround-trip onCreateDomain/UpdateDomainConfig/DescribeDomain/DescribeDomainConfig, but are not enforced by the running container — Floci serves the domain over plain HTTP with the security plugin disabled regardless, andAccessPoliciesis stored verbatim without being evaluated. Round-tripping is enough for SDK clients (Terraform, CDK, Pulumi) to detect drift correctly.- Master passwords for
AdvancedSecurityOptions.MasterUserOptionsare accepted but never echoed back, matching AWS behavior. - Cross-cluster connections, packages, applications, and data sources are not supported and return
UnsupportedOperationException. - The legacy
2015-01-01API serves no VPC endpoint operations.