cdk-cost-analyzer 0.1.1

package/examples/monorepo/README.md

@@ -0,0 +1,341 @@
+# Monorepo CDK Cost Analyzer Example
+
+This example demonstrates how to integrate CDK Cost Analyzer into a monorepo structure with multiple independent CDK applications.
+
+## Project Structure
+
+```
+monorepo/
+├── packages/
+│   ├── frontend-infra/       # Frontend infrastructure (S3, CloudFront)
+│   │   ├── bin/
+│   │   ├── lib/
+│   │   ├── .cdk-cost-analyzer.yml
+│   │   ├── cdk.json
+│   │   └── package.json
+│   ├── backend-infra/        # Backend infrastructure (Lambda, API Gateway)
+│   │   ├── bin/
+│   │   ├── lib/
+│   │   ├── .cdk-cost-analyzer.yml
+│   │   ├── cdk.json
+│   │   └── package.json
+│   └── data-infra/           # Data infrastructure (RDS, DynamoDB)
+│       ├── bin/
+│       ├── lib/
+│       ├── .cdk-cost-analyzer.yml
+│       ├── cdk.json
+│       └── package.json
+├── .gitlab-ci.yml            # GitLab CI pipeline with parallel analysis
+├── package.json              # Root package.json for workspace
+└── README.md                 # This file
+```
+
+## Architecture Overview
+
+This monorepo contains three independent CDK applications:
+
+### Frontend Infrastructure
+- **Amazon S3**: Static website hosting
+- **Amazon CloudFront**: Content delivery network
+- **AWS Certificate Manager**: SSL/TLS certificates
+
+### Backend Infrastructure
+- **AWS Lambda**: Serverless API functions
+- **Amazon API Gateway**: REST API endpoints
+- **Amazon DynamoDB**: NoSQL database
+
+### Data Infrastructure
+- **Amazon RDS**: PostgreSQL database
+- **Amazon ElastiCache**: Redis cache
+- **AWS Backup**: Automated backup solution
+
+## Why Monorepo?
+
+Monorepo architectures provide several benefits:
+
+- **Code Sharing**: Share common constructs and utilities across applications
+- **Atomic Changes**: Update multiple applications in a single commit
+- **Consistent Tooling**: Unified build and deployment processes
+- **Independent Deployment**: Each application can be deployed separately
+- **Team Autonomy**: Different teams can own different applications
+
+## Prerequisites
+
+- Node.js 18 or later
+- AWS CDK CLI: `npm install -g aws-cdk`
+- AWS account with appropriate credentials
+- GitLab repository with CI/CD enabled
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+cd examples/monorepo
+npm install
+```
+
+This installs dependencies for all packages in the workspace.
+
+### 2. Configure AWS Credentials
+
+For local development:
+
+```bash
+export AWS_ACCESS_KEY_ID=your-access-key
+export AWS_SECRET_ACCESS_KEY=your-secret-key
+export AWS_REGION=us-east-1
+```
+
+For GitLab CI, configure these as CI/CD variables in your GitLab project settings.
+
+### 3. Bootstrap CDK (First Time Only)
+
+```bash
+cdk bootstrap aws://ACCOUNT-ID/REGION
+```
+
+### 4. Review Configuration
+
+Each package has its own `.cdk-cost-analyzer.yml` with application-specific thresholds and assumptions.
+
+## Local Development
+
+### Work with Specific Application
+
+```bash
+# Frontend infrastructure
+cd packages/frontend-infra
+cdk synth
+cdk deploy
+
+# Backend infrastructure
+cd packages/backend-infra
+cdk synth
+cdk deploy
+
+# Data infrastructure
+cd packages/data-infra
+cdk synth
+cdk deploy
+```
+
+### Run Cost Analysis for Specific Application
+
+```bash
+# Install cost analyzer
+npm install -g cdk-cost-analyzer
+
+# Analyze frontend infrastructure
+cd packages/frontend-infra
+cdk-cost-analyzer pipeline \
+  --base-branch main \
+  --target-branch feature/my-changes \
+  --region us-east-1
+
+# Analyze backend infrastructure
+cd packages/backend-infra
+cdk-cost-analyzer pipeline \
+  --base-branch main \
+  --target-branch feature/my-changes \
+  --region us-east-1
+```
+
+## GitLab CI/CD Integration
+
+The `.gitlab-ci.yml` file configures parallel cost analysis for all applications in the monorepo.
+
+### Pipeline Stages
+
+1. **Build**: Install dependencies for all packages
+2. **Test**: Run tests for all packages in parallel
+3. **Cost Analysis**: Analyze cost changes for each application in parallel
+4. **Deploy**: Deploy applications to AWS
+
+### Parallel Cost Analysis
+
+The pipeline runs cost analysis for each application independently and in parallel:
+
+```yaml
+cost-analysis:frontend:
+  # Analyzes frontend infrastructure changes
+  
+cost-analysis:backend:
+  # Analyzes backend infrastructure changes
+  
+cost-analysis:data:
+  # Analyzes data infrastructure changes
+```
+
+Each analysis job:
+- Has its own cost thresholds
+- Posts separate comments to merge requests
+- Can fail independently without blocking other analyses
+
+### Viewing Cost Reports
+
+Each application posts its own cost analysis comment to merge requests:
+
+```
+Frontend Infrastructure Cost Analysis
+======================================
+Total Cost Delta: +$25.00/month
+- CloudFront: +$20.00/month
+- S3: +$5.00/month
+
+Backend Infrastructure Cost Analysis
+====================================
+Total Cost Delta: +$45.00/month
+- Lambda: +$30.00/month
+- API Gateway: +$15.00/month
+
+Data Infrastructure Cost Analysis
+==================================
+Total Cost Delta: +$80.00/month
+- RDS: +$60.00/month
+- ElastiCache: +$20.00/month
+```
+
+## Application-Specific Configuration
+
+Each application has its own configuration file with appropriate thresholds:
+
+### Frontend Infrastructure
+```yaml
+thresholds:
+  default:
+    warning: 30
+    error: 100
+```
+
+### Backend Infrastructure
+```yaml
+thresholds:
+  default:
+    warning: 50
+    error: 200
+```
+
+### Data Infrastructure
+```yaml
+thresholds:
+  default:
+    warning: 100
+    error: 500
+```
+
+## Workspace Management
+
+This monorepo uses npm workspaces for dependency management:
+
+```json
+{
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+Benefits:
+- Single `node_modules` at root
+- Shared dependencies across packages
+- Faster installation
+- Consistent versions
+
+## Troubleshooting
+
+### Pipeline Runs All Analyses Even for Single Application Changes
+
+**Issue**: All cost analysis jobs run even when only one application changed
+
+**Solution**: This is intentional for simplicity. To optimize:
+
+1. Use GitLab CI rules to detect changed files
+2. Skip analysis jobs for unchanged applications
+3. Example:
+
+```yaml
+cost-analysis:frontend:
+  rules:
+    - changes:
+        - packages/frontend-infra/**/*
+```
+
+### Different Applications Have Different Cost Thresholds
+
+**Issue**: Need different thresholds for different applications
+
+**Solution**: Each application has its own `.cdk-cost-analyzer.yml` file. Configure thresholds independently:
+
+```yaml
+# packages/frontend-infra/.cdk-cost-analyzer.yml
+thresholds:
+  default:
+    warning: 30
+    error: 100
+
+# packages/data-infra/.cdk-cost-analyzer.yml
+thresholds:
+  default:
+    warning: 100
+    error: 500
+```
+
+### Dependency Conflicts Between Applications
+
+**Issue**: Different applications need different versions of the same dependency
+
+**Solution**: Use workspace overrides in root `package.json`:
+
+```json
+{
+  "overrides": {
+    "aws-cdk-lib": "^2.118.0"
+  }
+}
+```
+
+### Cost Analysis Takes Too Long
+
+**Issue**: Parallel analysis still takes too long
+
+**Solution**: 
+1. Enable pricing cache across all jobs
+2. Use GitLab CI cache with shared key
+3. Consider running analysis only on merge requests, not all commits
+
+## Best Practices
+
+### Monorepo Organization
+
+- **Keep applications independent**: Minimize cross-application dependencies
+- **Share common code**: Create shared packages for reusable constructs
+- **Consistent naming**: Use consistent naming conventions across applications
+- **Clear ownership**: Document which team owns which application
+
+### Cost Management
+
+- **Set appropriate thresholds**: Different applications have different cost profiles
+- **Review regularly**: Periodically review and adjust thresholds
+- **Track trends**: Monitor cost changes over time per application
+- **Optimize independently**: Each application can be optimized separately
+
+### Deployment Strategy
+
+- **Deploy independently**: Each application can be deployed on its own schedule
+- **Test thoroughly**: Test each application independently before deployment
+- **Use environments**: Maintain separate dev/staging/prod environments per application
+- **Coordinate dependencies**: If applications depend on each other, coordinate deployments
+
+## Next Steps
+
+- Review [Configuration Documentation](../../docs/CONFIGURATION.md) for advanced options
+- Explore [Single-Stack Example](../single-stack/) for simpler projects
+- Check [Troubleshooting Guide](../../docs/TROUBLESHOOTING.md) for common issues
+
+## Additional Resources
+
+- [npm Workspaces Documentation](https://docs.npmjs.com/cli/v8/using-npm/workspaces)
+- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/)
+- [CDK Cost Analyzer Documentation](../../README.md)
+- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)

package/examples/monorepo/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "cdk-cost-analyzer-monorepo-example",
+  "version": "1.0.0",
+  "description": "Monorepo CDK application example with cost analysis",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "test": "npm test --workspaces",
+    "clean": "npm run clean --workspaces"
+  },
+  "keywords": [
+    "aws",
+    "cdk",
+    "monorepo",
+    "cost-analysis",
+    "example"
+  ],
+  "author": "ANWB",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

package/examples/monorepo/packages/backend-infra/.cdk-cost-analyzer.yml

@@ -0,0 +1,34 @@
+# CDK Cost Analyzer Configuration for Backend Infrastructure
+
+thresholds:
+  default:
+    warning: 50   # USD per month
+    error: 200    # USD per month
+
+usageAssumptions:
+  lambda:
+    invocationsPerMonth: 2000000
+    averageDurationMs: 300
+    memoryMB: 512
+
+  apiGateway:
+    requestsPerMonth: 2000000
+
+  dynamodb:
+    readCapacityUnits: 10
+    writeCapacityUnits: 10
+    storageGB: 25
+
+synthesis:
+  appPath: .
+  outputPath: cdk.out
+
+exclusions:
+  resourceTypes:
+    - AWS::IAM::Role
+    - AWS::IAM::Policy
+    - AWS::Logs::LogGroup
+
+cache:
+  enabled: true
+  durationHours: 24

package/examples/monorepo/packages/backend-infra/bin/app.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { BackendStack } from '../lib/backend-stack';
+
+const app = new cdk.App();
+
+new BackendStack(app, 'BackendStack', {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
+  },
+  description: 'Monorepo example - Backend infrastructure (Lambda, API Gateway, DynamoDB)',
+});
+
+app.synth();

package/examples/monorepo/packages/backend-infra/cdk.json

@@ -0,0 +1,7 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
+  "context": {
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true
+  }
+}

package/examples/monorepo/packages/backend-infra/lib/backend-stack.ts

@@ -0,0 +1,128 @@
+import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import { Construct } from 'constructs';
+
+/**
+ * Backend infrastructure stack
+ * 
+ * Creates Lambda functions, API Gateway, and DynamoDB table
+ */
+export class BackendStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    // DynamoDB table
+    const table = new dynamodb.Table(this, 'DataTable', {
+      tableName: 'backend-data',
+      partitionKey: {
+        name: 'id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      sortKey: {
+        name: 'timestamp',
+        type: dynamodb.AttributeType.NUMBER,
+      },
+      billingMode: dynamodb.BillingMode.PROVISIONED,
+      readCapacity: 10,
+      writeCapacity: 10,
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+    });
+
+    // Lambda function for API handler
+    const apiHandler = new lambda.Function(this, 'ApiHandler', {
+      functionName: 'backend-api-handler',
+      runtime: lambda.Runtime.NODEJS_18_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromInline(`
+        const { DynamoDBClient, PutItemCommand, QueryCommand } = require('@aws-sdk/client-dynamodb');
+        const client = new DynamoDBClient({});
+        
+        exports.handler = async (event) => {
+          const tableName = process.env.TABLE_NAME;
+          
+          try {
+            if (event.httpMethod === 'POST') {
+              const body = JSON.parse(event.body);
+              await client.send(new PutItemCommand({
+                TableName: tableName,
+                Item: {
+                  id: { S: body.id },
+                  timestamp: { N: Date.now().toString() },
+                  data: { S: JSON.stringify(body.data) }
+                }
+              }));
+              return {
+                statusCode: 201,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ message: 'Item created' })
+              };
+            } else {
+              const result = await client.send(new QueryCommand({
+                TableName: tableName,
+                KeyConditionExpression: 'id = :id',
+                ExpressionAttributeValues: { ':id': { S: event.pathParameters.id } }
+              }));
+              return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(result.Items)
+              };
+            }
+          } catch (error) {
+            return {
+              statusCode: 500,
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ error: error.message })
+            };
+          }
+        };
+      `),
+      memorySize: 512,
+      timeout: cdk.Duration.seconds(30),
+      environment: {
+        TABLE_NAME: table.tableName,
+      },
+    });
+
+    // Grant Lambda permissions to access DynamoDB
+    table.grantReadWriteData(apiHandler);
+
+    // API Gateway
+    const api = new apigateway.RestApi(this, 'Api', {
+      restApiName: 'Backend API',
+      description: 'Backend REST API',
+      deployOptions: {
+        stageName: 'prod',
+        throttlingRateLimit: 100,
+        throttlingBurstLimit: 200,
+      },
+    });
+
+    // API Gateway integration
+    const integration = new apigateway.LambdaIntegration(apiHandler);
+    
+    const items = api.root.addResource('items');
+    items.addMethod('POST', integration);
+    
+    const item = items.addResource('{id}');
+    item.addMethod('GET', integration);
+
+    // Stack outputs
+    new cdk.CfnOutput(this, 'ApiUrl', {
+      value: api.url,
+      description: 'API Gateway endpoint URL',
+    });
+
+    new cdk.CfnOutput(this, 'TableName', {
+      value: table.tableName,
+      description: 'DynamoDB table name',
+    });
+
+    new cdk.CfnOutput(this, 'FunctionName', {
+      value: apiHandler.functionName,
+      description: 'Lambda function name',
+    });
+  }
+}

package/examples/monorepo/packages/backend-infra/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "backend-infra",
+  "version": "1.0.0",
+  "description": "Backend infrastructure CDK application",
+  "bin": {
+    "backend-infra": "bin/app.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "jest",
+    "cdk": "cdk",
+    "synth": "cdk synth",
+    "deploy": "cdk deploy",
+    "clean": "rm -rf cdk.out node_modules"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.2",
+    "aws-cdk": "^2.232.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "aws-cdk-lib": "^2.232.1",
+    "constructs": "^10.4.2"
+  }
+}

package/examples/monorepo/packages/backend-infra/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "exclude": [
+    "node_modules",
+    "cdk.out"
+  ]
+}

package/examples/monorepo/packages/data-infra/.cdk-cost-analyzer.yml

@@ -0,0 +1,38 @@
+# CDK Cost Analyzer Configuration for Data Infrastructure
+
+thresholds:
+  default:
+    warning: 100   # USD per month
+    error: 500     # USD per month
+
+usageAssumptions:
+  rds:
+    instanceClass: db.t3.medium
+    storageGB: 100
+    backupRetentionDays: 7
+    multiAZ: false
+
+  elasticache:
+    nodeType: cache.t3.micro
+    numNodes: 2
+    engineType: redis
+
+  s3:
+    storageGB: 1000
+    getRequests: 500000
+    putRequests: 50000
+    dataTransferGB: 200
+
+synthesis:
+  appPath: .
+  outputPath: cdk.out
+
+exclusions:
+  resourceTypes:
+    - AWS::IAM::Role
+    - AWS::IAM::Policy
+    - AWS::EC2::SecurityGroup
+
+cache:
+  enabled: true
+  durationHours: 24

package/examples/monorepo/packages/data-infra/bin/app.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { DataStack } from '../lib/data-stack';
+
+const app = new cdk.App();
+
+new DataStack(app, 'DataStack', {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
+  },
+  description: 'Monorepo example - Data infrastructure (RDS, ElastiCache, S3)',
+});
+
+app.synth();

package/examples/monorepo/packages/data-infra/cdk.json

@@ -0,0 +1,7 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
+  "context": {
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true
+  }
+}