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

# OpenSearch

> Connect OpenSearch so agents can check cluster health, inspect indices and shards, search documents, and explain relevance, read-only

Connect an OpenSearch cluster to let CloudThinker agents check cluster health, inspect indices, mappings, and shards, search and count documents, and explain why a document scored the way it did. The connection signs in with a **username and password** (basic auth) and is read-only by design: it exposes eight read tools (cluster health, list indices, index mapping, shards, search, count, multi-search, and explain) and nothing that writes.

## Prerequisites

* An OpenSearch cluster with an HTTPS endpoint CloudThinker can reach over the network. `localhost` and private addresses aren't reachable from CloudThinker Cloud. If a firewall or domain access policy restricts callers, allow CloudThinker's egress IPs. These docs don't publish CloudThinker's egress IP list: ask your CloudThinker contact, or [contact us](https://cloudthinker.io/contact). See [Reaching private services](https://docs.cloudthinker.io/guide/connections/overview.md#reaching-private-services) for other options.
* The OpenSearch security plugin with an internal user you can create. On Amazon OpenSearch Service, that means a domain with fine-grained access control, because the connection uses basic auth, not AWS request signing.
* The indices agents should read, such as `logs-app` or `products`.

## Setup

**1. Create a read-only role**

In **OpenSearch Dashboards → Dev Tools**, create a role scoped to the indices agents need. Replace `logs-*` with your own patterns.

```http theme={null}
PUT _plugins/_security/api/roles/cloudthinker_read
{
  "cluster_permissions": ["cluster_monitor"],
  "index_permissions": [
    {
      "index_patterns": ["logs-*"],
      "allowed_actions": ["read", "indices_monitor", "indices:admin/mappings/get"]
    }
  ]
}
```

**2. Create a dedicated user and map the role**

Run each request separately in **Dev Tools**. First create the user:

```http theme={null}
PUT _plugins/_security/api/internalusers/cloudthinker
{
  "password": "<a long random password>"
}
```

Then map the role to it:

```http theme={null}
PUT _plugins/_security/api/rolesmapping/cloudthinker_read
{
  "users": ["cloudthinker"]
}
```

You can do the same in **OpenSearch Dashboards → Security** under **Roles** and **Internal users**.

**3. Add the connection in CloudThinker**

In the sidebar, click **More → Workspace settings → Connections**, then on the **Builtin Connections** tab select **OpenSearch**. Enter the **Cluster URL**, **Username**, and **Password**. Set **Connection timeout (seconds)** to a value such as `15`. Click **Connect**.

**Success state:** the connection shows **Connecting** and **Verifying**, then **Connected**.

To change the password later, open the connection, click the pencil icon on its row, and in **Edit Instance** click **Replace…**. See [Rotate a credential](https://docs.cloudthinker.io/guide/connections/overview.md#rotate-a-credential).

> [!TIP]
>
> On **Amazon OpenSearch Service**, enable fine-grained access control with the internal user database, sign in to OpenSearch Dashboards as the master user, and run the same requests. The domain access policy must also let CloudThinker's requests through.

> [!NOTE]
>
> Always set **Connection timeout (seconds)**. With it empty there is no timeout, so an unreachable cluster or a failed TLS check stalls the conversation instead of returning an error.

## Connection details

| Field | Required | Description | Example |
| - | - | - | - |
| **Cluster URL** | Yes | Cluster endpoint, including scheme and port | `https://opensearch.example.com:9200` |
| **Username** | Yes | A dedicated user scoped to the indices this workspace should reach, not the cluster admin | `cloudthinker` |
| **Password** | Yes | That user's password | |
| **Verify TLS certificate** | No | Leave empty to verify the certificate (recommended). Enter `false` only for a self-hosted cluster with a self-signed certificate | empty |
| **Connection timeout (seconds)** | No, but recommended | How long a call waits for the cluster. Empty means no limit | `15` |

## Required permissions

| Agents need to | Grant |
| - | - |
| Check cluster health | Cluster action group `cluster_monitor` |
| List indices and read shard allocation | Index action group `indices_monitor` |
| Read field mappings | Index action `indices:admin/mappings/get` |
| Search, count, multi-search, and explain | Index action group `read` |

Write permissions on the user add nothing, because the connection has no tool that uses them.

> [!TIP]
>
> Scope `index_patterns` to the indices agents need. A cluster admin credential gives agents nothing extra here and widens the damage if it leaks.

## Agent capabilities

| Capability | What agents can do |
| - | - |
| **Cluster health** | Report cluster status, node count, and unassigned shard count |
| **Index inventory** | List indices with health and document counts, and read field mappings |
| **Search and count** | Run DSL searches, counts, and multi-search requests against named indices |
| **Shard triage** | Show shard allocation for one index and separate an unassigned primary (data you can't read) from an unassigned replica (lost redundancy) |
| **Relevance explanation** | Explain why one document matched, missed, or scored as it did for a query |

Name the index in your prompt when you can. Index inventory and shard checks run against exact index names, not wildcards, so a prompt like "check logs-app-2026.10.24" gets a faster, more precise answer than "check the logs".

### Verify the connection

```text theme={null}
Check OpenSearch cluster health and list the indices with their document counts
```

Expect a status of green, yellow, or red, the node count, any unassigned shards, and a list of indices.

### Example prompts

```text theme={null}
Count authentication failures in logs-app over the last 24 hours, broken down by level
Why does the products index return irrelevant results for "wireless charger"? Explain the top hit's score
Which shards in logs-app-2026.10.24 are unassigned, and are any of them primaries?
```

## Troubleshooting

> [accordion] 401 Unauthorized
>
> The username or password is wrong, or the user was removed. Check the user under **Security → Internal users**, then [replace the credentials](https://docs.cloudthinker.io/guide/connections/overview.md#rotate-a-credential) on the connection.

> [accordion] Calls hang instead of failing
>
> The cluster is unreachable, or TLS verification is failing against a self-signed certificate. Set **Connection timeout (seconds)** so calls fail fast. Set **Verify TLS certificate** to `false` only if the cluster really serves a self-signed certificate.

> [accordion] security\_exception, or an agent can't see an index
>
> The user's role doesn't cover that index. Add the index to `index_patterns` on the `cloudthinker_read` role. Agents report which index was refused instead of retrying with a wider pattern.

> [accordion] Connection fails on Amazon OpenSearch Service
>
> The domain uses IAM-only access. This connection signs in with basic auth, so the domain needs fine-grained access control with an internal user database.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Read-only surface**: the connection can't write, delete, or change cluster settings, whatever the user's permissions allow.
- **Credentials stay on your cluster**: agents can't point the stored username and password at a different host. CloudThinker rejects per-call connection overrides before a request is sent, even if a document asks for one.

## Related

> [card] [Elasticsearch](https://docs.cloudthinker.io/guide/connections/elasticsearch.md)
>
> Connect an Elasticsearch cluster with a read-only API key.

> [card] [Root cause analysis](https://docs.cloudthinker.io/guide/incident/root-cause-analysis.md)
>
> See how agents use log searches to find what caused an incident.


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