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

# Elasticsearch On-Prem

> Search and analyze logs in self-hosted Elasticsearch

## Overview

Connect your self-hosted Elasticsearch cluster to give TierZero access to your log data. TierZero queries your on-premises Elasticsearch during investigations to search logs, analyze patterns, and correlate events.

## Prerequisites

* Access to your self-hosted Elasticsearch cluster
* Ability to create API keys in Elasticsearch
* Network connectivity between TierZero and your Elasticsearch cluster (port 9200 over HTTPS)

## Setup Instructions

### Step 1: Navigate to Integration Settings

1. Log into your TierZero dashboard
2. Go to **Settings → Integrations**
3. Click **Connect** next to Elasticsearch

### Step 2: Create an API Key

You can create an API key via the Elasticsearch UI or REST API.

**Option 1: Elasticsearch UI**

1. Open **Stack Management → API Keys**
2. Click **Create API Key**
3. Name it (e.g., "tierzero-read-access")
4. Set read-only permissions:

```json theme={null}
{
  "role_descriptors": {
    "tierzero_reader": {
      "cluster": ["monitor"],
      "index": [
        {
          "names": ["*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}
```

5. Click **Create** and copy the **Base64-encoded** API key

**Option 2: REST API**

```bash theme={null}
curl -X POST "https://<your-elasticsearch-host>:9200/_security/api_key" \
  -H "Content-Type: application/json" \
  -u "elastic:<password>" \
  -d '{
    "name": "tierzero-read-access",
    "role_descriptors": {
      "tierzero_reader": {
        "cluster": ["monitor"],
        "index": [
          {
            "names": ["*"],
            "privileges": ["read", "view_index_metadata"]
          }
        ]
      }
    }
  }'
```

Copy the `encoded` value from the response.

### Step 3: Enter Connection Details

1. Enter your Elasticsearch **cluster endpoint** (e.g., `https://elasticsearch.internal.yourcompany.com:9200`)
2. Paste the **Base64-encoded API key**
3. Click **Connect**

## Network Requirements

Your self-hosted Elasticsearch cluster must be reachable from TierZero over HTTPS:

* **Port**: 9200 (default) or your custom Elasticsearch port
* **Protocol**: HTTPS with a valid TLS certificate
* If your cluster is behind a firewall or VPN, ensure TierZero's IP addresses are allowlisted
* For clusters in AWS, **AWS PrivateLink** is supported. Contact TierZero to set up a private connection without exposing your cluster to the public internet

<Warning>
  TierZero requires HTTPS connectivity to your Elasticsearch cluster. Clusters accessible only via internal networks may require AWS PrivateLink, a reverse proxy, or VPN configuration.
</Warning>

## What TierZero Accesses

* **Log search**: Query logs across indices with time range filtering
* **Index metadata**: Index names and field mappings
* **Aggregations**: Statistical analysis of log data
* **Cluster health**: Basic cluster monitoring status

## Security

* TierZero uses API key authentication with **read-only permissions**
* No write, delete, or admin operations are performed
* API keys are encrypted at rest and in transit
* Revoke access by deleting the API key in your Elasticsearch cluster
* Never store credentials in plaintext in configuration files or source control

## Troubleshooting

### Connection Timeout

* Verify the cluster endpoint is reachable from TierZero (check firewall rules)
* Ensure HTTPS is enabled on your Elasticsearch cluster
* Confirm the port number is correct

### Authentication Errors

* Verify the API key is Base64-encoded (the `encoded` value from the creation response)
* Check that the API key has not expired
* Ensure the API key has the required `read` and `monitor` permissions

### TLS Certificate Errors

* Ensure your Elasticsearch cluster has a valid TLS certificate
* Self-signed certificates may require additional configuration