Documentation Plugins Amazon Aurora Configure

Configure the Amazon Aurora data source

This document explains how to configure the Amazon Aurora data source and how to provision it with YAML or Terraform.

Before you begin

Before you configure the data source, ensure you have:

• Grafana permissions: Organization administrator role.
• An Aurora cluster with IAM database authentication enabled: Refer to the AWS IAM database authentication documentation.
• A database user configured for IAM authentication: Refer to the AWS guide to creating a database account using IAM authentication.
• AWS credentials with the rds-db:connect permission: Refer to the following example IAM permissions.
• Network access: Grafana must be able to reach your cluster endpoint. For private clusters in Grafana Cloud, use private data source connect. For MySQL-compatible engines, Grafana also needs outbound HTTPS access to s3.amazonaws.com to download the RDS certificate bundle when it opens a connection.

Example IAM permissions

The AWS user or role that Grafana uses to query Aurora must have the rds-db:connect permission for your cluster and database user. For example:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["rds-db:connect"],
      "Resource": ["arn:aws:rds-db:us-east-2:1234567890:dbuser:cluster-ABCDEFGHIJKL01234/db_user"]
    }
  ]
}

For more information, refer to the AWS IAM database authentication policy documentation.

Key concepts

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

Add the data source

To add the Amazon Aurora data source:

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

Connection details

The plugin uses the AWS SDK for Go to obtain AWS credentials, then exchanges them for a temporary RDS authentication token that it uses as the database password. Configure how Grafana obtains AWS credentials in the Connection Details section.

Authentication

Assume role

Optionally, configure the Assume Role section to have the selected authentication provider assume a role rather than use its credentials directly. The base credentials must have sts:AssumeRole permission for the target role.

Additional settings

Database settings

Configure the connection to your Aurora cluster in the Database Settings section.

Separate host and port for authentication

To connect to your cluster, Grafana makes two calls:

1. It generates an RDS authentication token for an endpoint.
2. It opens an SQL connection to your database host using that token.

Usually both steps use the same endpoint. However, if your cluster is behind a load balancer, the RDS token must be generated for the actual cluster endpoint while SQL connections go through the load balancer. In that case, configure the Advanced: Separate Host and Port for Auth section:

For example, set Database Host and Database Port to your load balancer endpoint, and set Advanced: DB Host For Auth and Advanced: DB Port For Auth to the cluster endpoint behind the load balancer.

Private data source connect

Private data source connect (PDC) lets Grafana Cloud reach Aurora clusters that aren’t exposed to the public internet. The plugin supports PDC for both PostgreSQL-compatible and MySQL-compatible engines and requires Grafana 10.0 or later.

To use PDC:

1. Configure a PDC agent in your network. Refer to Private data source connect.
2. In the data source settings, under Private data source connect, select your network in the Private data source connect network drop-down. The drop-down shows how many agents are connected for each network.
3. To set up or manage networks, click Manage private data source connect networks.

Verify the connection

Click Save & test to verify the connection. When the connection test passes, Grafana displays the message Data source is working.

Query caching

To reduce the load on your Aurora cluster and speed up repeated queries, you can enable query caching for the data source. Query caching is available in Grafana Cloud and Grafana Enterprise, and is turned off by default for each data source.

To enable it, open the data source settings, go to the Cache tab, and click Enable. You can optionally set custom TTLs for cached queries. For details, refer to Query and resource caching.

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 Provision Grafana.

The following provisioning properties are available:

YAML provisioning examples

The following example provisions the data source with access and secret keys:

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Aurora
    type: grafana-aurora-datasource
    editable: true
    jsonData:
      authType: keys
      engine: aurora-postgres
      defaultRegion: us-east-1
      dbName: testDatabase
      dbUser: db_user
      dbHost: example.cluster-ro-example.us-east-1.rds.amazonaws.com
      dbPort: 5432
    secureJsonData:
      accessKey: <AWS_ACCESS_KEY_ID>
      secretKey: <AWS_SECRET_ACCESS_KEY>
    version: 1

The following example uses the AWS SDK default credentials chain, which supports service-based IAM roles:

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Aurora
    type: grafana-aurora-datasource
    editable: true
    jsonData:
      authType: default
      engine: aurora-mysql
      defaultRegion: us-east-1
      dbName: testDatabase
      dbUser: db_user
      dbHost: aurora-mysql.cluster-123.us-east-1.rds.amazonaws.com
      dbPort: 3306
    version: 1

The following example configures a cluster behind a load balancer, with a separate host and port for generating the authentication token:

YAML Copy

apiVersion: 1

datasources:
  - name: Amazon Aurora behind a load balancer
    type: grafana-aurora-datasource
    editable: true
    jsonData:
      authType: keys
      engine: aurora-mysql
      defaultRegion: us-east-1
      dbName: testDatabase
      dbUser: db_user
      dbHost: protected-by-a-load-balancer.example.com
      dbPort: 3307
      dbHostAuth: aurora-mysql.cluster-123.us-east-1.rds.amazonaws.com
      dbPortAuth: 3306
    secureJsonData:
      accessKey: <AWS_ACCESS_KEY_ID>
      secretKey: <AWS_SECRET_ACCESS_KEY>
    version: 1

Provision with Terraform

You can also provision the data source with the Grafana Terraform provider using the grafana_data_source resource. The json_data_encoded and secure_json_data_encoded arguments accept the same keys as the YAML jsonData and secureJsonData properties.

hcl Copy

terraform {
  required_providers {
    grafana = {
      source = "grafana/grafana"
    }
  }
}

resource "grafana_data_source" "aurora" {
  type = "grafana-aurora-datasource"
  name = "Amazon Aurora"

  json_data_encoded = jsonencode({
    authType      = "keys"
    engine        = "aurora-postgres"
    defaultRegion = "us-east-1"
    dbName        = "testDatabase"
    dbUser        = "db_user"
    dbHost        = "example.cluster-ro-example.us-east-1.rds.amazonaws.com"
    dbPort        = 5432
  })

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

Store secrets such as AWS keys in Terraform variables or a secrets manager instead of hard-coding them in your configuration.

Next steps

• Amazon Aurora query editor
• Template variables
• Troubleshooting