adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 06:53:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
engineering-handbook/aws-infrastructure.md
Adam Moussa 0c856bd107 docs: move blessed aws-cdk-lib pin to 2.257.0 
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).
2026-06-05 12:52:38 -04:00

2.2 KiB
Raw Blame History

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.