feat(deploy-on-aws): enhance with CDK best practices, monitoring, and validation #35
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # CDK Best Practices | ||
|
Contributor
There was a problem hiding this comment. Q: does this conflict with the cdk_best_practices tool exposed by the IaC MCP server ? |
||
|
|
||
| Patterns for generating CDK IaC in the deploy workflow. | ||
|
|
||
| ## Resource Naming | ||
|
|
||
| **DO NOT** explicitly specify resource names. Let CDK generate unique names: | ||
|
|
||
| ```typescript | ||
| // ✅ Let CDK generate: StackName-MyFunctionXXXXXX | ||
| new lambda.Function(this, 'MyFunction', { /* no functionName */ }); | ||
| ``` | ||
|
|
||
| **Why**: Enables reusable patterns, parallel deployments, and stack isolation. | ||
|
|
||
| ## Lambda Constructs | ||
|
|
||
| Use language-specific constructs for automatic bundling: | ||
|
|
||
| - **TypeScript**: `NodejsFunction` from `aws-cdk-lib/aws-lambda-nodejs` | ||
| - **Python**: `PythonFunction` from `@aws-cdk/aws-lambda-python-alpha` | ||
|
|
||
| Benefits: Automatic dependency resolution, transpilation, and packaging. | ||
|
|
||
| ## IAM Permissions | ||
|
|
||
| Use grant methods instead of raw policies: | ||
|
|
||
| ```typescript | ||
| table.grantReadWriteData(handler); // ✅ | ||
| // NOT: handler.addToRolePolicy({ actions: ['dynamodb:*'], resources: ['*'] }) | ||
| ``` | ||
|
|
||
| ## Construct Levels | ||
|
|
||
| Prefer L3 (`LambdaRestApi`) > L2 (`Function`) > L1 (`CfnFunction`). | ||
|
|
||
| ## Validation | ||
|
|
||
| 1. Add **cdk-nag** for automated best-practice checks during synthesis | ||
| 2. Run `cdk synth` to validate | ||
| 3. Suppress findings with documented reasons via `NagSuppressions` | ||
|
|
||
| ## Testing | ||
|
|
||
| - **Snapshot tests**: `expect(template.toJSON()).toMatchSnapshot()` | ||
| - **Assertions**: `template.hasResourceProperties('AWS::Lambda::Function', { ... })` | ||
|
|
||
| ## Stack Organization | ||
|
|
||
| - Split at ~200 resources per stack | ||
| - Separate stateful (DB, S3) from stateless (compute) resources | ||
| - Export values via `CfnOutput` for cross-stack references | ||
|
|
||
| ## Anti-Patterns | ||
|
|
||
| | Anti-Pattern | Fix | | ||
| | ----------------------------- | --------------------------------------- | | ||
| | Hardcoded resource names | Let CDK generate names | | ||
| | `actions: ['*']` in IAM | Use grant methods | | ||
| | Manual Lambda bundling | Use `NodejsFunction` / `PythonFunction` | | ||
| | Missing environment variables | Pass via `environment` prop | | ||
| | No stack outputs | Add `CfnOutput` for API URLs, ARNs | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # Monitoring and Observability | ||
|
|
||
| Post-deployment monitoring patterns. Set up after successful deployment. | ||
|
|
||
| ## When to Add Monitoring | ||
|
|
||
| - **Always**: Error alerting for deployed compute (Fargate, Lambda) | ||
| - **Production**: Full observability (alarms + dashboards + logs) | ||
| - **Dev**: Basic error alerting only | ||
|
|
||
| ## Lambda Alarms | ||
|
|
||
| | Metric | Threshold | Periods | | ||
| | --------------- | -------------- | ------- | | ||
| | Errors (Sum) | 10 per 5 min | 1 | | ||
| | Duration (Max) | 80% of timeout | 2 | | ||
| | Throttles (Sum) | 5 per 5 min | 1 | | ||
|
|
||
| ## ECS/Fargate Alarms | ||
|
|
||
| | Metric | Threshold | Periods | | ||
| | ---------------------- | ------------- | ------- | | ||
| | CPU Utilization | 80% | 3 | | ||
| | Memory Utilization | 85% | 2 | | ||
| | Running Task Count < 1 | 1 (less-than) | 2 | | ||
|
|
||
| ## ALB Alarms | ||
|
|
||
| | Metric | Threshold | Periods | | ||
| | -------------------- | ------------ | ------- | | ||
| | 5XX Error Count | 10 per 5 min | 1 | | ||
| | Unhealthy Host Count | 1 | 2 | | ||
| | Response Time p99 | 1 second | 2 | | ||
|
|
||
| ## RDS/Aurora Alarms | ||
|
|
||
| | Metric | Threshold | Periods | | ||
| | -------------------- | ---------- | ------- | | ||
| | CPU Utilization | 80% | 3 | | ||
| | Free Storage Space | < 10 GB | 1 | | ||
| | Database Connections | 80% of max | 2 | | ||
|
|
||
| ## Alarm Notification | ||
|
|
||
| Use SNS topic with email subscription for alarm actions: | ||
|
|
||
| ```typescript | ||
| const topic = new sns.Topic(this, 'AlarmTopic'); | ||
| topic.addSubscription(new subscriptions.EmailSubscription('ops@example.com')); | ||
| alarm.addAlarmAction(new actions.SnsAction(topic)); | ||
| ``` | ||
|
|
||
| ## Threshold Guidelines | ||
|
|
||
| | Category | Warning | Critical | | ||
| | ----------- | ------------ | ----------- | | ||
| | CPU/Memory | 70-80% | 80-90% | | ||
| | Error rate | Based on SLA | 2× warning | | ||
| | Latency p99 | 80% of SLA | 100% of SLA | | ||
| | Storage | 70% used | 85% used | | ||
|
|
||
| ## Production Dashboard | ||
|
|
||
| Include these widget groups: | ||
|
|
||
| 1. **Service Overview**: Request rate, error %, latency (p50/p95/p99) | ||
| 2. **Resource Utilization**: CPU, memory, network by service | ||
| 3. **Cost Metrics**: Daily spend, month-to-date | ||
| 4. **Errors**: Error counts by type, recent logs |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Q: similar question, does this conflict with the tools exposed by the IaC mcp server ?