@deotio/cdk-grafana

AWS CDK constructs for deploying and managing AWS Managed Grafana workspaces.

Features

• GrafanaWorkspace — L3 construct that provisions a Managed Grafana workspace with a service role, service account, and service account token
• GrafanaInfraStack — ready-to-deploy stack with Secrets Manager storage, SSM parameter discovery, GitHub Actions OIDC federation, and cross-account access
• RemovalPolicyAspect — CDK aspect to set removal policies across all resources in a construct tree
• Built-in cdk-nag suppressions with documented justifications

Installation

npm install @deotio/cdk-grafana

Peer dependencies

npm install aws-cdk-lib constructs cdk-nag

Quick start

import { App } from 'aws-cdk-lib';
import { GrafanaInfraStack } from '@deotio/cdk-grafana';

const app = new App();

new GrafanaInfraStack(app, 'GrafanaInfra', {
  workspaceName: 'my-grafana',
  environment: 'prod',
  orgId: 'o-abc123',
  secretAccessOuPaths: ['o-abc123/r-root/ou-xxxx/*'],
  ssmPrefix: '/grafana/prod',
  githubRepo: 'my-org/my-repo',
});

Using the L3 construct directly

import { GrafanaWorkspace } from '@deotio/cdk-grafana';

const workspace = new GrafanaWorkspace(this, 'Grafana', {
  workspaceName: 'my-grafana',
  orgId: 'o-abc123',
});

// workspace.endpoint — the workspace URL
// workspace.workspaceId — the workspace ID
// workspace.serviceAccountTokenKey — the service account token

API reference

GrafanaWorkspaceProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | workspaceName | string | Yes | Name of the Grafana workspace | | grafanaVersion | string | No | Grafana version (default: 10.4) | | orgId | string | Yes | AWS Organizations ID for cross-account role assumption |

GrafanaInfraStackProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | workspaceName | string | Yes | Name of the Grafana workspace | | grafanaVersion | string | No | Grafana version (default: 10.4) | | environment | string | Yes | Environment label (e.g., prod) | | orgId | string | Yes | AWS Organizations ID | | secretAccessOuPaths | string[] | Yes | OU paths granted cross-account read access to the token secret | | ssmPrefix | string | Yes | SSM parameter prefix (e.g., /grafana/prod) | | githubRepo | string | Yes | GitHub repository slug for OIDC federation (e.g., org/repo) | | existingGitHubOidcArn | string | No | ARN of existing GitHub OIDC provider | | githubActionsRoleName | string | No | Name for the GitHub Actions IAM role (default: github-actions-grafana) |

Development

npm ci          # install dependencies
npm run build   # compile TypeScript
npm test        # run tests
npm run lint    # lint source and tests

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache-2.0