Documentation Plugins DynamoDB Configure

Configure the DynamoDB data source

This document explains how to configure the DynamoDB data source in Grafana. DynamoDB uses the AWS SDK for Go to connect to your DynamoDB instance using AWS IAM credentials.

Before you begin

Before configuring the data source, ensure you have:

• Grafana permissions: Organization administrator role.
• A Grafana Cloud Pro or Advanced plan or an activated on-prem Grafana Enterprise license.
• AWS credentials: An IAM user with an access key and secret key, a shared credentials file configured on the Grafana server, an EC2 instance role, or an IAM role to assume.
• DynamoDB permissions: The IAM identity must have dynamodb:PartiQLSelect permission on the tables you want to query. For write operations, additional PartiQL permissions may be needed.

Key concepts

If you’re new to AWS, these terms are used throughout the configuration:

Add the data source

To add the data source:

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

Configure settings

The following table describes the available connection settings:

Authentication

The DynamoDB data source supports the standard AWS authentication methods provided by the shared AWS connection component. Choose the method that fits your deployment.

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

Access keys

Use static IAM access keys to authenticate directly with AWS. This is the default authentication method.

To configure access key authentication:

1. Select Access & secret key from the Authentication Provider drop-down.
2. Enter your Access Key ID.
3. Enter your Secret Access Key.
4. Optionally, enter a Session Token if using temporary credentials.
5. Select your Default Region.

AWS credentials file

Use a shared credentials file stored on the Grafana server to authenticate. This method reads credentials from ~/.aws/credentials.

To configure credentials file authentication:

1. Select Credentials file from the Authentication Provider drop-down.
2. Enter the Credentials Profile Name if you use a non-default profile.
3. Select your Default Region.

EC2 IAM role

Use the IAM role attached to the EC2 instance (or the IAM Role for Service Accounts, IRSA, in Kubernetes) that Grafana is running on. No credentials are entered in the data source configuration.

To configure EC2 IAM role authentication:

1. Select EC2 IAM Role from the Authentication Provider drop-down.
2. Select your Default Region.

AWS SDK Default

Use the default AWS SDK credential chain, which checks environment variables, shared configuration files, and container/instance metadata, in that order.

To configure AWS SDK Default authentication:

1. Select AWS SDK Default from the Authentication Provider drop-down.
2. Select your Default Region.

Grafana Assume Role

Available only in Grafana Cloud. Use temporary credentials managed by Grafana to assume an IAM role on your behalf.

To configure Grafana Assume Role authentication:

1. Select Grafana Assume Role from the Authentication Provider drop-down.
2. Select your Default Region.

Assume role

You can layer an assumed IAM role on top of any of the authentication methods described above (except Grafana Assume Role, which manages its own role). This is commonly used for cross-account access to DynamoDB tables.

To configure an assumed role:

1. Configure one of the base authentication methods above.
2. Enter the Assume Role ARN.
3. Optionally, enter an External ID if required by the role’s trust policy.

Verify the connection

Click Save & test to verify the connection. A Data source is working message confirms that Grafana can connect to your DynamoDB instance.

If the test fails, refer to Troubleshoot DynamoDB data source issues for common errors and solutions.

Provision the data source

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

Advanced settings

The following optional settings are available through provisioning only and don’t appear in the UI:

Include these in jsonData to override the defaults.

Access key provisioning

YAML Copy

apiVersion: 1

datasources:
  - name: DynamoDB
    type: grafana-dynamodb-datasource
    jsonData:
      authType: keys
      defaultRegion: us-west-2
      isV2: true
    secureJsonData:
      accessKey: <ACCESS_KEY_ID>
      secretKey: <SECRET_ACCESS_KEY>

To include a session token for temporary credentials, add sessionToken to secureJsonData:

YAML Copy

apiVersion: 1

datasources:
  - name: DynamoDB
    type: grafana-dynamodb-datasource
    jsonData:
      authType: keys
      defaultRegion: us-west-2
      isV2: true
    secureJsonData:
      accessKey: <ACCESS_KEY_ID>
      secretKey: <SECRET_ACCESS_KEY>
      sessionToken: <SESSION_TOKEN>

Credentials file provisioning

YAML Copy

apiVersion: 1

datasources:
  - name: DynamoDB
    type: grafana-dynamodb-datasource
    jsonData:
      authType: credentials
      defaultRegion: us-west-2
      profile: <PROFILE_NAME>
      isV2: true

Assume role provisioning

Add assumeRoleARN (and optionally externalId) to jsonData on top of any base authentication method. For example, with access keys:

YAML Copy

apiVersion: 1

datasources:
  - name: DynamoDB
    type: grafana-dynamodb-datasource
    jsonData:
      authType: keys
      defaultRegion: us-west-2
      assumeRoleARN: <ROLE_ARN>
      externalId: <EXTERNAL_ID>
      isV2: true
    secureJsonData:
      accessKey: <ACCESS_KEY_ID>
      secretKey: <SECRET_ACCESS_KEY>

Provision with Terraform

You can provision the DynamoDB data source using the Grafana Terraform provider.

hcl Copy

resource "grafana_data_source" "dynamodb" {
  type = "grafana-dynamodb-datasource"
  name = "DynamoDB"

  json_data_encoded = jsonencode({
    authType      = "keys"
    defaultRegion = "us-west-2"
    isV2          = true
  })

  secure_json_data_encoded = jsonencode({
    accessKey = var.aws_access_key_id
    secretKey = var.aws_secret_access_key
  })
}

For credentials file authentication:

hcl Copy

resource "grafana_data_source" "dynamodb" {
  type = "grafana-dynamodb-datasource"
  name = "DynamoDB"

  json_data_encoded = jsonencode({
    authType      = "credentials"
    defaultRegion = "us-west-2"
    profile       = "my-profile"
    isV2          = true
  })
}