Documentation Plugins AWS IoT SiteWise Configure

Configure the AWS IoT SiteWise data source

This document explains how to configure the AWS IoT SiteWise data source and provides links to related documentation.

Before you begin

Before you configure the data source, ensure you have:

• Grafana permissions: The Organization administrator role. Only organization administrators can add data sources.
• An AWS account with AWS IoT SiteWise enabled in at least one Region, or a configured SiteWise Edge gateway.
• AWS credentials or an IAM identity with read access to AWS IoT SiteWise. At a minimum, grant iotsitewise:List*, iotsitewise:Describe*, and iotsitewise:Get*. To use the SQL query editor, also grant iotsitewise:ExecuteQuery.

Attach the following example policy to the IAM identity. Omit iotsitewise:ExecuteQuery if you don’t use the SQL query editor.

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iotsitewise:List*",
        "iotsitewise:Describe*",
        "iotsitewise:Get*",
        "iotsitewise:ExecuteQuery"
      ],
      "Resource": "*"
    }
  ]
}

Key concepts

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

Add the data source

To add the AWS IoT SiteWise data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type AWS IoT SiteWise in the search bar.
4. Select AWS IoT SiteWise from the search results.
5. Click Add new data source.

Authentication

The AWS IoT SiteWise data source uses the same authentication system as the other AWS data sources in Grafana. In the data source settings, these options appear under Connection Details. Choose the method that matches your deployment.

Select the method from the Authentication Provider drop-down. The available options depend on the providers your Grafana administrator allows.

AWS SDK Default

This method uses the default AWS SDK credential chain, which resolves credentials from environment variables, shared configuration, or the container or instance role. Use it when Grafana runs on AWS infrastructure that already has AWS credentials available.

Workspace IAM Role

This method uses the IAM role attached to the Amazon EC2 instance that runs Grafana. Use it when Grafana runs on Amazon EC2 and you attach an instance profile with access to AWS IoT SiteWise.

Grafana Assume Role

This method lets Grafana assume an IAM role for temporary credentials without storing long-lived keys. It’s available in Grafana Cloud when your administrator enables it. Select Grafana Assume Role as the Authentication Provider, then expand How to create an IAM role for grafana to assume for the trust policy and steps. Create the role so it trusts the Grafana account, and enter its Amazon Resource Name in the Assume Role ARN field.

Access & secret key

This method uses a long-lived AWS access key ID and secret access key. Provide the following values.

Credentials file

This method reads credentials from an AWS shared credentials file on the Grafana server, typically at ~/.aws/credentials. Provide the profile name.

Assume Role

The Assume Role section appears for every authentication provider. Grafana can assume an IAM role instead of using the selected provider’s credentials directly.

Additional settings

Set the following options in the Additional Settings section.

Connect to private networks

AWS IoT SiteWise is usually reachable over public AWS endpoints. If you need to reach a private endpoint, such as a SiteWise Edge gateway or a service behind a private network that isn’t publicly accessible, use one of the following options.

Private data source connect (Grafana Cloud)

If you use Grafana Cloud, use Private data source connect (PDC) to securely connect Grafana Cloud to a private network without opening the network to inbound traffic. PDC establishes an outbound connection from an agent that runs inside your network.

When PDC is enabled for your Grafana Cloud instance, a Private data source connect section appears in the data source settings, which lets you query data that lives within a secured network without opening the network to inbound traffic from Grafana Cloud. Select the Private data source connect network where your endpoint is available.

For setup instructions, refer to Private data source connect.

Secure Socks proxy (self-managed Grafana)

On self-managed Grafana, if your administrator enables the secure Socks proxy, a Secure Socks Proxy section appears in the data source configuration so you can route requests through the proxy. This option requires Grafana version 10.0.0 or later. To enable it, configure the [secure_socks_datasource_proxy] section in the Grafana configuration file. For more information, refer to Configure Grafana.

Configure SiteWise Edge

SiteWise Edge lets you run AWS IoT SiteWise on an on-premises gateway. To connect to a gateway, select Edge as the Default Region. An explicit endpoint is required for Edge connections.

Select the Authentication Mode for the gateway.

Provide an SSL certificate for every Edge connection, including Standard mode.

To replace a saved certificate, click Reset and enter a new certificate.

For Linux and LDAP modes, also provide the following values.

Verify the connection

Click Save & test to verify the configuration. On success, Grafana returns OK. The data source runs a ListAssetModels request against AWS IoT SiteWise to confirm that the credentials and Region are valid.

If the test fails, refer to Troubleshooting.

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.

Access and secret key

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT SiteWise
    type: grafana-iot-sitewise-datasource
    jsonData:
      authType: keys
      defaultRegion: us-east-1
    secureJsonData:
      accessKey: <YOUR_ACCESS_KEY>
      secretKey: <YOUR_SECRET_KEY>

Credentials file

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT SiteWise
    type: grafana-iot-sitewise-datasource
    jsonData:
      authType: credentials
      defaultRegion: us-east-1
      profile: default

Assume role

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT SiteWise
    type: grafana-iot-sitewise-datasource
    jsonData:
      authType: keys
      defaultRegion: us-east-1
      assumeRoleArn: arn:aws:iam::123456789012:role/grafana-sitewise
      externalId: <YOUR_EXTERNAL_ID>
    secureJsonData:
      accessKey: <YOUR_ACCESS_KEY>
      secretKey: <YOUR_SECRET_KEY>

Edge gateway

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT SiteWise Edge
    type: grafana-iot-sitewise-datasource
    jsonData:
      defaultRegion: Edge
      endpoint: https://<YOUR_EDGE_GATEWAY_HOST>
      edgeAuthMode: linux
      edgeAuthUser: <YOUR_EDGE_USERNAME>
    secureJsonData:
      edgeAuthPass: <YOUR_EDGE_PASSWORD>
      cert: |
        -----BEGIN CERTIFICATE-----
        <YOUR_CERTIFICATE>
        -----END CERTIFICATE-----

The following table describes the provisioning keys.

Secure Socks proxy

To route a provisioned data source through the secure Socks proxy, set enableSecureSocksProxy to true.

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT SiteWise
    type: grafana-iot-sitewise-datasource
    jsonData:
      authType: keys
      defaultRegion: us-east-1
      enableSecureSocksProxy: true
    secureJsonData:
      accessKey: <YOUR_ACCESS_KEY>
      secretKey: <YOUR_SECRET_KEY>

Provision with Terraform

You can use the Grafana Terraform provider to provision the AWS IoT SiteWise data source as code. The following examples use the grafana_data_source resource.

Access and secret key with Terraform

hcl Copy

resource "grafana_data_source" "sitewise" {
  type = "grafana-iot-sitewise-datasource"
  name = "AWS IoT SiteWise"

  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
  })
}

To use temporary AWS credentials from STS, add sessionToken to secure_json_data_encoded:

hcl Copy

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

Assume role with Terraform

hcl Copy

resource "grafana_data_source" "sitewise" {
  type = "grafana-iot-sitewise-datasource"
  name = "AWS IoT SiteWise"

  json_data_encoded = jsonencode({
    authType      = "default"
    defaultRegion = "us-east-1"
    assumeRoleArn = "arn:aws:iam::123456789012:role/grafana-sitewise"
    externalId    = var.external_id
  })
}

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

Next steps

• AWS IoT SiteWise query editor
• Template variables