Documentation Plugins AWS IoT TwinMaker Configure

Configure the AWS IoT TwinMaker app and data source

This document explains how to install the AWS IoT TwinMaker app and configure the bundled data source.

Before you begin

Before you configure the data source, ensure you have:

• Grafana permissions: The Organization administrator role. Only organization administrators can install plugins and add data sources.
• An AWS account with an AWS IoT TwinMaker workspace.
• An IAM role for your workspace: Follow the AWS IoT TwinMaker dashboard IAM role guide to create policies and a role with minimal permissions for your TwinMaker workspace. The data source requires this role’s Amazon Resource Name.

Key concepts

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

Install the app plugin

To install the AWS IoT TwinMaker app:

1. Navigate to Administration > Plugins and data > Plugins.
2. Search for AWS IoT TwinMaker App.
3. Click Install.

The app is enabled automatically after installation, which registers the data source, the four panels, and the transformation. On self-managed Grafana, you can also install the plugin with the CLI:

Bash Copy

grafana cli plugins install grafana-iot-twinmaker-app

Restart Grafana after a CLI installation.

Add the data source

To add the AWS IoT TwinMaker data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type AWS IoT TwinMaker in the search bar. The data source is listed in the Industrial & IoT section.
4. Select AWS IoT TwinMaker.
5. Click Add new data source.

Configure connection details

The Connection Details section uses the standard Grafana AWS authentication settings. For details about each authentication provider, refer to AWS authentication.

Why an assume role is required

The credentials resolved from the authentication provider are used for AWS calls made by the backend plugin. The same credentials are also used in the browser by the Scene Viewer and Video Player panels, so the plugin assumes the role you provide with an inline session policy to ensure a narrow permission scope. Only permissions that intersect with the inline policy are used.

Configure TwinMaker settings

The Twinmaker Settings section selects the workspace and optionally enables write access for the Alarm Configuration panel.

To configure the workspace:

1. Click Save & test. The first save returns the error Missing WorkspaceID configuration, which is expected because you haven’t selected a workspace yet.
2. Open the Workspace drop-down and select your workspace. Any query that uses this data source has access to resources within the selected workspace.
3. Click Save & test again.

Verify the connection

When the connection succeeds, Save & test returns the message TwinMaker datasource successfully configured followed by your workspace name. If the health check fails, refer to Troubleshooting for common errors such as Assume Role ARN is required.

Private data source connect

Private data source connect (PDC) lets Grafana Cloud reach AWS endpoints in a private network through a secure SOCKS proxy.

When PDC is enabled for your Grafana instance, the configuration page shows a Secure Socks Proxy section. Toggle Enable Secure Socks Proxy to route data source traffic through the PDC agent.

For setup instructions, refer to Private data source connect and Configure Grafana private data source connect.

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.

YAML Copy

apiVersion: 1

datasources:
  - name: AWS IoT TwinMaker
    type: grafana-iot-twinmaker-datasource
    jsonData:
      authType: default
      defaultRegion: us-east-1
      assumeRoleArn: arn:aws:iam::<ACCOUNT_ID>:role/<DASHBOARD_ROLE>
      workspaceId: <WORKSPACE_ID>
      # Optional settings:
      # externalId: <EXTERNAL_ID>
      # assumeRoleArnWriter: arn:aws:iam::<ACCOUNT_ID>:role/<WRITE_ROLE>
      # enableSecureSocksProxy: true

To provision static credentials instead of the default SDK credential chain, set authType: keys and provide the keys in secureJsonData:

YAML Copy

    secureJsonData:
      accessKey: <ACCESS_KEY_ID>
      secretKey: <SECRET_ACCESS_KEY>

Provision with Terraform

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

Assume role with Terraform

This example uses the default SDK credential chain and assumes the IAM role you created for your TwinMaker workspace.

hcl Copy

resource "grafana_data_source" "twinmaker" {
  type = "grafana-iot-twinmaker-datasource"
  name = "AWS IoT TwinMaker"

  json_data_encoded = jsonencode({
    authType      = "default"
    defaultRegion = "us-east-1"
    assumeRoleArn = "arn:aws:iam::123456789012:role/grafana-twinmaker-dashboard"
    workspaceId   = var.twinmaker_workspace_id
  })
}

To enable writes for the Alarm Configuration panel or route traffic through private data source connect, add the optional keys to json_data_encoded:

hcl Copy

  json_data_encoded = jsonencode({
    authType               = "default"
    defaultRegion          = "us-east-1"
    assumeRoleArn          = "arn:aws:iam::123456789012:role/grafana-twinmaker-dashboard"
    workspaceId            = var.twinmaker_workspace_id
    externalId             = var.external_id
    assumeRoleArnWriter    = "arn:aws:iam::123456789012:role/grafana-twinmaker-writer"
    enableSecureSocksProxy = true
  })

Access and secret key with Terraform

This example uses static credentials, which Grafana stores encrypted in secure JSON data.

hcl Copy

resource "grafana_data_source" "twinmaker" {
  type = "grafana-iot-twinmaker-datasource"
  name = "AWS IoT TwinMaker"

  json_data_encoded = jsonencode({
    authType      = "keys"
    defaultRegion = "us-east-1"
    assumeRoleArn = "arn:aws:iam::123456789012:role/grafana-twinmaker-dashboard"
    workspaceId   = var.twinmaker_workspace_id
  })

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

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

Next steps

• Build queries with the query editor
• Set up the Scene Viewer and other panels
• Import the pre-built dashboards