Elasticsearch Integration

Connect Elasticsearch so that agents can search logs and analyze data during investigations.

Capabilities

Capability	Description
Search Logs	Query log data with filters
Aggregate Data	Run aggregations and analytics
Browse Indices	Access available indices

Prerequisites

• Access to your Elasticsearch deployment's Kibana UI
• Permission to create API keys in Kibana
• The Elasticsearch endpoint URL (not the Kibana URL)

Setup

1

Open Kibana for Your Deployment

Go to your Elastic Cloud console and open Kibana for the deployment you want to connect.

warning

Do not use the API keys from the Elastic Cloud console (Organization → API Keys). Those keys are for managing cloud deployments, not for accessing cluster data. You must create the API key inside Kibana.

2

Create an API Key in Kibana

1. In Kibana, navigate to Security → API Keys
2. Click Create API key
3. Give it a name (e.g., autoheal-readonly)
4. Under Role descriptors, paste the following JSON to grant read-only access:

{
  "autoheal-read-role": {
    "cluster": ["monitor"],
    "indices": [
      {
        "names": ["*"],
        "privileges": ["read", "monitor", "view_index_metadata"],
        "allow_restricted_indices": false
      }
    ]
  }
}

5. Click Create API key
6. Copy the API key — you will only see it once

tip

You do not need to base64-encode the key. Paste the API key exactly as Kibana gives it to you.

3

Get Your Elasticsearch Endpoint

In the Elastic Cloud console, find your deployment and copy the Elasticsearch endpoint URL.

It looks like: https://my-cluster.es.us-east-1.aws.found.io:9243

warning

Use the Elasticsearch endpoint, not the Kibana endpoint. The Kibana URL will not work.

4

Add Integration in Autoheal

1. Go to Integrations → Elasticsearch
2. Enter a name for this instance (e.g., "Production ES")
3. Paste the Elasticsearch endpoint URL
4. Select API Key as the authentication method
5. Paste the API key from Kibana

5

Test and Save

Click Test Connection to check the connection. Then click Save.

Authentication Options

API Key (Recommended)

Create an API key inside Kibana (Security → API Keys) with the role policy shown above. Paste it directly into Autoheal. You do not need to encode it.

Basic Auth

Use a username and password with read access to the required indices. This is useful if your organization manages Elasticsearch credentials centrally.

Required Permissions

The API key role grants these permissions:

Permission	Scope	Why It's Needed
monitor	Cluster	Test connection and check cluster health
read	All indices	Search and read log data
monitor	All indices	View index stats
view_index_metadata	All indices	List and browse index mappings

tip

To restrict access to specific indices, replace "*" in the role policy with a list of index patterns (e.g., ["logs-*", "metrics-*"]).

Example Queries

Search for errors in the application logs from the last hour

Find all 500 errors in the nginx logs

Show me logs containing "OutOfMemoryError"

Troubleshooting

Test Connection fails with 'security_exception'

This usually means that you created the API key in the wrong place.

• Do not use API keys from Elastic Cloud console (Organization → API Keys). Those keys are for cloud management only.
• Create the API key inside Kibana → Security → API Keys for your specific deployment.

'Unable to authenticate with provided credentials'

• Check that you copied the full API key from Kibana. Kibana shows it only once, at creation time.
• Check that you are not base64 encoding the key. Paste it exactly as Kibana provided it.
• If you lost the key, create a new one in Kibana.

Using the wrong endpoint

• Use the Elasticsearch endpoint URL, not the Kibana URL.
• The Elasticsearch endpoint typically looks like https://my-cluster.es.us-east-1.aws.found.io:9243.
• The Kibana URL (containing kb.) will not work for data access.

Agent can't read indices or data

• Check that the API key was created with the role policy that includes read and view_index_metadata privileges.
• Check that the names field in the role covers the indices you need (use ["*"] for all indices).