mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 08:03:16 +00:00
a34f9c9e8a
Some checks are pending
ci / ci / ci (push) Waiting to run
Point migrating stacks at the org-baseline checklist; leave SAM/CDK defaults for greenfield serverless.
71 lines
4.2 KiB
Markdown
71 lines
4.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)
|
|
- **Migrating stacks** from mgmt into seahaven-prod / seahaven-dev use **HCP Terraform** (migrate-and-convert; do not convert in place in mgmt). The authoritative per-stack steps live in the `seahaven-org-baseline` README migration checklist (plan/apply role patterns, boundary widen, artifact packaging, cutover). Reference implementation: `afi-backup-monitor` (PLAT-56).
|
|
- Every deployed resource should be managed by IaC (CloudFormation via SAM/CDK, or HCP Terraform state for migrated stacks)
|
|
- 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 (`nodejs24.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.
|
|
|
|
### Node runtime
|
|
|
|
This is the canonical statement; [dev-environment.md](dev-environment.md#nodejs) and [cdk-project-layout.md](cdk-project-layout.md#lambda-defaults) defer to it.
|
|
|
|
- **`nodejs24.x` is the standard.** Every new Node Lambda targets it, set explicitly in the IaC template.
|
|
- **`nodejs22.x` is legacy only.** It is valid for functions that already run on it, and those move to 24.x before the AWS deprecation date of 2027-04-30. Do not start a new function on it.
|
|
- **Never target `nodejs26.x`,** including once AWS ships it. Lambda applies runtime updates automatically, so a fresh major is only adopted after it has been generally available on Lambda for a full quarter, and only by a deliberate change to this page. Odd majors (25.x, 27.x) never become Lambda runtimes at all.
|
|
|
|
## CDK Version Policy
|
|
|
|
Pin `aws-cdk-lib` to an exact version (no `^`, `~`, or `>=`) and let Dependabot keep it current. There is no static "blessed version" — the org standard is the latest release that passes the gates below. Do not add blanket `dependabot.yml` ignore entries for `aws-cdk-lib`; that is how pins rot into carrying known vulnerabilities.
|
|
|
|
Why exact + automated: the exact pin plus the lockfile gives reproducible builds; weekly Dependabot version updates keep the pin moving; CI (`npm ci` + `cdk synth`) and the dependency-review check reject a bad release at the PR. A release with broken bundled-dep metadata (e.g. 2.254.0) fails `npm ci` on its own bump PR; a release bundling a vulnerable transitive dep fails dependency review. Either way, a bad release never merges — the gates do the vetting, not a frozen number in this document.
|
|
|
|
aws-cdk-lib bundles transitive dependencies (`inBundle: true`) that npm `overrides` cannot patch. When a bundled dep has a vulnerability, the only fix is advancing to a release that bundles the patched version — treat the alert as a prompt to merge the next Dependabot bump, never as something to dismiss indefinitely.
|
|
|
|
If a specific release is known-bad, ignore that version only (`ignore: - dependency-name: aws-cdk-lib, versions: ["2.254.0"]`) with a comment explaining why, and remove the entry once a fixed release ships.
|
|
|
|
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.
|