Documentation Plugins Amazon Timestream Configure

Configure the Amazon Timestream data source

This document provides instructions for configuring the Amazon Timestream data source and explains available configuration options. For general information on managing data sources, refer to Data source management.

Before you begin

To configure the Amazon Timestream data source, you need:

• Grafana permissions: The organization administrator role.
• AWS account: An active AWS account with Amazon Timestream enabled.
• AWS credentials: An IAM identity with permissions to query Timestream. Refer to IAM policies for the minimum required permissions.

Key concepts

If you’re new to Amazon Timestream, the following terms are used throughout this documentation.

Add the data source

To add the Amazon Timestream data source:

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

Configure settings

The following table describes the available configuration settings.

Authentication

The Amazon Timestream data source uses the shared AWS authentication provided by the Grafana AWS SDK. It supports the following authentication methods:

• AWS SDK Default: Uses the default credential provider chain, which checks environment variables, the shared credentials file, and the EC2/ECS instance role in order.
• Credentials file: Uses a named profile from the AWS shared credentials file (~/.aws/credentials).
• Access and secret key: Uses an IAM access key ID and secret access key that you enter directly in the data source settings.

You can restrict which authentication methods are available by configuring the allowed_auth_providers option in the Grafana configuration file.

For detailed information on each method, refer to AWS authentication.

Assume role

To access Timestream using a different IAM role, configure the data source to assume that role:

1. Enter the Assume Role ARN in the data source settings, for example arn:aws:iam::123456789012:role/TimestreamReadOnly.
2. If the role’s trust policy requires it, enter an External ID.

IAM policies

The IAM identity used by Grafana needs Timestream-specific permissions to access the Timestream API. These permissions are separate from CloudWatch or other AWS service permissions. Attach a policy to the IAM user or role configured in the authentication step.

The following example grants full Timestream access:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["timestream:*"],
      "Resource": "*"
    }
  ]
}

For more restrictive access, grant only the specific actions the plugin requires. The following policy lists every action the plugin uses:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "timestream:DescribeEndpoints",
        "timestream:Select",
        "timestream:ListDatabases",
        "timestream:ListTables",
        "timestream:ListMeasures",
        "timestream:DescribeDatabase",
        "timestream:DescribeTable"
      ],
      "Resource": "*"
    }
  ]
}

The following table explains why each action is required.

EKS IAM Roles for Service Accounts (IRSA)

If you run Grafana on Amazon EKS and use IAM Roles for Service Accounts, the IAM role also needs the sts:AssumeRoleWithWebIdentity permission. Verify that:

1. The IAM role’s trust policy allows the EKS OIDC provider to assume the role.
2. The service account annotation matches the role ARN.
3. The Grafana pod uses the correct service account.

For more information, refer to the AWS documentation on IRSA.

Verify the connection

Click Save & test. A Connection success message confirms that Grafana can connect to your Timestream instance.

If the test fails:

• Verify that your authentication credentials are correct.
• Confirm that the IAM identity has the required permissions.
• Check that the selected region matches where your Timestream database is located.

For more help, refer to Troubleshoot Amazon Timestream data source issues.

Provision the data source

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

The following examples demonstrate common provisioning configurations.

AWS SDK Default

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Timestream
    type: grafana-timestream-datasource
    jsonData:
      authType: default
      defaultRegion: us-east-1

Credentials file profile

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Timestream
    type: grafana-timestream-datasource
    jsonData:
      authType: credentials
      defaultRegion: us-east-1

Access and secret key

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Timestream
    type: grafana-timestream-datasource
    jsonData:
      authType: keys
      defaultRegion: us-east-1
    secureJsonData:
      accessKey: <YOUR_ACCESS_KEY>
      secretKey: <YOUR_SECRET_KEY>

AWS SDK Default with assume role

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Timestream
    type: grafana-timestream-datasource
    jsonData:
      authType: default
      defaultRegion: us-east-1
      assumeRoleArn: arn:aws:iam::123456789012:role/TimestreamReadOnly
      externalId: <YOUR_EXTERNAL_ID>

Include default query parameters

You can also include default database, table, and measure values in any provisioning configuration. These values populate the $__database, $__table, and $__measure macros.

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Timestream
    type: grafana-timestream-datasource
    jsonData:
      authType: default
      defaultRegion: us-east-1
      defaultDatabase: my_database
      defaultTable: my_table
      defaultMeasure: cpu_utilization

Provision the data source with Terraform

You can provision the Amazon Timestream data source using the Grafana Terraform provider.

The following example creates an Amazon Timestream data source using access and secret keys:

hcl Copy

resource "grafana_data_source" "timestream" {
  type = "grafana-timestream-datasource"
  name = "Amazon Timestream"

  json_data_encoded = jsonencode({
    authType      = "keys"
    defaultRegion = "us-east-1"
  })

  secure_json_data_encoded = jsonencode({
    accessKey = var.aws_access_key
    secretKey = var.aws_secret_key
  })
}

The following example uses the AWS SDK default authentication with an assume role:

hcl Copy

resource "grafana_data_source" "timestream" {
  type = "grafana-timestream-datasource"
  name = "Amazon Timestream"

  json_data_encoded = jsonencode({
    authType       = "default"
    defaultRegion  = "us-east-1"
    assumeRoleArn  = "arn:aws:iam::123456789012:role/TimestreamReadOnly"
    defaultDatabase = "my_database"
    defaultTable    = "my_table"
    defaultMeasure  = "cpu_utilization"
  })
}

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