adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 09:13:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
engineering-handbook/aws-infrastructure.md

5.4 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)
  • 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

HCP Terraform VCS file triggers

New prod/dev HCP workspaces follow the first-apply runbook in seahaven-org-baseline. When the workspace is created, set VCS file triggers before the first merge to the tracked branch.

  • Keep file-triggers-enabled. Do not turn file triggers off so that docs-only commits skip prod applies.
  • trigger-prefixes are added to the working directory. trigger-patterns replace the working-directory filter and must include a glob for that directory.
  • If the plan reads files outside the working directory (Lambda source, layers, requirements.txt, build scripts that copy src/, functions/, lambda/, or lambdas/), list those paths in trigger-prefixes or trigger-patterns. An empty pair with working-directory=terraform queues runs only for terraform/ changes, so a source-only merge is ingested and then silently skipped.
  • Record the live prefixes or patterns in the app README next to the workspace name.
  • python3 scripts/check_hcp_workspace_triggers.py in seahaven-org-baseline lists file-triggered workspaces in seahaven-mgmt, seahaven-prod, and seahaven-dev and flags an empty prefix/pattern pair when the repo working directory references those source trees.

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 and cdk-project-layout.md 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.