cdk-cost-analyzer 0.1.1

package/examples/multi-stack/README.md

@@ -0,0 +1,279 @@
+# Multi-Stack CDK Cost Analyzer Example
+
+This example demonstrates how to integrate CDK Cost Analyzer into a multi-stack CDK application with separate networking, compute, and storage layers.
+
+## Project Structure
+
+```
+multi-stack/
+├── bin/
+│   └── app.ts              # CDK application entry point
+├── lib/
+│   ├── networking-stack.ts # VPC and networking resources
+│   ├── compute-stack.ts    # ECS and compute resources
+│   └── storage-stack.ts    # RDS and storage resources
+├── .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
+```
+
+## Architecture Overview
+
+This example creates a three-tier application infrastructure across multiple stacks:
+
+### Networking Stack
+- **Amazon VPC**: Virtual private cloud with public and private subnets
+- **NAT Gateway**: Network address translation for private subnet internet access
+- **VPC Endpoints**: Private connectivity to AWS services
+
+### Compute Stack
+- **Amazon ECS Cluster**: Container orchestration
+- **Application Load Balancer**: Traffic distribution
+- **ECS Service**: Containerized application
+
+### Storage Stack
+- **Amazon RDS**: PostgreSQL database
+- **Amazon ElastiCache**: Redis cache cluster
+- **Amazon S3**: Object storage for application data
+
+## Why Multi-Stack?
+
+Multi-stack architectures provide several benefits:
+
+- **Separation of Concerns**: Network, compute, and storage managed independently
+- **Deployment Flexibility**: Update individual layers without affecting others
+- **Resource Limits**: Stay within CloudFormation's 500-resource limit per stack
+- **Team Organization**: Different teams can own different stacks
+- **Cost Tracking**: Easier to track costs per infrastructure layer
+
+## 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/multi-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 All Stacks
+
+```bash
+cdk synth
+```
+
+### Deploy All Stacks
+
+```bash
+cdk deploy --all
+```
+
+### Deploy Individual Stack
+
+```bash
+cdk deploy NetworkingStack
+cdk deploy ComputeStack
+cdk deploy StorageStack
+```
+
+### Run Cost Analysis Locally
+
+```bash
+# Install cost analyzer
+npm install -g cdk-cost-analyzer
+
+# Analyze cost impact across all stacks
+cdk-cost-analyzer pipeline \
+  --base-branch main \
+  --target-branch feature/my-changes \
+  --region us-east-1
+```
+
+## Understanding Multi-Stack Cost Analysis
+
+When analyzing multi-stack applications, CDK Cost Analyzer:
+
+1. **Identifies All Stacks**: Automatically detects all CloudFormation templates
+2. **Per-Stack Analysis**: Calculates cost changes for each stack independently
+3. **Aggregated Total**: Sums costs across all stacks for total impact
+4. **Detailed Breakdown**: Shows which stack contributes most to cost changes
+
+### Example Cost Report
+
+```
+Cost Analysis Summary
+=====================
+
+Total Cost Delta: +$245.50/month
+
+Per-Stack Breakdown:
+- NetworkingStack: +$45.00/month
+  - NAT Gateway: +$32.40/month
+  - VPC Endpoints: +$12.60/month
+
+- ComputeStack: +$150.00/month
+  - ECS Tasks: +$120.00/month
+  - Application Load Balancer: +$30.00/month
+
+- StorageStack: +$50.50/month
+  - RDS Instance: +$35.00/month
+  - ElastiCache: +$15.50/month
+```
+
+## GitLab CI/CD Integration
+
+The `.gitlab-ci.yml` file configures automatic cost analysis for merge requests with multi-stack support.
+
+### Pipeline Stages
+
+1. **Build**: Install dependencies
+2. **Test**: Run application tests
+3. **Cost Analysis**: Analyze infrastructure cost changes across all stacks
+4. **Deploy**: Deploy stacks to AWS (manual approval required if cost threshold exceeded)
+
+### Cost Thresholds
+
+The pipeline enforces cost thresholds defined in `.cdk-cost-analyzer.yml`:
+
+- **Warning**: $100/month - Pipeline passes but displays warning
+- **Error**: $500/month - Pipeline fails, requires manual review
+
+Note: Thresholds apply to the total cost across all stacks.
+
+## Customizing Usage Assumptions
+
+Edit `.cdk-cost-analyzer.yml` to reflect your actual usage patterns:
+
+```yaml
+usageAssumptions:
+  natGateway:
+    dataProcessedGB: 500    # Monthly data processed through NAT Gateway
+  
+  alb:
+    newConnectionsPerSecond: 50
+    activeConnectionsPerMinute: 5000
+    processedBytesGB: 1000
+  
+  rds:
+    instanceClass: db.t3.medium
+    storageGB: 100
+    backupRetentionDays: 7
+  
+  elasticache:
+    nodeType: cache.t3.micro
+    numNodes: 2
+```
+
+## Stack Dependencies
+
+The stacks have the following dependencies:
+
+```
+NetworkingStack (base)
+    ↓
+ComputeStack (depends on VPC)
+    ↓
+StorageStack (depends on VPC and security groups)
+```
+
+CDK automatically handles deployment order based on these dependencies.
+
+## Troubleshooting
+
+### Stack Dependency Errors
+
+**Issue**: Deployment fails due to missing resources from other stacks
+
+**Solution**: Ensure stacks are deployed in the correct order:
+1. NetworkingStack first
+2. ComputeStack second
+3. StorageStack last
+
+Or use `cdk deploy --all` to deploy in dependency order automatically.
+
+### Cost Analysis Shows Unexpected Changes
+
+**Issue**: Cost report shows changes in stacks you didn't modify
+
+**Solution**: This is normal when:
+- Stack dependencies cause resource updates
+- CDK updates resource configurations automatically
+- Cross-stack references change
+
+Review the detailed per-stack breakdown to understand the changes.
+
+### Pipeline Timeout
+
+**Issue**: Cost analysis stage times out in GitLab CI
+
+**Solution**: Multi-stack analysis takes longer. Increase timeout:
+
+```yaml
+cost-analysis:
+  timeout: 15m  # Increase from default 1h
+```
+
+## Best Practices
+
+### Stack Organization
+
+- **Keep stacks focused**: Each stack should have a clear purpose
+- **Minimize cross-stack references**: Reduces coupling between stacks
+- **Use consistent naming**: Makes cost tracking easier
+
+### Cost Management
+
+- **Set per-stack budgets**: Track costs for each infrastructure layer
+- **Review stack-level changes**: Understand which layer drives cost increases
+- **Optimize expensive stacks**: Focus optimization efforts where they matter most
+
+### Deployment Strategy
+
+- **Deploy networking first**: Establish foundation before other resources
+- **Test incrementally**: Deploy and test each stack before moving to the next
+- **Use stack policies**: Protect critical resources from accidental updates
+
+## Next Steps
+
+- Review [Configuration Documentation](../../docs/CONFIGURATION.md) for advanced options
+- Explore [Monorepo Example](../monorepo/) for multiple applications
+- Check [Troubleshooting Guide](../../docs/TROUBLESHOOTING.md) for common issues
+
+## Additional Resources
+
+- [AWS CDK Multi-Stack Documentation](https://docs.aws.amazon.com/cdk/v2/guide/stack_how_to_create_multiple_stacks.html)
+- [CDK Cost Analyzer Documentation](../../README.md)
+- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)

package/examples/multi-stack/bin/app.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { NetworkingStack } from '../lib/networking-stack';
+import { ComputeStack } from '../lib/compute-stack';
+import { StorageStack } from '../lib/storage-stack';
+
+const app = new cdk.App();
+
+const env = {
+  account: process.env.CDK_DEFAULT_ACCOUNT,
+  region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
+};
+
+// Create networking stack (foundation)
+const networkingStack = new NetworkingStack(app, 'NetworkingStack', {
+  env,
+  description: 'Multi-stack example - Networking layer (VPC, NAT Gateway, VPC Endpoints)',
+});
+
+// Create compute stack (depends on networking)
+const computeStack = new ComputeStack(app, 'ComputeStack', {
+  env,
+  vpc: networkingStack.vpc,
+  description: 'Multi-stack example - Compute layer (ECS, ALB)',
+});
+
+// Create storage stack (depends on networking and compute)
+const storageStack = new StorageStack(app, 'StorageStack', {
+  env,
+  vpc: networkingStack.vpc,
+  appSecurityGroup: computeStack.appSecurityGroup,
+  description: 'Multi-stack example - Storage layer (RDS, ElastiCache, S3)',
+});
+
+app.synth();

package/examples/multi-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/multi-stack/lib/compute-stack.ts

@@ -0,0 +1,128 @@
+import * as cdk from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import * as elbv2 from 'aws-cdk-lib/aws-elasticloadbalancingv2';
+import { Construct } from 'constructs';
+
+export interface ComputeStackProps extends cdk.StackProps {
+  vpc: ec2.IVpc;
+}
+
+/**
+ * Compute stack - Application layer
+ * 
+ * Creates ECS cluster, Application Load Balancer, and containerized application
+ */
+export class ComputeStack extends cdk.Stack {
+  public readonly appSecurityGroup: ec2.SecurityGroup;
+
+  constructor(scope: Construct, id: string, props: ComputeStackProps) {
+    super(scope, id, props);
+
+    const { vpc } = props;
+
+    // Security group for application
+    this.appSecurityGroup = new ec2.SecurityGroup(this, 'AppSecurityGroup', {
+      vpc,
+      description: 'Security group for application containers',
+      allowAllOutbound: true,
+    });
+
+    // ECS Cluster
+    const cluster = new ecs.Cluster(this, 'Cluster', {
+      clusterName: 'multi-stack-cluster',
+      vpc,
+      containerInsights: true,
+    });
+
+    // Application Load Balancer
+    const alb = new elbv2.ApplicationLoadBalancer(this, 'ALB', {
+      loadBalancerName: 'multi-stack-alb',
+      vpc,
+      internetFacing: true,
+      deletionProtection: false,
+    });
+
+    // ALB Target Group
+    const targetGroup = new elbv2.ApplicationTargetGroup(this, 'TargetGroup', {
+      vpc,
+      port: 80,
+      protocol: elbv2.ApplicationProtocol.HTTP,
+      targetType: elbv2.TargetType.IP,
+      healthCheck: {
+        path: '/health',
+        interval: cdk.Duration.seconds(30),
+        timeout: cdk.Duration.seconds(5),
+        healthyThresholdCount: 2,
+        unhealthyThresholdCount: 3,
+      },
+    });
+
+    // ALB Listener
+    alb.addListener('HttpListener', {
+      port: 80,
+      protocol: elbv2.ApplicationProtocol.HTTP,
+      defaultTargetGroups: [targetGroup],
+    });
+
+    // ECS Task Definition
+    const taskDefinition = new ecs.FargateTaskDefinition(this, 'TaskDef', {
+      memoryLimitMiB: 1024,
+      cpu: 512,
+    });
+
+    // Container Definition
+    taskDefinition.addContainer('AppContainer', {
+      containerName: 'app',
+      image: ecs.ContainerImage.fromRegistry('nginx:latest'),
+      portMappings: [
+        {
+          containerPort: 80,
+          protocol: ecs.Protocol.TCP,
+        },
+      ],
+      logging: ecs.LogDrivers.awsLogs({
+        streamPrefix: 'app',
+      }),
+    });
+
+    // ECS Service
+    const service = new ecs.FargateService(this, 'Service', {
+      cluster,
+      taskDefinition,
+      desiredCount: 2,
+      assignPublicIp: false,
+      securityGroups: [this.appSecurityGroup],
+      vpcSubnets: {
+        subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
+      },
+    });
+
+    // Attach service to target group
+    service.attachToApplicationTargetGroup(targetGroup);
+
+    // Allow ALB to communicate with ECS tasks
+    this.appSecurityGroup.addIngressRule(
+      ec2.Peer.securityGroupId(alb.connections.securityGroups[0].securityGroupId),
+      ec2.Port.tcp(80),
+      'Allow traffic from ALB'
+    );
+
+    // Stack outputs
+    new cdk.CfnOutput(this, 'LoadBalancerDNS', {
+      value: alb.loadBalancerDnsName,
+      description: 'Application Load Balancer DNS name',
+      exportName: 'ComputeStack-LoadBalancerDNS',
+    });
+
+    new cdk.CfnOutput(this, 'ClusterName', {
+      value: cluster.clusterName,
+      description: 'ECS Cluster name',
+    });
+
+    new cdk.CfnOutput(this, 'ServiceName', {
+      value: service.serviceName,
+      description: 'ECS Service name',
+    });
+  }
+}

package/examples/multi-stack/lib/networking-stack.ts

@@ -0,0 +1,69 @@
+import * as cdk from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+
+/**
+ * Networking stack - Foundation layer
+ * 
+ * Creates VPC with public and private subnets, NAT Gateway, and VPC Endpoints
+ */
+export class NetworkingStack extends cdk.Stack {
+  public readonly vpc: ec2.Vpc;
+
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    // VPC with public and private subnets across 2 AZs
+    this.vpc = new ec2.Vpc(this, 'Vpc', {
+      vpcName: 'multi-stack-vpc',
+      maxAzs: 2,
+      natGateways: 1,  // Single NAT Gateway for cost optimization
+      subnetConfiguration: [
+        {
+          name: 'Public',
+          subnetType: ec2.SubnetType.PUBLIC,
+          cidrMask: 24,
+        },
+        {
+          name: 'Private',
+          subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
+          cidrMask: 24,
+        },
+      ],
+    });
+
+    // VPC Endpoint for S3 (Gateway endpoint - no cost)
+    this.vpc.addGatewayEndpoint('S3Endpoint', {
+      service: ec2.GatewayVpcEndpointAwsService.S3,
+    });
+
+    // VPC Endpoint for DynamoDB (Gateway endpoint - no cost)
+    this.vpc.addGatewayEndpoint('DynamoDbEndpoint', {
+      service: ec2.GatewayVpcEndpointAwsService.DYNAMODB,
+    });
+
+    // VPC Endpoint for ECR API (Interface endpoint - has cost)
+    this.vpc.addInterfaceEndpoint('EcrApiEndpoint', {
+      service: ec2.InterfaceVpcEndpointAwsService.ECR,
+      privateDnsEnabled: true,
+    });
+
+    // VPC Endpoint for ECR Docker (Interface endpoint - has cost)
+    this.vpc.addInterfaceEndpoint('EcrDockerEndpoint', {
+      service: ec2.InterfaceVpcEndpointAwsService.ECR_DOCKER,
+      privateDnsEnabled: true,
+    });
+
+    // Stack outputs
+    new cdk.CfnOutput(this, 'VpcId', {
+      value: this.vpc.vpcId,
+      description: 'VPC ID',
+      exportName: 'NetworkingStack-VpcId',
+    });
+
+    new cdk.CfnOutput(this, 'VpcCidr', {
+      value: this.vpc.vpcCidrBlock,
+      description: 'VPC CIDR block',
+    });
+  }
+}