grafana-aws-sdk-react

@grafana/aws-sdk is Grafana Labs’ internal-turned-public toolkit for building the frontend half of AWS data source plugins — CloudWatch, Athena, Redshift, OpenSearch, Timestream, DynamoDB, IoT SiteWise, X-Ray, and the managed Prometheus/Amazon plugins all share it rather than each reimplementing AWS auth forms from scratch.

Its centerpiece, ConnectionConfig, renders the full authentication picker (access keys, shared credentials profile, EC2 IAM role, Grafana Assume Role, AWS SDK default chain), the Assume Role ARN and external ID flow — including the newer per-datasource external ID minting and its save-time warning banner — an optional HTTP proxy section, and default-region selection, all wired directly into Grafana’s DataSourcePluginOptionsEditorProps shape. A SIGV4ConnectionConfig variant covers services that authenticate via SigV4 instead.

A second sql module supplies the pieces a SQL-based AWS plugin’s query editor needs: a code editor wrapper, format and fill-value selects, a resource selector for browsing AWS resources, and template-variable helpers for filtering and substituting $variable references inside raw SQL. A useConfigSaveReporter hook reports save-success/failure interaction events through Grafana’s plugin analytics.

Because every consuming plugin is itself part of the Grafana ecosystem, the package tracks Grafana’s release cadence closely (peer dependency on @grafana/plugin-ui, devDependencies pinned to a specific @grafana/* line) and changes are driven by feature toggles like awsDatasourcesTempCredentials and awsAssumeRolePerDatasourceExternalId that roll out new auth behavior gradually across the whole plugin fleet.

What You Get

• ConnectionConfig - a drop-in datasource config-page component covering AWS auth provider selection, Assume Role ARN + external ID (including per-datasource external ID minting), optional HTTP proxy settings, and default region.
• SIGV4ConnectionConfig - a variant of the connection config for services that authenticate via AWS SigV4 signing rather than the standard auth-provider list.
• SQL query editor pieces - QueryEditorHeader, QueryCodeEditor, FormatSelect, FillValueSelect/FillValueOptions, and ConfigSelect/InlineInput for building a SQL-based AWS plugin’s query editor.
• ResourceSelector - a reusable async selector component for browsing AWS resources (tables, log groups, etc.) inside a query editor.
• SQL template-variable utilities - filterSQLQuery, applySQLTemplateVariables, and appendTemplateVariablesAsSuggestions for handling Grafana $variable substitution in raw SQL.
• useConfigSaveReporter hook - reports datasource-test success/failure events through Grafana’s plugin interaction analytics.
• Shared types and constants - AwsAuthType, AwsAuthDataSourceJsonData/SecureJsonData/Settings, standardRegions, and awsAuthProviderOptions so every consuming plugin models AWS auth state the same way.

Common Use Cases

• New AWS data source plugin - a team building a new Grafana data source for an AWS service drops in ConnectionConfig instead of writing an auth-provider picker and Assume Role flow from scratch.
• SQL-based AWS plugins - plugins like Athena or Redshift use the sql module’s query editor header, code editor, and fill-value/format selects to get a consistent SQL editing experience.
• Migrating to Grafana Assume Role - existing plugins adopt the shared Assume Role + external ID UI, including the per-datasource external ID rollout gated behind a feature toggle.
• SigV4-signed services - a plugin whose backend authenticates via SigV4 rather than the standard AWS credential chain uses SIGV4ConnectionConfig instead of the default component.
• Template-variable-aware SQL editors - plugins that need to substitute Grafana dashboard variables into raw SQL use filterSQLQuery/applySQLTemplateVariables rather than reimplementing variable interpolation.

Under The Hood

Architecture The package has two parallel surfaces layered over Grafana’s plugin SDK types: a components module centered on ConnectionConfig (and SIGV4ConnectionConfig) that composes @grafana/ui primitives (Select, Field, Collapse, Switch, Alert) into a full datasource config page driven entirely by props (options, onOptionsChange) rather than internal data fetching, and a sql module of independent, smaller editor-piece components (QueryEditorHeader, QueryCodeEditor, FillValueSelect, ResourceSelector) meant to be assembled by each consuming plugin’s own query editor. State that must survive across saves — like per-datasource external ID minting and its change-warning banner — is tracked with refs keyed off options.version so the component can tell a fresh mount from a post-save re-render. A small useConfigSaveReporter hook subscribes to Grafana’s global app-event bus for test-success/failure telemetry, decoupling analytics from the render path entirely.

Tech Stack TypeScript throughout, built as a dual ESM/CJS package via Rollup (rollup-plugin-esbuild, rollup-plugin-dts, rollup-plugin-node-externals) with publint validating the resulting package layout. The UI layer depends on Grafana’s own @grafana/ui, @grafana/data, @grafana/runtime, and @grafana/plugin-ui packages (the latter as a peer dependency, keeping the actual runtime version choice with the consuming plugin), plus rxjs for event-stream handling. Linting runs through Grafana’s shared @grafana/eslint-config plus Prettier and cspell, and lefthook wires these into pre-commit hooks.

Code Quality Every non-trivial component and utility ships with a co-located Jest test file (ConnectionConfig.test.tsx, SIGV4ConnectionConfig.test.tsx, useConfigSaveReporter.test.ts, ResourceSelector.test.tsx, and tests for each SQL editor piece), using @testing-library/react and react-select-event for interaction testing and @swc/jest for fast TS compilation. Types are strict and exported explicitly (ConnectionConfigProps, SQLQuery) rather than inferred implicitly, deprecated auth values are marked with JSDoc @deprecated tags instead of silently removed, and GitHub Actions run push-triggered CI plus an automated npm publish workflow.

What Makes It Unique Rather than being a generic AWS SDK wrapper, this package encodes Grafana-specific product decisions directly into reusable UI — the gradual per-datasource external ID migration (feature-toggle gated, with a save-time warning when the toggle changes and legacy shared-stack IDs still supported), the distinction between Grafana Cloud stack-derived external IDs and CloudWatch’s own /external-id endpoint, and datasource-type allowlists (DS_TYPES_THAT_SUPPORT_TEMP_CREDS) that let one shared component behave differently per consuming plugin without forking it.