CDK Cost Analyzer


A TypeScript package that analyzes AWS CDK infrastructure changes and provides cost impact summaries. Compare CloudFormation templates to understand the financial implications of your infrastructure changes before deployment.

Key Features

- Single Template Analysis: Analyze individual CloudFormation templates for estimated monthly costs without comparison
- Template Comparison: Parse and diff CloudFormation templates (JSON/YAML) to identify added, removed, and modified resources
- Cost Estimation: Calculate monthly costs for AWS resources using real-time AWS Pricing API data
- Automatic CDK Synthesis: Optionally synthesize CDK applications in CI/CD pipelines
- Cost Threshold Enforcement: Fail pipelines when cost increases exceed configured thresholds
- Configuration Management: Project-specific configuration for thresholds, usage assumptions, and exclusions
- Dual Interface: Use as a CLI tool for quick analysis or import as a library for programmatic integration
- Clear Reporting: Generate formatted cost reports in text, JSON, or Markdown formats
- GitLab Integration: Post cost analysis reports as comments on GitLab merge requests
- FinOps Awareness: Help developers understand cost implications during the development cycle

Use Cases

- Analyze single CloudFormation templates for cost estimation
- Analyze infrastructure changes in GitLab merge requests
- Estimate costs before deploying CDK applications
- Enforce cost approval gates in CI/CD pipelines
- Compare different infrastructure configurations
- Promote cost-conscious development practices

Installation

``bash
npm install cdk-cost-analyzer
`

AWS Credentials

CDK Cost Analyzer requires AWS credentials to query the AWS Pricing API for real-time cost data.

$3

`bash


Via environment variables

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

Or via AWS CLI configuration

aws configure
`

$3

The AWS credentials must have permission to call the Pricing API:

`json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"pricing:GetProducts",
"pricing:DescribeServices"
],
"Resource": "*"
}
]
}
`

For CI/CD environments, configure credentials as secrets/variables in your pipeline. See the CI/CD Integration Guide for detailed setup instructions.

Documentation

- Configuration Guide - Configure thresholds, usage assumptions, and exclusions
- CI/CD Integration - GitHub Actions and GitLab CI/CD setup guides
- Resource Calculator Reference - Detailed cost calculation methods and assumptions
- Troubleshooting Guide - Common issues and solutions
- Development Guide - Local development, testing, and architecture
- Release Process - How to release new versions
- Examples - Example templates and API usage demonstrations

Quick Start

$3

`bash


Analyze a single CloudFormation template

cdk-cost-analyzer analyze template.json --region us-east-1

Analyze with different output formats

cdk-cost-analyzer analyze template.yaml --format markdown
cdk-cost-analyzer analyze template.json --format json

Compare two CloudFormation templates

cdk-cost-analyzer compare base-template.json target-template.json --region eu-central-1

Use pipeline command with automatic synthesis

cdk-cost-analyzer pipeline \
--synth \
--cdk-app-path ./infrastructure \
--region eu-central-1 \
--config .cdk-cost-analyzer.yml

Generate Markdown output

cdk-cost-analyzer compare base.yaml target.yaml --region us-east-1 --format markdown

Enable debug logging to troubleshoot pricing issues

cdk-cost-analyzer analyze template.yaml --debug
cdk-cost-analyzer compare base.yaml target.yaml --debug

Show help

cdk-cost-analyzer --help
cdk-cost-analyzer analyze --help
`

$3

Use the --debug flag to enable verbose logging for pricing API calls. This helps troubleshoot why pricing lookups might return $0.00 for resources:

`bash
cdk-cost-analyzer compare base.yaml target.yaml --debug
`

Debug mode logs the following information to stderr:
- Pricing API queries - Service type, filters, and region used in each query
- Pricing API responses - Product details, pricing information, and response metadata
- Filter values - Exact filter parameters sent to the AWS Pricing API
- Region normalization - Conversion from AWS region codes (e.g., us-east-1) to Pricing API region names (e.g., US East (N. Virginia))
- Cache status - Whether pricing data was retrieved from memory cache, persistent cache, or API
- Pricing failures - Detailed error messages when pricing lookups fail

Example debug output:
`
[DEBUG 2024-01-15T10:30:00.000Z] Region Normalization
{
"originalRegion": "us-east-1",
"normalizedRegion": "US East (N. Virginia)",
"wasNormalized": true
}

[DEBUG 2024-01-15T10:30:00.100Z] Pricing API Query
{
"serviceCode": "AWSLambda",
"region": "US East (N. Virginia)",
"filters": [
{
"field": "group",
"value": "AWS-Lambda-Requests",
"type": "TERM_MATCH"
}
]
}

[DEBUG 2024-01-15T10:30:00.500Z] Pricing API Response
{
"serviceCode": "AWSLambda",
"region": "US East (N. Virginia)",
"price": 0.0000002,
"productDetails": { ... }
}
`

Debug logging is disabled by default and does not interfere with normal output formats (text, JSON, or Markdown).

$3

Create .cdk-cost-analyzer.yml in your project:

`yaml


Cost thresholds

thresholds:
default:
warning: 50 # USD per month
error: 200
environments:
production:
warning: 25
error: 100

Custom usage assumptions

usageAssumptions:
s3:
storageGB: 500
natGateway:
dataProcessedGB: 500
alb:
newConnectionsPerSecond: 50
processedBytesGB: 1000

Resource exclusions

exclusions:
resourceTypes:
- AWS::IAM::Role
- AWS::Logs::LogGroup
`

See the Configuration Guide for complete documentation.

$3

Add to your .gitlab-ci.yml:

`yaml
cost-analysis:
stage: cost-analysis
image: node:18
before_script:
- npm install -g cdk-cost-analyzer
script:
- |
cdk-cost-analyzer pipeline \
--synth \
--cdk-app-path ./infrastructure \
--region $AWS_REGION \
--config .cdk-cost-analyzer.yml \
--format markdown \
--post-to-gitlab
only:
- merge_requests
`

See the CI/CD Integration Guide for complete documentation.

$3

Add to your .github/workflows/ci.yml:

`yaml
name: CI

on:
push:
branches: ['**']
pull_request:
branches: ['**']

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18.x'
cache: 'npm'
- run: npm ci
- run: npm run eslint
- run: npm run lint
- run: npm run build
- run: npm run test:silent
`

The GitHub Actions workflow automatically runs on every push and pull request, executing linting, type checking, build verification, and the complete test suite. See the CI/CD Integration Guide for complete documentation.

$3

See examples/api-usage.js for a complete working example.

#### Analyze a Single Template

`typescript
import { analyzeSingleTemplate } from 'cdk-cost-analyzer';

const result = await analyzeSingleTemplate({
template: templateContent, // CloudFormation template (JSON or YAML string)
region: 'us-east-1',
format: 'text' // or 'json', 'markdown'
});

console.log(Total monthly cost: $${result.totalMonthlyCost.toFixed(2)} ${result.currency});
console.log(Total resources: ${result.metadata.resourceCount});
console.log(Supported resources: ${result.metadata.supportedResourceCount});
console.log(result.summary); // Formatted report
`

#### Compare Two Templates

`typescript
import { analyzeCosts } from 'cdk-cost-analyzer';

const result = await analyzeCosts({
baseTemplate: baseTemplateContent,
targetTemplate: targetTemplateContent,
region: 'eu-central-1',
format: 'text' // or 'json', 'markdown'
});

console.log(Cost delta: ${result.totalDelta} ${result.currency});
console.log(Added resources: ${result.addedResources.length});
console.log(Removed resources: ${result.removedResources.length});
console.log(Modified resources: ${result.modifiedResources.length});
console.log(result.summary); // Formatted report
`

$3

Post cost analysis reports as comments on GitLab merge requests:

`typescript
import { analyzeCosts, GitLabIntegration } from 'cdk-cost-analyzer';

// Analyze costs
const result = await analyzeCosts({
baseTemplate: baseTemplateContent,
targetTemplate: targetTemplateContent,
region: 'eu-central-1',
format: 'markdown'
});

// Post to GitLab MR
const gitlab = GitLabIntegration.fromEnvironment();
await gitlab.postMergeRequestComment(
process.env.CI_PROJECT_ID!,
process.env.CI_MERGE_REQUEST_IID!,
result.summary
);
`

Configure in .gitlab-ci.yml:

`yaml
cost-analysis:
stage: test
script:
- npm install cdk-cost-analyzer
- cdk-cost-analyzer base.json target.json --format markdown > cost-report.md
- node -e "require('cdk-cost-analyzer').GitLabIntegration.fromEnvironment().postMergeRequestComment(process.env.CI_PROJECT_ID, process.env.CI_MERGE_REQUEST_IID, require('fs').readFileSync('cost-report.md', 'utf8'))"
only:
- merge_requests
`

Supported Resource Types

$3

- AWS::EC2::Instance - EC2 instances with on-demand pricing
- AWS::S3::Bucket - S3 buckets with storage and request costs
- AWS::Lambda::Function - Lambda functions with invocation and duration costs
- AWS::RDS::DBInstance - RDS database instances
- AWS::DynamoDB::Table - DynamoDB tables with provisioned or on-demand billing
- AWS::ECS::Service - ECS services with Fargate or EC2 launch types
- AWS::ApiGateway::RestApi - API Gateway REST APIs
- AWS::ApiGatewayV2::Api - API Gateway HTTP and WebSocket APIs

$3

- AWS::EC2::NatGateway - NAT Gateways with hourly and data processing costs
- AWS::ElasticLoadBalancingV2::LoadBalancer - Application and Network Load Balancers with LCU costs
- AWS::EC2::VPCEndpoint - VPC Endpoints (interface and gateway types)

$3

- AWS::CloudFront::Distribution - CloudFront distributions with data transfer and request costs

$3

- ElastiCache clusters
- EKS clusters
- And more...

Cost Calculation Assumptions

For resources with usage-based pricing, the following default assumptions are used:

$3

- S3 Buckets: 100 GB standard storage, 10,000 GET requests/month
- Lambda Functions: 1 million invocations/month, average 1-second duration
- RDS Instances: 100 GB storage, single-AZ deployment
- EC2 Instances: 730 hours/month (full month), on-demand pricing

$3

- DynamoDB Tables (Provisioned): 5 read capacity units, 5 write capacity units
- DynamoDB Tables (On-Demand): 10M read requests, 1M write requests per month (configurable)
- ECS Services (Fargate): 0.25 vCPU, 0.5 GB memory per task
- API Gateway (REST): 1M requests per month
- API Gateway (HTTP): 1M requests per month
- API Gateway (WebSocket): 1M messages, 100K connection minutes per month

$3

- NAT Gateway: 500 GB data processed per month
- Application Load Balancer: 50 new connections/sec, 5,000 active connections/min, 1,000 GB processed
- Network Load Balancer: 100 new connections/sec, 10,000 active connections/min, 1,000 GB processed
- VPC Endpoint (Interface): 100 GB data processed per month
- CloudFront Distribution: 100 GB data transfer out, 1M HTTP/HTTPS requests per month

These assumptions are documented in cost reports and can be customized via configuration file or by extending the calculator classes.

Report Formats

$3

`
============================================================
CDK Cost Analysis Report
============================================================

Total Cost Delta: +$245.60

ADDED RESOURCES:
------------------------------------------------------------
• MyEC2Instance (AWS::EC2::Instance): $30.40 [high]
• MyRDSInstance (AWS::RDS::DBInstance): $215.20 [high]

REMOVED RESOURCES:
------------------------------------------------------------
(none)

MODIFIED RESOURCES:
------------------------------------------------------------
(none)

============================================================
`

$3

Perfect for GitLab merge request comments:

`markdown


CDK Cost Analysis Report

Total Cost Delta: +$245.60

Added Resources

| Logical ID | Type | Monthly Cost |
|------------|------|--------------|
| MyEC2Instance | AWS::EC2::Instance | $30.40 |
| MyRDSInstance | AWS::RDS::DBInstance | $215.20 |

Modified Resources

| Logical ID | Type | Old Cost | New Cost | Delta |
|------------|------|----------|----------|-------|
| MyFunction | AWS::Lambda::Function | $50.00 | $75.00 | +$25.00 |
`

$3

For programmatic processing and integration:

`json
{
"totalDelta": 245.60,
"currency": "USD",
"addedCosts": [...],
"removedCosts": [...],
"modifiedCosts": [...]
}
`

Configuration

$3

The tool uses the AWS SDK default credential chain. Ensure you have AWS credentials configured:

`bash


Via environment variables

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

Or via AWS CLI configuration

aws configure
`

$3

Specify the AWS region for pricing data:

`bash


CLI

cdk-cost-analyzer base.json target.json --region eu-central-1

API

analyzeCosts({ baseTemplate, targetTemplate, region: 'eu-central-1' })
`

Default region: eu-central-1

$3

For GitLab integration, the following environment variables are used:

- CI_JOB_TOKEN or GITLAB_TOKEN: GitLab API authentication token
- CI_API_V4_URL: GitLab API URL (defaults to https://gitlab.com/api/v4)
- CI_PROJECT_ID: Project ID (automatically set in GitLab CI)
- CI_MERGE_REQUEST_IID: Merge request IID (automatically set in GitLab CI)

Error Handling

The tool handles errors gracefully:

- Invalid templates: Clear error messages for malformed JSON/YAML
- Missing pricing data: Resources marked as "unknown cost" with warnings
- API failures: Automatic retry with exponential backoff, fallback to cached data
- Unsupported resources: Marked as "unknown cost", analysis continues
- GitLab API errors: Descriptive error messages with HTTP status codes

Development Roadmap

$3

- Core template parsing and diffing
- Basic resource costing (EC2, S3, Lambda, RDS)
- CLI and programmatic API
- AWS Pricing API integration
- Text and JSON report formats

$3

- Markdown report formatter for GitLab MR comments
- GitLab integration module for posting reports
- Extended resource support (DynamoDB, ECS, API Gateway)
- Property-based testing with fast-check
- Comprehensive unit tests for all new features

$3

- Automatic CDK Synthesis: Synthesize CDK applications in CI/CD pipelines
- Cost Threshold Enforcement: Fail pipelines when costs exceed configured limits
- Configuration Management: Project-specific configuration files
- Additional Resource Calculators: NAT Gateway, ALB, NLB, VPC Endpoints
- Enhanced CLI: Pipeline command with synthesis and threshold support
- Comprehensive Documentation: Configuration guide, GitLab CI/CD examples

$3

- Multi-region cost analysis with regional breakdowns
- Historical cost tracking and trend analysis
- Cost optimization recommendations
- Support for Savings Plans and Reserved Instances
- Additional resource types (CloudFront, ElastiCache, EKS)
- GitHub Actions integration
- Slack/Teams notifications

Testing

The project includes comprehensive test coverage with both unit and property-based tests:

`bash


Run all tests

npm test

Run tests in watch mode

npm run test:watch

Build the project

npm run build

Type checking

npm run lint
`

Contributing

Contributions are welcome! Please see the implementation plan for current development tasks.

$3

This project uses Projen for project management. All project configuration is managed through .projenrc.ts.

`bash


Clone the repository

git clone https://gitlab.com/anwb/cdk-cost-analyzer.git
cd cdk-cost-analyzer

Install dependencies

npm install

Synthesize project files (after modifying .projenrc.ts)

npx projen

Build the project

npx projen build

Run tests

npx projen test

Run linting

npx projen lint

Compile TypeScript

npx projen compile
`

Important: Never manually edit generated files like package.json, tsconfig.json, or .gitignore. Always modify .projenrc.ts and run npx projen` to regenerate these files.

$3

See docs/RELEASE.md for detailed release instructions.

License

MIT

Acknowledgments

Inspired by Infracost for Terraform. Built for ANWB's CDK and GitLab CI/CD workflows.