cdk-grafana-json-dashboard-handler

A handler Custom Construct for JSON Grafana Dashboards - Deploy to Grafana using AWSCDK.

How it works

Declare the package as a dependency and import the Construct in your stack. Point it to your local Grafana dashboard file so the Construct can calculate an MD5 hash of it. This is needed as otherwise CloudFormation would not know when to redeploy your dashboard to Grafana when it changes. Upload your dashboard file in your CDK stack (s3assets, see example below), and pass the bucket and s3 file path to the Construct as well. Also, give the Construct a secret to resolve from SecretsManager in order to authenticate to your Grafana installation, in combination with the url where to find it. Finally give it a name so it can name your dashboard accordingly. Deploy!

Contents of the Custom Construct

The Construct contains a Lambda Singleton function, which gets wrapped by a CloudFormation Custom Resource.

Before using consider the following

1. This construct is geared towards deploying json dashboards. This construct does not cater towards DSL for creating and developing Grafana Dashboards. The construct assumes you will place this json dashboard somewhere in S3. Consider deploying it using new s3assets.BucketDeployment and then pass the object path & bucket name to the construct so it knows where to fetch it.
2. This construct assumes Bearer authorization, in which the value of Bearer is stored in AWS Secretsmanager, either plain or in an object for which you can specify the key, e.g. 'password' or {'pass' : 'password'}
3. This construct currently does NOT support custom KMS encrypted files in s3 (see roadmap below)

Grafana Handler

Implement as following:

Write your Grafana Dashboard JSON file somewhere to disk.

Use that Dashboard JSON in your stack as follows:

# Example automatically generated from non-compiling source. May contain errors.
# setup the dependencies for the construct, for example like this
bucket = s3.Bucket(self, "pogg",
    auto_delete_objects=True,
    removal_policy=cdk.RemovalPolicy.DESTROY
)

fdp = s3assets.BucketDeployment(self, "pogu",
    sources=[s3assets.Source.asset("test/dashboard")],
    destination_bucket=bucket,
    destination_key_prefix="test/test"
)

secret = sm.Secret.from_secret_partial_arn(self, "smLookup",
    get_required_env_variable("GRAFANA_SECRET_PARTIAL_ARN"))

# Example automatically generated from non-compiling source. May contain errors.
dbr = GrafanaHandler(self, "pog",
    dashboard_app_name="cdkConstructTest",
    grafana_pw_secret=secret,
    grafana_url=get_required_env_variable("GRAFANA_URL"),
    bucket_name=bucket.bucket_name,
    object_key="test/test/dashboard/test-dashboard.json",
    local_file_path="test/dashboard/test-dashboard.json"
)
dbr.node.add_dependency(fdp)

If your handler needs to live inside your projects networking tier:

# Example automatically generated from non-compiling source. May contain errors.
dbr = GrafanaHandler(self, "pog",
    dashboard_app_name="cdkConstructTest",
    grafana_pw_secret=secret,
    grafana_url=get_required_env_variable("GRAFANA_URL"),
    bucket_name=bucket.bucket_name,
    object_key="test/test/dashboard/test-dashboard.json",
    local_file_path="test/dashboard/test-dashboard.json",
    vpc=testing_vpc,
    vpc_subnets={
        "subnets": [testing_private_subnet_iD1, testing_private_subnet_iD2, testing_private_subnet_iD3
        ]
    }
)
dbr.node.add_dependency(fdp)

More permissions

Whenever your handler needs more permissions use the addToRolePolicy on the properties exposed on the construct:

# Example automatically generated from non-compiling source. May contain errors.
dbr = GrafanaHandler(self, "pog",
    dashboard_app_name="cdkConstructTest",
    grafana_pw=process.env.pw,  # pass in a string value. CDK supports resolving to string values from SSM and SecretsManager
    grafana_url=process.env.url,
    path_to_file="../src/test/test-dashboard.json",
    local_file_path="test/dashboard/test-dashboard.json"
)

dbr.grafana_handler_function.add_to_role_policy(
    iam.PolicyStatement(
        actions=["ec2:*"],
        resources=["*"]
    ))

Example deployment

TODO / Roadmap

1. Add custom KMS key support for the dashboard files in s3.
2. Reduce SecretsManager permissions