OpenSearch (Elastic)



OpenSearch is a scalable, open-source search and analytics suite. It's used for various purposes, including full-text search, log analytics, and real-time application monitoring. As a fully managed service, Stacktape makes it easy to deploy, operate, and scale OpenSearch clusters in the AWS Cloud.

Under the hood, Stacktape uses AWS OpenSearch Service, which was previously known as Amazon Elasticsearch Service.

Basic configuration

To set up a basic OpenSearch domain, you only need to specify the resource type and the desired OpenSearch version.

Defaults to a single m4.large.search node if not specified.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"

Connecting to an OpenSearch domain

You can connect to your OpenSearch domain either from anywhere on the internet or exclusively from resources within your stack's VPC, depending on your accessibility configuration.

In either case, you need valid IAM credentials. You can grant these to your stack's resources using the connectTo property.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      accessibility:
        accessibilityMode: vpc

  webService:
    type: web-service
    properties:
      # ...
      connectTo:
        - myOpenSearch

A web service connected to an OpenSearch domain.

import { Client, Connection } from "@opensearch-project/opensearch";
import { defaultProvider } from "@aws-sdk/credential-provider-node";
import aws4 from "aws4";

// The OpenSearch domain endpoint is automatically injected as an environment variable
const host = `https://${process.env.STP_MY_OPEN_SEARCH_DOMAIN_ENDPOINT}`;

const createAwsConnector = (credentials, region) => {
  class AmazonConnection extends Connection {
    buildRequestObject(params) {
      const request = super.buildRequestObject(params) as any;
      request.service = "es";
      request.region = region;
      request.headers = request.headers || {};
      request.headers["host"] = request.hostname;

      return aws4.sign(request, credentials);
    }
  }
  return {
    Connection: AmazonConnection
  };
};

const getClient = async () => {
  const credentials = await defaultProvider()();
  return new Client({
    ...createAwsConnector(credentials, "eu-west-1"),
    node: host
  });
};

async function search() {
  const client = await getClient();
  await client.indices.create({
    index: "test-index"
  });
}

Example code for connecting to an OpenSearch domain.

Data nodes

You can configure the instance type and number of data nodes in your cluster.

Data nodes store data and handle queries. For production, pair with dedicated master nodes.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3

OpenSearch version

You can specify the version of OpenSearch you want to use.

OpenSearch engine version. Pin this to avoid surprises when the default changes.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"

Dedicated master nodes

For production environments, it's recommended to use dedicated master nodes to improve cluster stability.

Recommended for clusters with 3+ data nodes to prevent split-brain. Use an odd count (3, 5, or 7).

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3
        dedicatedMasterType: r6g.large.search
        dedicatedMasterCount: 3

Warm nodes

Warm nodes provide a cost-effective way to store large amounts of read-only data.

Data on warm nodes is still searchable but with higher query latency. Great for retaining old logs or time-series data at lower cost.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3
        warmType: ultrawarm1.medium.search
        warmCount: 2

Multi-AZ with standby

You can enable a multi-AZ deployment with a standby Availability Zone for high availability.

Distributes nodes across 3 AZs with one as standby. The standby takes over instantly during failures without re-balancing. Requires: version 1.3+, 3 dedicated master + data nodes, GP3/SSD instances.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3
        dedicatedMasterType: r6g.large.search
        dedicatedMasterCount: 3
        standbyEnabled: true

Restrict access

You can restrict access to your OpenSearch domain to a specific VPC.

Even in internet mode, access requires IAM credentials. VPC modes add network-level isolation. Warning: you cannot switch between internet and vpc/scoping-workloads-in-vpc after creation.

  • internet: Accessible from anywhere (still requires IAM credentials).
  • vpc: Only accessible from resources inside your VPC (functions with joinDefaultVpc: true, containers, batch jobs).
  • scoping-workloads-in-vpc: Like vpc, but also requires security-group access via connectTo.

Cannot be changed after creation — switching between internet and VPC modes requires a new domain.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      accessibility:
        accessibilityMode: vpc

Logging

You can enable and configure logging for your OpenSearch domain.

Error logs, search slow logs, and indexing slow logs. Sent to CloudWatch automatically.

OpenSearchLogConfigurationAPI referenceParent:OpenSearchDomain
errorLogs

Error logs — script compilation errors, invalid queries, indexing issues, snapshot failures.

Type: OpenSearchLogRetentionSettings

searchSlowLogs

Search slow logs — queries exceeding thresholds you configure in OpenSearch index settings.

Type: OpenSearchLogRetentionSettings

indexSlowLogs

Indexing slow logs — indexing operations exceeding thresholds you configure in OpenSearch index settings.

Type: OpenSearchLogRetentionSettings

OpenSearchLogRetentionSettingsAPI referenceParent:OpenSearchLogConfiguration
disabled

Disable this log type.

Type: boolean

retentionDaysDefault: 14

Days to keep logs in CloudWatch before automatic deletion.

Type: number ENUM

Possible values: 13571430609012015018036540054573118273653

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      logging:
        errorLogs:
          retentionDays: 30
        searchSlowLogs:
          retentionDays: 14
        indexSlowLogs:
          disabled: true

Storage

You can configure the storage for your OpenSearch domain using EBS volumes.

iops and throughput settings only apply to GP3 volumes.

OpenSearchStorageAPI referenceParent:OpenSearchDomain
sizeRequired

EBS volume size per data node in GiB. Min/max depends on instance type (typically 10–16,384 GiB).

Type: number

iopsDefault: 3000

Provisioned IOPS per data node. GP3 volumes only.

Type: number

throughputDefault: 125

Provisioned throughput per data node in MiB/s. GP3 volumes only.

Type: number

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3
      storage:
        size: 100
        iops: 3000
        throughput: 200

Disable Multi-AZ awareness

You can disable Multi-AZ awareness if you don't need the high availability features.

Multi-AZ is auto-enabled for clusters with 2+ nodes. It distributes nodes across availability zones so the cluster survives an AZ outage.

resources:
  myOpenSearch:
    type: open-search-domain
    properties:
      version: "2.17"
      clusterConfig:
        instanceType: r6g.large.search
        instanceCount: 3
        multiAzDisabled: true

API Reference

OpenSearchDomainAPI reference
typeRequired
No description

Type: string "open-search-domain"

properties.versionDefault: '2.17'

OpenSearch engine version. Pin this to avoid surprises when the default changes.

Type: string ENUM

Possible values: 1.01.11.21.32.112.132.152.172.32.52.72.9

properties.clusterConfig

Instance types, counts, and cluster topology (data nodes, master nodes, warm storage).

Type: OpenSearchClusterConfig

Defaults to a single m4.large.search node if not specified.

properties.storage

EBS volume size, IOPS, and throughput per data node. Only for EBS-backed instance types.

Type: OpenSearchStorage

iops and throughput settings only apply to GP3 volumes.

properties.userPool

Name of a user-pool resource in your config. Enables login to OpenSearch Dashboards via Cognito.

Type: string

properties.logging

Error logs, search slow logs, and indexing slow logs. Sent to CloudWatch automatically.

Type: OpenSearchLogConfiguration

properties.accessibility

Network access mode: public internet (default), VPC-only, or VPC with security-group scoping.

Type: OpenSearchAccessibility

Even in internet mode, access requires IAM credentials. VPC modes add network-level isolation. Warning: you cannot switch between internet and vpc/scoping-workloads-in-vpc after creation.

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true
OpenSearchClusterConfigAPI referenceParent:OpenSearchDomain
instanceTypeRequired

Instance type for data nodes (e.g., t3.medium.search, r6g.large.search).

Type: string

Data nodes store data and handle queries. For production, pair with dedicated master nodes.

instanceCountRequired

Number of data nodes. More nodes = more storage capacity and query throughput.

Type: number

dedicatedMasterType

Instance type for dedicated master nodes (e.g., m5.large.search). Manages cluster state, not data.

Type: string

Recommended for clusters with 3+ data nodes to prevent split-brain. Use an odd count (3, 5, or 7).

dedicatedMasterCount

Number of dedicated master nodes. Must be odd (3, 5, or 7) for quorum.

Type: number

warmType

Instance type for warm (UltraWarm) nodes — cheaper storage for infrequently accessed data.

Type: string

Data on warm nodes is still searchable but with higher query latency. Great for retaining old logs or time-series data at lower cost.

warmCount

Number of warm (UltraWarm) nodes for lower-cost storage of older data.

Type: number

multiAzDisabled

Disable Multi-AZ replication. Not recommended — reduces availability and data durability.

Type: boolean

Multi-AZ is auto-enabled for clusters with 2+ nodes. It distributes nodes across availability zones so the cluster survives an AZ outage.

standbyEnabled

Enable Multi-AZ with a standby AZ for highest availability (99.99% SLA).

Type: boolean

Distributes nodes across 3 AZs with one as standby. The standby takes over instantly during failures without re-balancing. Requires: version 1.3+, 3 dedicated master + data nodes, GP3/SSD instances.

OpenSearchAccessibilityAPI referenceParent:OpenSearchDomain
accessibilityModeDefault: internetRequired

How the domain can be reached.

Type: string ENUM

Possible values: internetscoping-workloads-in-vpcvpc

  • internet: Accessible from anywhere (still requires IAM credentials).
  • vpc: Only accessible from resources inside your VPC (functions with joinDefaultVpc: true, containers, batch jobs).
  • scoping-workloads-in-vpc: Like vpc, but also requires security-group access via connectTo.

Cannot be changed after creation — switching between internet and VPC modes requires a new domain.