OpenSearch Integration

Connect OpenSearch to let agents search logs, read index mappings, and run PPL and SQL log queries directly during investigations. You can also forward OpenSearch alerting monitor notifications to Autoheal via webhook so they are ingested, grouped, and available for triage on the Alerts page.

This integration works with self-hosted OpenSearch and Amazon OpenSearch Service (managed domains).

note

OpenSearch vs. Elasticsearch — pick the right card. OpenSearch forked from Elasticsearch 7.10 and is a different product: it uses the PPL/SQL query languages (not Elasticsearch's ES|QL) and a different auth model. Use this card for OpenSearch; use the Elasticsearch card for an Elasticsearch cluster. If you point this card at an Elasticsearch cluster, Test Connection will warn you.

Capabilities

Once connected, agents can:

Capability	Description
Search Logs	Run the full query DSL with filters, aggregations, sorting, and pagination (opensearch_search)
Query Logs (PPL/SQL)	Run piped PPL (default) or SQL log queries (opensearch_query) — the OpenSearch equivalent of ES|QL
Browse Indices	List indices and their document counts (opensearch_list_indices)
Read Mappings	Inspect an index's field mappings so agents build correct queries (opensearch_get_mappings)
Inspect Shards	Check shard allocation and health (opensearch_get_shards)
Test Connection	Verify the endpoint, credentials, and that it's really OpenSearch (opensearch_test_connection)
Alert Source Webhooks	Receive OpenSearch alerting monitor notifications via webhook, mapped to Autoheal alerts

Prerequisites

• An OpenSearch cluster endpoint reachable by Autoheal (see Private and on-prem access if it is not internet-reachable)
• Credentials matching how your cluster is protected: basic (OpenSearch Security user), bearer/JWT, or AWS IAM (Amazon OpenSearch Service)
• A read-only OpenSearch role for the account you connect (see Required Permissions)

Setup

1

Add the Integration in Autoheal

1. Go to Integrations in Autoheal and click OpenSearch
2. Enter a name that identifies the cluster/environment — e.g. OpenSearch – prod

2

Enter the Endpoint

• OpenSearch Endpoint: the cluster base URL (not OpenSearch Dashboards), e.g. https://opensearch.internal:9200.
• For Amazon OpenSearch Service, use the domain endpoint, e.g. https://search-mydomain-abc123.us-east-1.es.amazonaws.com.

3

Choose Authentication

Pick the auth type that matches your cluster:

• Username & Password — an OpenSearch Security user with read access
• Bearer Token (JWT) — OpenSearch Security JWT or a reverse-proxy token
• AWS IAM (SigV4) — Amazon OpenSearch Service via a linked AWS integration (see below)

4

Test and Save

Click Test Connection to verify the endpoint and credentials, then Save. Test Connection reports the cluster version and warns if the endpoint is actually an Elasticsearch cluster.

Authentication Options

Auth type	When to use	Fields
Username & Password	OpenSearch Security internal/LDAP user	Username, Password
Bearer Token (JWT)	OpenSearch Security JWT or reverse-proxy token	Bearer Token
AWS IAM (SigV4)	Amazon OpenSearch Service (managed domain)	AWS Integration, Region

AWS IAM (SigV4)

For Amazon OpenSearch Service, Autoheal signs each request with AWS SigV4 using credentials from a linked AWS integration — no long-lived keys are stored on the OpenSearch integration.

1

Connect an AWS integration

Add the AWS integration (OIDC federation or instance role). Its IAM role must be allowed on your OpenSearch domain's access policy / fine-grained access control (a read-only role is enough).

2

Select AWS IAM (SigV4) on OpenSearch

• AWS Integration: pick the AWS integration from step 1
• Region: the domain's AWS region (leave blank to use the AWS integration's region)

Required Permissions

Grant Autoheal a read-only role. The integration only reads — it never writes, updates, or deletes. A typical OpenSearch Security role:

Permission	Scope	Why it's needed
cluster:monitor/*	Cluster	Test connection, cluster health, shard status
indices:data/read/*	Log indices	Search and PPL/SQL queries
indices:admin/mappings/get	Log indices	Read field mappings
indices:monitor/*	Log indices	Index/shard stats

tip

Restrict the role's index patterns to the log indices Autoheal should see (e.g. logs-*) rather than *.

Example Queries

Once connected, you can ask an agent questions like:

Show the last 50 ERROR logs for host vm-42 in the last hour

Count errors by service in the app-logs index over the last 15 minutes

Using PPL, find OutOfMemoryError entries and group them by host

What indices are available, and what fields does the app-logs mapping have?

Alert Source Setup

OpenSearch's alerting plugin can POST a notification to a webhook when a monitor triggers. Because the message body is a fully customer-authored template, you map its fields to Autoheal alert fields in the Alert Payload Mapping (it starts empty — you configure it to match your body, using the recommended template below as a starting point).

1

Enable the Webhook in Autoheal

1. Open your OpenSearch integration in Autoheal
2. In the Events Setup section, copy the Webhook URL (it already contains a unique per-integration secret)
3. Optionally enter a Webhook Signing Secret for a Bearer-token check on every delivery

2

Create a Notifications Channel in OpenSearch

In OpenSearch Dashboards → Notifications, create a Custom webhook channel:

• URL: the Autoheal Webhook URL
• Content type: application/json
• If you set a Webhook Signing Secret, add a header Authorization: Bearer <the same secret>

3

Set the Monitor Action Message

In your monitor's trigger action, select that channel and set the message body to this recommended template, then map its fields in the Payload Mapping:

{
  "identity": "{{ctx.monitor.name}}::{{ctx.trigger.name}}",
  "title": "{{ctx.trigger.name}} on {{ctx.monitor.name}}",
  "severity": "{{ctx.trigger.severity}}",
  "monitor": "{{ctx.monitor.name}}",
  "trigger": "{{ctx.trigger.name}}"
}

warning

The body must be valid JSON (escape quotes as OpenSearch requires). To scope an alert to a host/VM — so agents can pull that host's logs — add a field from your query results (e.g. "host": "{{ctx.results.0.hits.hits.0._source.host}}") and add a matching label row in the Payload Mapping.

4

Preview and Test

Use Preview in the mapping editor to paste a sample body and confirm the resulting alert, then trigger the monitor. The alert should appear on Autoheal's Alerts page within a few seconds.

note

OpenSearch alerting fires on trigger; it does not send a "resolved" signal by default, so mapped alerts stay open until they expire. To auto-resolve, add a status field to your message body and map it (Status + Resolved Values) in the Payload Mapping.

Private and on-prem access

note

This applies to Autoheal's SaaS deployment. In a BYOC deployment the stack runs inside your own network and reaches OpenSearch directly by endpoint, so the Private Access connection field is not shown.

Query routing over a Private Access connection runs inside the agent sandbox and is enabled per organization; contact support to turn it on. See Private Access.

If your OpenSearch is on a private network and not reachable from the internet, alert delivery still works (OpenSearch makes an outbound call to the Webhook URL), but queries need a path into your network:

1

Add a Private Access connection

Follow the Tailscale guide to add a connection (Tailscale) and join the host or subnet running OpenSearch to your private network.

2

Bind OpenSearch to it

In the OpenSearch integration, set Private Access connection to the connection you created. Queries for this instance then route over your private network to the endpoint.

note

Only integrations you explicitly bind to a Private Access connection route through it — everything else continues to reach public endpoints directly.

Troubleshooting

Test Connection warns it may be an Elasticsearch cluster

You've pointed the OpenSearch card at an Elasticsearch cluster. Use the Elasticsearch integration instead — the query languages and auth differ.

401 / 403 on Test Connection

• Confirm the Auth type matches how your cluster is protected (Basic vs Bearer vs AWS IAM)
• For Basic, re-enter the username and password (watch for trailing spaces) and confirm the user has the read-only role
• For AWS IAM, confirm the linked AWS integration's role is granted on the domain's access policy / fine-grained access control, and the Region is correct

PPL/SQL query fails

• PPL starts with source=<index> | ...; SQL uses FROM <index>
• The SQL/PPL plugin ships by default with OpenSearch and Amazon OpenSearch Service; if it's disabled, use opensearch_search (query DSL) instead

Connection timeout / cannot reach endpoint

• Verify the Endpoint is the cluster URL (port 9200 for self-hosted), not OpenSearch Dashboards
• If OpenSearch is on a private network, add and bind a Private Access connection (SaaS deployments; see Private and on-prem access)

Webhook alerts not appearing

• Confirm the channel URL exactly matches the Webhook URL in Autoheal, with content type application/json
• Use Preview in the mapping editor to confirm your message body maps to a valid alert (at minimum an Identity and Title)
• If you set a Webhook Signing Secret, confirm the channel sends the matching Authorization: Bearer header