> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/connectors/saas/opensearch.md).

# OpenSearch

## Prerequisites

* You are an admin to the OpenSearch domain/collection.
* The OpenSearch endpoint is network accessible from the environment in which Teleskope is deployed.

For a private domain or VPC endpoint, configure the network path and DNS resolution from the Teleskope deployment to the endpoint before enrollment. IAM permissions do not provide network connectivity.

## Supported Authentication Methods

1. Username / Password (Basic Auth)
2. AWS IAM

***

{% stepper %}
{% step %}

#### Create OpenSearch users

**Option 1: Basic Auth**

1. Create a user in OpenSearch (Settings → Security → Internal Users):
   1. Username: `teleskope_ro`
   2. Password: `{secure_password}`
2. Assign the new user to a role with the permissions listed below.
3. Go to mapped users, and add the new internal user.

**Option 2: IAM Auth**

1. See [AWS](/connectors/aws.md), and add the Teleskope role to the target accounts if it does not exist.
2. Attach the **`AmazonOpenSearchServiceReadOnlyAccess`** IAM Policy to the role, or scope it down to select resources:

   ```
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
             "es:Describe*",
             "es:List*",
             "es:Get*"
         ],
         "Resource": "*"
       }
     ]
   }
   ```
3. Assign the **backend user** a role in OpenSearch (Settings → Security → Roles):
   1. Create or edit a role with the permissions listed below.
   2. Go to mapped users, and add the backend role by ARN (e.g. `arn:aws:iam::{origin_aws_account_id}:role/system/TeleskopeRole` ).

**Required OpenSearch role permissions**

The OpenSearch role mapped to the internal user or IAM backend role must include:

| Scope                 | Permissions                                   |
| --------------------- | --------------------------------------------- |
| Cluster               | `cluster_monitor`, `cluster_composite_ops_ro` |
| Target index patterns | `read`, `indices_monitor`                     |

The built-in `readall` role is not sufficient by itself because the connector also reads cluster and index monitoring data. Use `*` as the index pattern to scan all non-system indices, or restrict the role to the index patterns that Teleskope should scan.

Some OpenSearch security configurations also require `indices:admin/mappings/get` while servicing index discovery requests. If the OpenSearch security audit log reports a denied mapping request, add this permission to the target index patterns.
{% endstep %}

{% step %}

#### Enroll OpenSearch in Teleskope

1. Gather the following details for your OpenSearch instance:
   1. **Endpoint:** enter the complete OpenSearch endpoint URL. For an AWS private domain, use its VPC endpoint URL.
   2. **Region:** enter the OpenSearch region. For IAM authentication, Teleskope currently derives the request-signing region from the endpoint URL; this field does not override it.
   3. **Provider**
2. Select the authentication method
3. Supply the credentials:
   1. **Basic Auth:** enter the username/password.
   2. **IAM Auth:** select the AWS account where the OpenSearch instance & IAM role belongs.
      {% endstep %}

{% step %}

#### Configure the scan

Set the scan schedule in the OpenSearch connector settings.
{% endstep %}
{% endstepper %}