AWS integration via CloudFormation

This guide shows how to deploy the Dash0 AWS integration using Terraform's aws_cloudformation_stackCopy resource.

[!NOTE] This is not a native Dash0 provider resource. It uses the AWS provider to deploy a CloudFormation stack with the official Dash0 integration template.

The integration provisions the required IAM roles and configuration for collecting telemetry from your AWS account. The template additionally provisions, via a CloudFormation StackSet, per-region resources for the AWS/LambdaCopy namespace — a Kinesis Firehose delivery stream, a CloudWatch metric stream and an S3 backup bucket — and, optionally, an EventBridge rule, ApiDestination, and Connection that forward Lambda lifecycle events (UpdateFunctionConfigurationCopy, DeleteFunctionCopy) to Dash0 in near real-time.

Prerequisites

• An active Dash0 organization.
• A Dash0 API key (auth token), created under Settings > Auth Tokens in the Dash0 UI.
• Your Dash0 regional endpoint base URL, found under Settings > Endpoints > AWS CloudWatch Metrics in the Dash0 UI (for example https://ingress.eu-west-1.aws.dash0.comCopy). Provide only the base URL — the template appends the required paths internally.
• An AWS account with permissions to create CloudFormation stacks, StackSets, and IAM roles.
• Terraform >= 1.0 and the AWS provider >= 5.0.
• To collect Lambda lifecycle events (enabled by default), a CloudTrail trail logging management events in each region listed in RegionsCopy. Most AWS accounts already have an org-wide trail; if yours does not, either enable one or set CollectLambdaLifecycleEventsCopy to "false"Copy.

Example Usage

A complete, runnable example is available in examples/guides/aws_cloudformation_integration/Copy.

The core resource definition is:

12345678910111213141516
resource "aws_cloudformation_stack" "dash0_integration" {
  name         = "dash0-integration"
  template_url = "https://public-integrations-production.eu-west-1.aws.dash0.com.s3.eu-west-1.amazonaws.com/dash0-customer-integration-cloudformation-v2.yaml"

  parameters = {
    ApiKey                       = var.api_key
    Dataset                      = var.dataset
    ResourcesInstrumentation     = var.resources_instrumentation
    CollectLambdaLifecycleEvents = var.collect_lambda_lifecycle_events
    TechnicalId                  = var.technical_id
    Regions                      = join(",", var.regions)
    Dash0RegionalEndpoint        = var.dash0_regional_endpoint
  }

  capabilities = ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]
}

The CAPABILITY_NAMED_IAMCopy capability is required because the template creates named IAM roles for the Dash0 integration. The CAPABILITY_AUTO_EXPANDCopy capability is required because the v2 template includes a nested AWS::CloudFormation::StackSetCopy that deploys the per-region Dash0 resources (Lambda metrics streaming and, optionally, Lambda lifecycle event forwarding).

CloudFormation expects RegionsCopy to be a CommaDelimitedListCopy, so the Terraform list variable is joined into a comma-separated string before being passed to the stack.

CloudFormation Parameters

Getting Started

1. Copy the example directory into your project, or use the resource definition above in your own configuration.

2. Create a terraform.tfvarsCopy file with your values (do not commit this file):

   hcl

   Copy

   123
   api_key                 = "your-dash0-auth-token"
   dash0_regional_endpoint = "https://ingress.eu-west-1.aws.dash0.com"
   regions                 = ["eu-west-1"]

3. Initialize and apply:

   shell

   Copy

   123
   terraform init
   terraform plan
   terraform apply

4. To tear down the integration:

   shell

   Copy

   1
   terraform destroy

Notes

• The api_keyCopy variable is marked as sensitiveCopy so Terraform will not display its value in plan or apply output.
• The TechnicalIdCopy parameter is optional. When omitted or left empty, the template derives the IAM external ID from the CloudFormation stack ID. This is the recommended approach for Terraform onboarding — no Dash0-internal identifier is required.
• The CloudFormation stack is region-specific. Deploy it in the region where your AWS workloads run, or in the region closest to your Dash0 environment. The RegionsCopy parameter controls which regions the nested StackSet provisions Lambda metrics streaming into; it is independent from the region the parent stack itself is deployed in.
• The S3 backup bucket created by the StackSet is retained on terraform destroyCopy by design. Delete it manually if you want to fully reclaim the bucket name before re-onboarding.