> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keephq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSearch Serverless

> OpenSearch Serverless provider enables seamless integration with AWS OpenSearch Serverless for document-level querying, alerting, and writing, directly into Keep.

## Overview

The OpenSearch Provider offers native integration with **Amazon OpenSearch Serverless**, allowing Keep users to query, monitor, and write documents in real-time. This supports observability and event-driven alerting for operational and security use cases.

### Key Features:

* **Read & Write Support**: Enables both querying and writing documents to OpenSearch Serverless collections.
* **AWS IAM Authentication**: Authenticates using AWS IAM credentials (access key/secret or instance role).

## Connecting with the Provider

To connect OpenSearch with Keep, you’ll need:

* An AWS account with permissions for OpenSearch Serverless (AOSS).
* A configured collection and index in AOSS.
* AWS IAM credentials (permanent or temporary).

## Required AWS IAM Permissions (Scopes)

To function properly, the OpenSearch provider requires the following IAM scopes:

### Mandatory Scopes

* **`iam:SimulatePrincipalPolicy`**
  * **Description**: Required to check if the IAM identity has access to AOSS API.
  * **Alias**: Needed to test the access for next 3 scopes.
  * **Mandatory**: Yes

* **`aoss:APIAccessAll`**
  * **Description**: Required to make API calls to OpenSearch Serverless.
  * **Alias**: Access to make API calls to serverless
  * **Mandatory**: Yes

* **`aoss:ListAccessPolicies`**
  * **Description**: Needed to list all Data Access Policies.
  * **Alias**: Policy List access
  * **Mandatory**: Yes

* **`aoss:GetAccessPolicy`**
  * **Description**: Required to inspect each policy for read/write scope.
  * **Alias**: Policy read access
  * **Mandatory**: Yes

* **`aoss:CreateIndex`**
  * **Description**: Required to create an index.
  * **Documentation**: [AOSS API Docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-genref.html#serverless-operations)
  * **Alias**: Create Index
  * **Mandatory**: Yes

* **`aoss:ReadDocument`**
  * **Description**: Required to read documents from an OpenSearch collection.
  * **Documentation**: [AOSS API Docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-genref.html#serverless-operations)
  * **Alias**: Read Documents
  * **Mandatory**: Yes

* **`aoss:WriteDocument`**
  * **Description**: Required to index or update documents in an OpenSearch collection.
  * **Documentation**: [AOSS API Docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-genref.html#serverless-operations)
  * **Alias**: Write Documents
  * **Mandatory**: Yes

> [!NOTE]
>
> `iam:SimulatePrincipalPolicy`, `aoss:APIAccessAll`, `aoss:ListAccessPolicies`, `aoss:GetAccessPolicy`, needs to be added from your IAM console to the IAM identity used by Keep.
> The other two policies are data access policies which needs to be added from aws serverless dashboard.
> Go through the readme to get step by step setup: [README](https://github.com/keep/keep/providers/opensearchserverless_provider\README.md)

## Authentication Configuration

To authenticate with OpenSearch Serverless, provide the following:

* **AWS Access Key** (Mandatory): Your AWS access key.
* **AWS Access Key Secret** (Mandatory): Your AWS access key secret.
* **Region** (Mandatory): The AWS region hosting your OpenSearch collection.
* **Domain Endpoint** (Mandatory): The full domain URL of your AOSS collection endpoint.

## Setting Up the Integration

### Steps:

1. **Assign IAM Permissions**: Grant your IAM user/role `aoss:CreateIndex`, `aoss:ReadDocument` and `aoss:WriteDocument` on the target collection.
2. **Configure Keep Provider**: Provide access key, secret, region, and collection endpoint in the Keep platform.

## Querying OpenSearch

Keep supports standard OpenSearch queries using the `_search` endpoint:

* **index**: The name of the OpenSearch index to query.
* **query**: A valid OpenSearch query DSL object.

### Example

```json theme={null}
{
  "query": {
    "match_all": {}
  },
  "size": 1
}
```

## Writing to OpenSearch

You can use the `_notify` functionality to push documents into OpenSearch collections.

* **index**: The index name where the document should be written.
* **document**: A Python dictionary representing the document body.
* **id**: ID for the document

## Useful Links

* [AWS OpenSearch Serverless Documentation](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless.html)
* [AOSS Data Access Control](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)
* [README](https://github.com/keep/keep/providers/opensearchserverless_provider\README.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.