Documentation Plugins OpenSearch Configure

Configure the OpenSearch data source

This document explains how to configure the OpenSearch data source in Grafana.

Before you begin

Before configuring the data source, ensure you have:

• Grafana permissions: Organization administrator role to add and configure data sources.
• OpenSearch instance: A running OpenSearch or Elasticsearch instance accessible from your Grafana server.
• Credentials: Authentication credentials for your OpenSearch instance, if required.

Add the data source

To add the OpenSearch data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type OpenSearch in the search bar.
4. Select OpenSearch.
5. Click Add new data source.

Configure settings

The following table describes the connection settings:

Authentication

The OpenSearch data source supports several authentication methods.

Basic authentication

To use basic authentication:

1. Enable Basic auth in the data source settings.
2. Enter the User and Password for your OpenSearch instance.

TLS client authentication

To use TLS client authentication:

1. Enable TLS Client Auth in the data source settings.
2. Provide the CA Cert, Client Cert, and Client Key.
3. Optionally enable Skip TLS Verify to bypass certificate validation (not recommended for production).

AWS SigV4 authentication

To sign requests to Amazon OpenSearch Service using AWS Signature Version 4:

1. Enable SigV4 in your Grafana configuration.
2. In the data source settings, enable SigV4 auth.
3. Configure the authentication provider:
   • Access & secret key: Enter your AWS access key and secret key directly.
   • Credentials file: Use a shared credentials file on the Grafana server.
   • Workspace IAM role: Use the IAM role attached to the Grafana workspace (Grafana Cloud or Amazon Managed Grafana).

For more information about AWS authentication options, refer to AWS authentication.

OAuth pass-through

When oauthPassThru is enabled in the data source configuration, Grafana forwards the user’s OAuth token to OpenSearch with each request. This is configured through provisioning or the Grafana API.

OpenSearch details

These settings control how Grafana connects to and queries your OpenSearch index.

The Min time interval value must be a number followed by a valid time identifier:

Log settings

These optional settings control how log data is displayed in Explore.

For example, if you use a default Filebeat setup to ship logs to OpenSearch, set Message field name to message and Level field name to fields.level.

Data links

Data links create a link from a specified field that you can access in Explore’s log view.

Each data link configuration consists of:

Private data source connect (PDC)

Use private data source connect (PDC) to connect to and query data within a secure network without opening that network to inbound traffic from Grafana Cloud. For more information, refer to Private data source connect and Configure PDC.

If you use PDC with SigV4, the PDC agent must allow internet egress to sts.<region>.amazonaws.com:443.

To configure PDC, click in the Private data source connect box to select an existing PDC connection from the drop-down or create a new one.

Verify the connection

Click Save & test to verify the connection. If you encounter errors, refer to Troubleshoot OpenSearch data source issues.

On success, the data source returns one of the following messages:

Amazon OpenSearch Service

AWS users can use this data source to visualize data from Amazon OpenSearch Service. If you use an AWS Identity and Access Management (IAM) policy to control access to your domain, you must use AWS SigV4 to sign all requests.

For more information about AWS SigV4, refer to the AWS documentation.

IAM policies for OpenSearch Service

Grafana needs permissions granted through IAM to read OpenSearch Service documents. You can attach these permissions to IAM roles and use Grafana’s built-in support for assuming roles. Configure the required policy before adding the data source to Grafana.

For predefined policies, refer to the Amazon OpenSearch Service managed policies documentation.

The following is an example of a minimal policy for querying OpenSearch Service:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["es:ESHttpGet", "es:ESHttpPost"],
      "Resource": "arn:aws:es:<REGION>:<ACCOUNT_ID>:domain/<DOMAIN_NAME>"
    }
  ]
}

Amazon OpenSearch Serverless

Amazon OpenSearch Serverless lets you run OpenSearch workloads without managing infrastructure. Access is controlled by data access policies.

To use Serverless mode, enable the Serverless toggle in the data source settings. This automatically sets the flavor and version.

Data access policies for OpenSearch Serverless

The following example shows a policy that allows querying a collection and index:

JSON Copy

[
  {
    "Rules": [
      {
        "Resource": ["collection/<COLLECTION_NAME>"],
        "Permission": ["aoss:DescribeCollectionItems"],
        "ResourceType": "collection"
      },
      {
        "Resource": ["index/<COLLECTION_NAME>/<INDEX_NAME>"],
        "Permission": ["aoss:DescribeIndex", "aoss:ReadDocument"],
        "ResourceType": "index"
      },
      {
        "Effect": "Allow",
        "Action": "aoss:APIAccessAll",
        "Resource": "arn:aws:aoss:<REGION>:<ACCOUNT_ID>:collection/<COLLECTION_NAME>"
      },
      {
        "Effect": "Allow",
        "Action": ["aoss:BatchGetCollection", "aoss:ListCollections"],
        "Resource": "*"
      }
    ],
    "Principal": ["arn:aws:iam:<REGION>:<ACCOUNT_ID>:user/<USERNAME>"],
    "Description": "read-access"
  }
]

Provision the data source

You can define and configure the data source in YAML files as part of Grafana’s provisioning system. For more information, refer to Provisioning Grafana.

The following example provisions an OpenSearch data source with basic authentication:

YAML Copy

apiVersion: 1

datasources:
  - name: OpenSearch
    type: grafana-opensearch-datasource
    access: proxy
    url: <OPENSEARCH_URL>
    basicAuth: true
    basicAuthUser: <USERNAME>
    jsonData:
      flavor: opensearch
      version: "2.18.0"
      database: <INDEX_NAME>
      timeField: "@timestamp"
      logMessageField: message
      logLevelField: level
      pplEnabled: true
      serverless: false
      maxConcurrentShardRequests: 5
      timeInterval: 10s
    secureJsonData:
      basicAuthPassword: <PASSWORD>

The following table describes the available jsonData provisioning options:

The following table describes the available secureJsonData provisioning options:

Provision the data source using Terraform

You can provision the data source using the Grafana Terraform provider. The following example creates an OpenSearch data source with basic authentication:

hcl Copy

resource "grafana_data_source" "opensearch" {
  type = "grafana-opensearch-datasource"
  name = "OpenSearch"
  url  = "<OPENSEARCH_URL>"

  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  json_data_encoded = jsonencode({
    flavor                     = "opensearch"
    version                    = "2.18.0"
    database                   = "<INDEX_NAME>"
    timeField                  = "@timestamp"
    logMessageField            = "message"
    logLevelField              = "level"
    pplEnabled                 = true
    serverless                 = false
    maxConcurrentShardRequests = 5
    timeInterval               = "10s"
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

For more information about the Grafana Terraform provider, refer to the Grafana provider documentation.