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

# Elastic

> Configure log shipping from Control Plane to Elasticsearch, using AWS Elasticsearch, Elastic Cloud, or a generic Elasticsearch endpoint.

## Overview

[Elastic](https://www.elastic.co/elasticsearch) (Elasticsearch) is a distributed search and analytics engine commonly used to store, search, and visualize log data, often as part of the Elastic Stack (ELK).

Control Plane can ship org logs to Elasticsearch using one of three connection types:

1. **AWS Elasticsearch** - an Elasticsearch domain hosted on AWS.
2. **Elastic Cloud** - a deployment hosted on [Elastic Cloud](https://www.elastic.co/cloud).
3. **Generic Elasticsearch** - any other reachable Elasticsearch endpoint.

Only one connection type can be configured at a time.

Follow the steps below to configure log shipping to Elastic.

## Step 1 - Credential Procurement

The credentials required depend on the connection type:

* **AWS Elasticsearch**: An [AWS key](/reference/secret#amazon-web-services-aws) is required.
* **Elastic Cloud**: A [Username & Password secret](/reference/secret#username-and-password) is required.
* **Generic Elasticsearch**: A [Username & Password secret](/reference/secret#username-and-password) is required.

## Step 2 - Configure External Logging

External logging can be configured by using either the [UI Console](#enable-logging-using-the-ui-console) or [CLI](#enable-logging-using-the-cli).

### Enable Logging using the UI Console

1. From the Control Plane Console UI, click on `Org` in the left menu.
2. Click `External Logs` in the middle context menu.
3. Select `Elastic`, choose the connection type (AWS, Elastic Cloud, or Generic), and fill out the required fields.
4. Select the secret created to authenticate to Elastic. Refer to the [credential procurement](#step-1-credential-procurement) section to obtain and configure the necessary credentials.
5. Click `Save`.
6. After the configuration is complete, log entries will be available at Elastic within a few minutes.

### Enable Logging using the CLI

The external logging configuration can be created / updated using the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

Below is an example of an [Org](/reference/org) manifest (in YAML) for each connection type. Edit and save the YAML as a file and use it as an input to the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

Refer to the [credential procurement](#step-1-credential-procurement) section to obtain and configure the necessary credentials.

<Note>
  Only one of `aws`, `elasticCloud`, or `generic` can be set at a time.
</Note>

#### AWS Elasticsearch

* Substitute: `ORG_NAME`, `AWS_SECRET`, `HOST_NAME`, `INDEX`, `TYPE`, and `REGION`.

```yaml YAML theme={null}
kind: org
name: ORG_NAME
spec:
  logging:
    elastic:
      aws:
        host: HOST_NAME.es.amazonaws.com
        port: 443
        index: INDEX
        type: TYPE
        region: REGION
        credentials: //secret/AWS_SECRET
```

* `host` - Required. Must be a valid AWS Elasticsearch hostname, ending in `es.amazonaws.com`.
* `port` - Defaults to `443`.
* `index` - Required.
* `type` - Required.
* `region` - Required.
* `credentials` - Required. Must reference an [AWS secret](/reference/secret#amazon-web-services-aws).

#### Elastic Cloud

* Substitute: `ORG_NAME`, `USERPASS_SECRET`, `CLOUD_ID`, `INDEX`, and `TYPE`.

```yaml YAML theme={null}
kind: org
name: ORG_NAME
spec:
  logging:
    elastic:
      elasticCloud:
        cloudId: CLOUD_ID
        index: INDEX
        type: TYPE
        credentials: //secret/USERPASS_SECRET
```

* `cloudId` - Required. The deployment's [Cloud ID](https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html), found on the Elastic Cloud deployment overview page.
* `index` - Required.
* `type` - Required.
* `credentials` - Required. Must reference a [Username & Password secret](/reference/secret#username-and-password).

#### Generic Elasticsearch

* Substitute: `ORG_NAME`, `USERPASS_SECRET`, `HOST_NAME`, `INDEX`, and `TYPE`.

```yaml YAML theme={null}
kind: org
name: ORG_NAME
spec:
  logging:
    elastic:
      generic:
        host: HOST_NAME
        port: 443
        path: /
        index: INDEX
        type: TYPE
        credentials: //secret/USERPASS_SECRET
```

* `host` - Required.
* `port` - Defaults to `443`.
* `path` - Optional. Must start with a `/`.
* `index` - Required.
* `type` - Required.
* `credentials` - Required. Must reference a [Username & Password secret](/reference/secret#username-and-password).