Skip to content

Commit 3ea68d2

Browse files
drduhedrduhe
committed
chore: updating cdk README.md
1 parent ee6748b commit 3ea68d2

File tree

1 file changed

+139
-31
lines changed

1 file changed

+139
-31
lines changed

‎cdk/README.md‎

Lines changed: 139 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,145 @@ Before deploying, ensure the following tools and resources are available:
1616

1717
---
1818

19+
## 🏗️ Stacks Overview
20+
21+
This CDK application deploys multiple stacks that work together to provide the complete Model Runner infrastructure. Understanding what each stack creates will help you plan your deployment and manage resources effectively.
22+
23+
### NetworkStack (`<project-name>-Network`)
24+
25+
The **NetworkStack** provides the foundational networking infrastructure that all other stacks depend on. It manages VPC creation or import and network security.
26+
27+
**Resources Created:**
28+
29+
- **VPC**: Either creates a new VPC or imports an existing one based on configuration
30+
- New VPCs include public and private subnets across 2 availability zones
31+
- CIDR block: `10.0.0.0/16` (configurable)
32+
- Internet Gateway for public subnets
33+
- NAT Gateway for private subnet egress
34+
- **Security Groups**: Network security rules for Model Runner services
35+
- **VPC Flow Logs**: Network traffic logging (enabled for production-like environments)
36+
- **Subnet Selection**: Configures which subnets to use for resource deployment
37+
38+
**Key Features:**
39+
40+
- Can import existing VPCs to integrate with your existing network infrastructure
41+
- Supports custom subnet and security group selection
42+
- Automatically configures proper routing for public and private subnets
43+
44+
---
45+
46+
### ModelRunnerStack (`<project-name>-ModelRunner`)
47+
48+
The **ModelRunnerStack** deploys the core Model Runner dataplane - the main application infrastructure that processes geospatial imagery and runs ML models.
49+
50+
**Resources Created:**
51+
52+
#### **Database (DynamoDB)**
53+
54+
- **Outstanding Image Requests Table**: Tracks pending image processing requests
55+
- **Image Request Table**: Stores image request status and metadata
56+
- **Features Table**: Stores extracted feature data from processed images
57+
- **Endpoint Statistics Table**: Tracks endpoint performance metrics
58+
- **Region Request Table**: Manages region-level processing requests
59+
- **AWS Backup Configuration**: Automated backups for production environments (when `prodLike: true`)
60+
61+
#### **Messaging (SQS & SNS)**
62+
63+
- **Image Request Queue**: Primary queue for image processing requests
64+
- **Region Request Queue**: Queue for region-level processing tasks
65+
- **Dead Letter Queues**: Handles failed messages from both request queues
66+
- **Image Status Topic** (optional): SNS topic for image processing status notifications
67+
- **Region Status Topic** (optional): SNS topic for region processing status notifications
68+
- **Status Queues** (optional): SQS queues subscribed to status topics
69+
70+
#### **Compute (ECS)**
71+
72+
- **ECS Cluster**: Container orchestration cluster for Model Runner tasks
73+
- **Fargate Service**: Serverless container service running Model Runner containers
74+
- **Task Definition**: Container configuration with CPU, memory, and environment variables
75+
- **Container Image**: Model Runner Docker image (built from source or pulled from registry)
76+
- **CloudWatch Log Group**: Centralized logging for all container logs
77+
- **ECS Roles**: IAM roles for task execution and task permissions
78+
79+
#### **Autoscaling**
80+
81+
- **ECS Service Autoscaler**: Automatically scales ECS tasks based on queue depth
82+
- **CloudWatch Alarms**: Monitors queue metrics to trigger scaling events
83+
- **Scaling Policies**: Configurable min/max task counts and scaling increments
84+
85+
#### **Output Sinks**
86+
87+
- **S3 Bucket** (optional): Stores processed output data and results
88+
- Includes access logging bucket
89+
- Versioning enabled for production environments
90+
- Server-side encryption enabled
91+
- **Kinesis Data Stream** (optional): Real-time streaming output for processed data
92+
93+
#### **Monitoring**
94+
95+
- **CloudWatch Dashboard** (optional): Pre-configured dashboard with key metrics
96+
- ECS service metrics (CPU, memory, task count)
97+
- Queue metrics (message count, visibility timeout)
98+
- Custom Model Runner metrics
99+
100+
**Key Features:**
101+
102+
- Fully serverless architecture using Fargate (no EC2 instances to manage)
103+
- Automatic scaling based on workload
104+
- Configurable resource allocation (CPU, memory, worker count)
105+
- Optional status notifications via SNS
106+
- Production-ready with backups, encryption, and monitoring
107+
108+
---
109+
110+
### IntegrationTestStack (`<project-name>-IntegrationTest`)
111+
112+
The **IntegrationTestStack** deploys test infrastructure for development and integration testing. This stack is only deployed when `deployIntegrationTests: true` in your configuration.
113+
114+
**Resources Created:**
115+
116+
#### **Test Imagery**
117+
118+
- **S3 Bucket**: Dedicated bucket for storing test imagery files
119+
- **Bucket Deployment**: Automatically uploads test images from local `cdk/assets/imagery/` directory
120+
- **Encryption**: Server-side encryption enabled
121+
- **Access Control**: Private bucket with proper IAM permissions
122+
123+
#### **Test Models**
124+
125+
- **SageMaker Endpoints**:
126+
- **Centerpoint Endpoint**: Object detection model endpoint
127+
- **Flood Endpoint**: Flood detection model endpoint
128+
- **Multi-Container Endpoint**: Multi-model inference endpoint
129+
- **HTTP Endpoint**: Container-based HTTP endpoint for testing HTTP model integration
130+
- **Container Resources**: ECS task definitions and services for HTTP endpoint
131+
- **IAM Roles**: SageMaker execution roles with necessary permissions
132+
133+
**Key Features:**
134+
135+
- Provides ready-to-use test models for validating Model Runner functionality
136+
- Includes both SageMaker and HTTP-based endpoints for different integration patterns
137+
- Test imagery is automatically deployed for immediate use
138+
- Shares the same VPC as ModelRunnerStack for consistent networking
139+
140+
---
141+
142+
### SageMakerRoleStack (`<project-name>-SageMakerRole`)
143+
144+
The **SageMakerRoleStack** creates a dedicated IAM role for SageMaker endpoints. This is deployed separately to ensure proper cleanup of network interfaces when endpoints are deleted.
145+
146+
**Resources Created:**
147+
148+
- **IAM Role**: SageMaker execution role with permissions for:
149+
- Accessing S3 buckets
150+
- CloudWatch logging
151+
- VPC network access
152+
- Model artifact access
153+
154+
**Note**: This stack exists as a workaround for a CloudFormation limitation with SageMaker endpoint cleanup. It ensures network interfaces are properly cleaned up when endpoints are deleted.
155+
156+
---
157+
19158
## ⚙️ Configuration
20159

21160
### Deployment File: `bin/deployment/deployment.json`
@@ -213,37 +352,6 @@ This command will:
213352

214353
---
215354

216-
## 🧱 Project Structure
217-
218-
```text
219-
cdk
220-
├── bin/
221-
│ ├── app.ts # Entry point, loads config and launches stack
222-
│ └── deployment/
223-
│ ├── deployment.json # Your environment-specific config
224-
│ ├── deployment.json.example # Template for creating new configs
225-
│ └── load-deployment.ts # Configuration loader and validator
226-
├── lib/
227-
│ ├── model-runner-stack.ts # Root CDK stack
228-
│ ├── integration-test-stack.ts # Integration test resources CDK stack
229-
│ └── constructs/ # Modular construct classes
230-
│ ├── types.ts # Common types and interfaces
231-
│ ├── dataplane.ts # Main Dataplane construct
232-
│ ├── network.ts # Network - VPC and networking resources
233-
│ ├── database-tables.ts # DatabaseTables - DynamoDB tables
234-
│ ├── messaging.ts # Messaging - SQS queues and SNS topics
235-
│ ├── ecs-service.ts # ECSService - ECS cluster, services, and roles
236-
│ ├── ecs-roles.ts # ECSRoles - ECS task and execution roles
237-
│ ├── monitoring.ts # Monitoring - CloudWatch dashboards
238-
│ ├── autoscaling.ts # Autoscaling - ECS autoscaling policies
239-
│ └── sinks.ts # Sinks - S3 bucket and Kinesis stream outputs
240-
├── test/ # Unit tests and cdk-nag checks
241-
│ └── test-utils.ts # Test utilities and NAG report generation
242-
└── package.json # Project config and npm
243-
```
244-
245-
---
246-
247355
## 🏗️ Architecture
248356

249357
This CDK project uses a **modular construct architecture** that separates concerns into focused, reusable classes:

0 commit comments

Comments
 (0)