cdk-cost-analyzer 0.1.1

package/examples/multi-stack/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "cdk-cost-analyzer-multi-stack-example",
+  "version": "1.0.0",
+  "description": "Multi-stack CDK application example with cost analysis",
+  "bin": {
+    "multi-stack": "bin/app.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "jest",
+    "cdk": "cdk",
+    "synth": "cdk synth",
+    "deploy": "cdk deploy --all",
+    "deploy:networking": "cdk deploy NetworkingStack",
+    "deploy:compute": "cdk deploy ComputeStack",
+    "deploy:storage": "cdk deploy StorageStack",
+    "diff": "cdk diff"
+  },
+  "keywords": [
+    "aws",
+    "cdk",
+    "multi-stack",
+    "cost-analysis",
+    "example"
+  ],
+  "author": "ANWB",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.2",
+    "aws-cdk": "^2.233.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "aws-cdk-lib": "^2.233.0",
+    "constructs": "^10.4.2"
+  }
+}

package/examples/multi-stack/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": [
+      "es2020"
+    ],
+    "declaration": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": false,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false,
+    "typeRoots": [
+      "./node_modules/@types"
+    ],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "exclude": [
+    "node_modules",
+    "cdk.out"
+  ]
+}

package/examples/simple/base.json

@@ -0,0 +1,8 @@
+{
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {}
+    }
+  }
+}

package/examples/simple/target.json

@@ -0,0 +1,14 @@
+{
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {}
+    },
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "InstanceType": "t3.micro"
+      }
+    }
+  }
+}

package/examples/single-stack/.cdk-cost-analyzer.yml

@@ -0,0 +1,52 @@
+# CDK Cost Analyzer Configuration
+# This file configures cost thresholds and usage assumptions for cost analysis
+
+# Cost thresholds for pipeline enforcement
+thresholds:
+  default:
+    warning: 50   # USD per month - displays warning but passes pipeline
+    error: 200    # USD per month - fails pipeline, requires review
+
+# Custom usage assumptions for cost estimation
+# Adjust these values to match your expected application usage
+usageAssumptions:
+  # Amazon S3 usage patterns
+  s3:
+    storageGB: 100           # Expected storage size in GB
+    getRequests: 50000       # Monthly GET requests
+    putRequests: 5000        # Monthly PUT requests
+    dataTransferGB: 50       # Monthly data transfer out in GB
+
+  # AWS Lambda usage patterns
+  lambda:
+    invocationsPerMonth: 1000000  # Monthly function invocations
+    averageDurationMs: 200        # Average execution duration in milliseconds
+    memoryMB: 512                 # Allocated memory in MB
+
+  # Amazon DynamoDB usage patterns
+  dynamodb:
+    readCapacityUnits: 5     # Provisioned read capacity units
+    writeCapacityUnits: 5    # Provisioned write capacity units
+    storageGB: 10            # Expected data storage in GB
+
+  # Amazon API Gateway usage patterns
+  apiGateway:
+    requestsPerMonth: 1000000  # Monthly API requests
+
+# CDK synthesis configuration (optional)
+synthesis:
+  appPath: .                 # Path to CDK application
+  outputPath: cdk.out        # CDK synthesis output directory
+
+# Resource exclusions (optional)
+# Exclude specific resource types from cost analysis
+exclusions:
+  resourceTypes:
+    - AWS::IAM::Role         # IAM roles have no direct cost
+    - AWS::IAM::Policy       # IAM policies have no direct cost
+    - AWS::Logs::LogGroup    # CloudWatch Logs analyzed separately
+
+# Cache configuration
+cache:
+  enabled: true              # Enable pricing data caching
+  durationHours: 24          # Cache duration in hours

package/examples/single-stack/.gitlab-ci.yml

@@ -0,0 +1,126 @@
+# GitLab CI/CD Pipeline with CDK Cost Analysis
+# This pipeline runs cost analysis on merge requests to prevent unexpected infrastructure costs
+
+stages:
+  - build
+  - test
+  - cost-analysis
+  - deploy
+
+variables:
+  AWS_REGION: us-east-1
+  CDK_APP_PATH: examples/single-stack
+  NODE_VERSION: "18"
+
+# Install dependencies for the application
+build:
+  stage: build
+  image: node:${NODE_VERSION}
+  script:
+    - echo "Installing dependencies..."
+    - npm ci
+    - cd ${CDK_APP_PATH}
+    - npm ci
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+      - ${CDK_APP_PATH}/node_modules/
+  artifacts:
+    paths:
+      - node_modules/
+      - ${CDK_APP_PATH}/node_modules/
+    expire_in: 1 hour
+
+# Run application tests
+test:
+  stage: test
+  image: node:${NODE_VERSION}
+  dependencies:
+    - build
+  script:
+    - cd ${CDK_APP_PATH}
+    - npm test
+  only:
+    - merge_requests
+    - main
+
+# Analyze infrastructure cost changes for merge requests
+cost-analysis:
+  stage: cost-analysis
+  image: node:${NODE_VERSION}
+  dependencies:
+    - build
+  before_script:
+    # Install CDK Cost Analyzer globally
+    - npm install -g cdk-cost-analyzer
+    # Verify AWS credentials are configured
+    - |
+      if [ -z "$AWS_ACCESS_KEY_ID" ] || [ -z "$AWS_SECRET_ACCESS_KEY" ]; then
+        echo "ERROR: AWS credentials not configured"
+        echo "Please configure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as CI/CD variables"
+        exit 1
+      fi
+  script:
+    - echo "Analyzing infrastructure cost changes..."
+    - cd ${CDK_APP_PATH}
+    # Run cost analysis with automatic CDK synthesis
+    - |
+      cdk-cost-analyzer pipeline \
+        --base-branch ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME} \
+        --target-branch ${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} \
+        --cdk-app-path . \
+        --region ${AWS_REGION} \
+        --format markdown \
+        --post-to-gitlab
+  cache:
+    key: pricing-cache
+    paths:
+      - .cdk-cost-analyzer-cache/
+  artifacts:
+    reports:
+      # Store cost analysis report as artifact
+      dotenv: cost-analysis.env
+    paths:
+      - cost-report.md
+    expire_in: 30 days
+  only:
+    - merge_requests
+  allow_failure: false  # Fail pipeline if cost threshold exceeded
+
+# Deploy to AWS (requires manual approval if cost threshold exceeded)
+deploy:
+  stage: deploy
+  image: node:${NODE_VERSION}
+  dependencies:
+    - build
+  before_script:
+    - npm install -g aws-cdk
+  script:
+    - cd ${CDK_APP_PATH}
+    - echo "Deploying infrastructure to AWS..."
+    - cdk deploy --require-approval never
+  only:
+    - main
+  when: manual
+  environment:
+    name: production
+    action: start
+
+# Optional: Deploy to development environment automatically
+deploy:dev:
+  stage: deploy
+  image: node:${NODE_VERSION}
+  dependencies:
+    - build
+  before_script:
+    - npm install -g aws-cdk
+  script:
+    - cd ${CDK_APP_PATH}
+    - echo "Deploying to development environment..."
+    - cdk deploy --require-approval never
+  only:
+    - develop
+  environment:
+    name: development
+    action: start

package/examples/single-stack/README.md

@@ -0,0 +1,184 @@
+# Single-Stack CDK Cost Analyzer Example
+
+This example demonstrates how to integrate CDK Cost Analyzer into a basic single-stack CDK application with GitLab CI/CD pipeline integration.
+
+## Project Structure
+
+```
+single-stack/
+├── bin/
+│   └── app.ts              # CDK application entry point
+├── lib/
+│   └── infrastructure-stack.ts  # Infrastructure stack definition
+├── .cdk-cost-analyzer.yml  # Cost analyzer configuration
+├── .gitlab-ci.yml          # GitLab CI pipeline
+├── cdk.json                # CDK configuration
+├── package.json            # Node.js dependencies
+├── tsconfig.json           # TypeScript configuration
+└── README.md               # This file
+```
+
+## Infrastructure Overview
+
+This example creates a simple web application infrastructure:
+
+- **Amazon S3**: Static website hosting bucket
+- **AWS Lambda**: API backend function
+- **Amazon DynamoDB**: Data storage table
+- **Amazon API Gateway**: REST API endpoint
+
+## 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/single-stack
+npm install
+```
+
+### 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
+
+Edit `.cdk-cost-analyzer.yml` to adjust cost thresholds and usage assumptions for your needs.
+
+## Local Development
+
+### Synthesize CloudFormation Template
+
+```bash
+cdk synth
+```
+
+### Deploy Infrastructure
+
+```bash
+cdk deploy
+```
+
+### Run Cost Analysis Locally
+
+```bash
+# Install cost analyzer
+npm install -g cdk-cost-analyzer
+
+# Analyze cost impact
+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 automatic cost analysis for merge requests.
+
+### Pipeline Stages
+
+1. **Build**: Install dependencies
+2. **Test**: Run application tests
+3. **Cost Analysis**: Analyze infrastructure cost changes
+4. **Deploy**: Deploy to AWS (manual approval required if cost threshold exceeded)
+
+### Cost Thresholds
+
+The pipeline enforces cost thresholds defined in `.cdk-cost-analyzer.yml`:
+
+- **Warning**: $50/month - Pipeline passes but displays warning
+- **Error**: $200/month - Pipeline fails, requires manual review
+
+### Viewing Cost Reports
+
+Cost analysis results appear as comments on merge requests, showing:
+
+- Total monthly cost change
+- Per-resource cost breakdown
+- Threshold status
+- Configuration summary
+
+## Customizing Usage Assumptions
+
+Edit `.cdk-cost-analyzer.yml` to reflect your actual usage patterns:
+
+```yaml
+usageAssumptions:
+  s3:
+    storageGB: 100          # Expected storage size
+    getRequests: 50000      # Monthly GET requests
+    putRequests: 5000       # Monthly PUT requests
+  lambda:
+    invocationsPerMonth: 1000000  # Monthly invocations
+    averageDurationMs: 200        # Average execution time
+  dynamodb:
+    readCapacityUnits: 5    # Provisioned read capacity
+    writeCapacityUnits: 5   # Provisioned write capacity
+```
+
+## Troubleshooting
+
+### Synthesis Fails in Pipeline
+
+**Issue**: CDK synthesis fails with dependency errors
+
+**Solution**: Ensure all dependencies are installed in the build stage:
+
+```yaml
+build:
+  script:
+    - npm ci
+    - cd examples/single-stack && npm ci
+```
+
+### Missing AWS Credentials
+
+**Issue**: Pipeline fails with "Unable to locate credentials"
+
+**Solution**: Configure AWS credentials as GitLab CI/CD variables:
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_REGION`
+
+### Cost Threshold Exceeded
+
+**Issue**: Pipeline fails due to cost threshold violation
+
+**Solution**: Review the cost report in the merge request comment:
+1. Identify resources contributing to cost increase
+2. Optimize resource configuration if possible
+3. Request threshold override approval if increase is justified
+4. Update thresholds in `.cdk-cost-analyzer.yml` if appropriate
+
+## Next Steps
+
+- Review [Configuration Documentation](../../docs/CONFIGURATION.md) for advanced options
+- Explore [Multi-Stack Example](../multi-stack/) for complex applications
+- Check [Troubleshooting Guide](../../docs/TROUBLESHOOTING.md) for common issues
+
+## Additional Resources
+
+- [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/single-stack/bin/app.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { InfrastructureStack } from '../lib/infrastructure-stack';
+
+const app = new cdk.App();
+
+new InfrastructureStack(app, 'SingleStackExample', {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
+  },
+  description: 'Single-stack CDK Cost Analyzer example - Basic web application infrastructure',
+});
+
+app.synth();

package/examples/single-stack/cdk.json

@@ -0,0 +1,72 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": [
+      "aws",
+      "aws-cn"
+    ],
+    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+    "@aws-cdk/aws-iam:minimizePolicies": true,
+    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+    "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+    "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+    "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true,
+    "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
+    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+    "@aws-cdk/aws-route53-patters:useCertificate": true,
+    "@aws-cdk/customresources:installLatestAwsSdkDefault": false,
+    "@aws-cdk/aws-rds:databaseProxyUniqueResourceName": true,
+    "@aws-cdk/aws-codedeploy:removeAlarmsFromDeploymentGroup": true,
+    "@aws-cdk/aws-apigateway:authorizerChangeDeploymentLogicalId": true,
+    "@aws-cdk/aws-ec2:launchTemplateDefaultUserData": true,
+    "@aws-cdk/aws-secretsmanager:useAttachedSecretResourcePolicyForSecretTargetAttachments": true,
+    "@aws-cdk/aws-redshift:columnId": true,
+    "@aws-cdk/aws-stepfunctions-tasks:enableEmrServicePolicyV2": true,
+    "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": true,
+    "@aws-cdk/aws-apigateway:requestValidatorUniqueId": true,
+    "@aws-cdk/aws-kms:aliasNameRef": true,
+    "@aws-cdk/aws-autoscaling:generateLaunchTemplateInsteadOfLaunchConfig": true,
+    "@aws-cdk/core:includePrefixInUniqueNameGeneration": true,
+    "@aws-cdk/aws-efs:denyAnonymousAccess": true,
+    "@aws-cdk/aws-opensearchservice:enableOpensearchMultiAzWithStandby": true,
+    "@aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion": true,
+    "@aws-cdk/aws-efs:mountTargetOrderInsensitiveLogicalId": true,
+    "@aws-cdk/aws-rds:auroraClusterChangeScopeOfInstanceParameterGroupWithEachParameters": true,
+    "@aws-cdk/aws-appsync:useArnForSourceApiAssociationIdentifier": true,
+    "@aws-cdk/aws-rds:preventRenderingDeprecatedCredentials": true,
+    "@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeCommitSource": true,
+    "@aws-cdk/aws-cloudwatch-actions:changeLambdaPermissionLogicalIdForLambdaAction": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeysDefaultValueToFalse": true,
+    "@aws-cdk/aws-codepipeline:defaultPipelineTypeToV2": true,
+    "@aws-cdk/aws-kms:reduceCrossAccountRegionPolicyScope": true,
+    "@aws-cdk/aws-eks:nodegroupNameAttribute": true,
+    "@aws-cdk/aws-ec2:ebsDefaultGp3Volume": true,
+    "@aws-cdk/aws-ecs:removeDefaultDeploymentAlarm": true,
+    "@aws-cdk/custom-resources:logApiResponseDataPropertyTrueDefault": false
+  }
+}

package/examples/single-stack/lib/infrastructure-stack.ts

@@ -0,0 +1,119 @@
+import * as cdk from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+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';
+
+/**
+ * Single-stack infrastructure for a basic web application
+ * 
+ * This stack demonstrates common AWS resources that CDK Cost Analyzer can estimate:
+ * - S3 bucket for static website hosting
+ * - Lambda function for API backend
+ * - DynamoDB table for data storage
+ * - API Gateway for REST API endpoint
+ */
+export class InfrastructureStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    // S3 bucket for static website hosting
+    const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
+      bucketName: `${cdk.Stack.of(this).account}-website-${cdk.Stack.of(this).region}`,
+      websiteIndexDocument: 'index.html',
+      websiteErrorDocument: 'error.html',
+      publicReadAccess: true,
+      blockPublicAccess: {
+        blockPublicAcls: false,
+        blockPublicPolicy: false,
+        ignorePublicAcls: false,
+        restrictPublicBuckets: false,
+      },
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+    });
+
+    // DynamoDB table for application data
+    const dataTable = new dynamodb.Table(this, 'DataTable', {
+      tableName: 'application-data',
+      partitionKey: {
+        name: 'id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      billingMode: dynamodb.BillingMode.PROVISIONED,
+      readCapacity: 5,
+      writeCapacity: 5,
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+    });
+
+    // Lambda function for API backend
+    const apiFunction = new lambda.Function(this, 'ApiFunction', {
+      functionName: 'api-handler',
+      runtime: lambda.Runtime.NODEJS_18_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromInline(`
+        exports.handler = async (event) => {
+          return {
+            statusCode: 200,
+            headers: {
+              'Content-Type': 'application/json',
+              'Access-Control-Allow-Origin': '*',
+            },
+            body: JSON.stringify({
+              message: 'Hello from Lambda!',
+              timestamp: new Date().toISOString(),
+            }),
+          };
+        };
+      `),
+      memorySize: 512,
+      timeout: cdk.Duration.seconds(30),
+      environment: {
+        TABLE_NAME: dataTable.tableName,
+      },
+    });
+
+    // Grant Lambda function permissions to access DynamoDB
+    dataTable.grantReadWriteData(apiFunction);
+
+    // API Gateway REST API
+    const api = new apigateway.RestApi(this, 'Api', {
+      restApiName: 'Application API',
+      description: 'REST API for the application',
+      deployOptions: {
+        stageName: 'prod',
+        throttlingRateLimit: 100,
+        throttlingBurstLimit: 200,
+      },
+      defaultCorsPreflightOptions: {
+        allowOrigins: apigateway.Cors.ALL_ORIGINS,
+        allowMethods: apigateway.Cors.ALL_METHODS,
+      },
+    });
+
+    // API Gateway integration with Lambda
+    const lambdaIntegration = new apigateway.LambdaIntegration(apiFunction);
+    api.root.addMethod('GET', lambdaIntegration);
+
+    const itemsResource = api.root.addResource('items');
+    itemsResource.addMethod('GET', lambdaIntegration);
+    itemsResource.addMethod('POST', lambdaIntegration);
+
+    // Stack outputs
+    new cdk.CfnOutput(this, 'WebsiteUrl', {
+      value: websiteBucket.bucketWebsiteUrl,
+      description: 'Static website URL',
+    });
+
+    new cdk.CfnOutput(this, 'ApiUrl', {
+      value: api.url,
+      description: 'API Gateway endpoint URL',
+    });
+
+    new cdk.CfnOutput(this, 'TableName', {
+      value: dataTable.tableName,
+      description: 'DynamoDB table name',
+    });
+  }
+}