mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 08:03:16 +00:00
Adam Moussa
0c856bd107
2.253.1 bundles fast-uri 3.1.0 (two high-severity GHSAs, unfixable via overrides since it ships in the tarball). 2.257.0 bundles patched fast-uri 3.1.2 and passes npm ci (the 2.254.0 breakage that motivated the old pin was release-specific).
57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
# AWS Infrastructure
|
|
|
|
## IaC Strategy
|
|
|
|
- **SAM** is the default for new serverless stacks (Lambda + API Gateway + DynamoDB)
|
|
- **CDK** only for complex infrastructure (ECS, VPCs, multi-service compositions)
|
|
- Every deployed resource should be managed by CloudFormation
|
|
- No manually-created Lambdas, roles, or other resources outside of IaC
|
|
|
|
## Lambda Defaults
|
|
|
|
These apply to every Lambda in every project. Verify, don't assume.
|
|
|
|
| Setting | Value |
|
|
|---|---|
|
|
| Runtime | Python 3.12 or Node 24.x |
|
|
| Architecture | arm64 |
|
|
| Log retention | 60 days (explicit in IaC template) |
|
|
| Naming | kebab-case, matching the stack name prefix |
|
|
|
|
Never rely on the CloudWatch default for log retention. Always set `RetentionInDays` explicitly in the template.
|
|
|
|
## CDK Version Policy
|
|
|
|
Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.257.0**.
|
|
|
|
Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors, and bundled deps can carry vulnerabilities that npm `overrides` cannot fix (e.g., 2.253.1 bundled a high-severity-vulnerable fast-uri; the only remedy is moving to a release that bundles the patched version). When bumping the blessed version: test `npm ci` locally and confirm the new release's bundled deps clear dependency review.
|
|
|
|
When upgrading, verify on a branch first:
|
|
1. Update `package.json` to the new version
|
|
2. Run `rm -rf node_modules package-lock.json && npm install`
|
|
3. Run `npm ci` — if it fails, the version is not safe
|
|
4. Run `npx cdk synth` — if it fails, the version is not safe
|
|
|
|
## CloudFormation Outputs
|
|
|
|
Every stack should export:
|
|
|
|
- Function ARNs
|
|
- Any externally-consumable URLs (API Gateway endpoints, etc.)
|
|
|
|
## S3
|
|
|
|
- Every non-CloudFormation bucket must have `Purpose` and `ManagedBy` tags
|
|
- Define lifecycle policies in the IaC template
|
|
- Use Glacier Deep Archive for archival data
|
|
|
|
## README
|
|
|
|
Every repo must have a README that accurately describes:
|
|
|
|
- Project architecture
|
|
- Lambdas and services
|
|
- Data flow
|
|
- Configuration requirements
|
|
|
|
Update the README in the same commit where functionality changes. If a README is missing or outdated when you start working on a project, fix it as part of the current work.
|