mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 11:33:13 +00:00
4b5d39fb91
* Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD - Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure - Update Lambda runtime default from Node 22 to Node 24 - Rewrite CI/CD page to reflect GitHub Actions reusable workflows (was still referencing CodePipeline/CodeBuild) * Add pre-push hook for npm ci validation Catches lock file drift locally before it breaks CI. Includes install instructions in git-workflow.md. * Add repo provisioning script Automates the new-repo checklist: GitHub repo creation, OIDC deploy role, repo secret, security features, CI/CD workflow stubs, and pre-push hook installation. Supports both SAM and CDK stack types. * Add shared VpnEc2Instance CDK construct Reference construct for the VPN-accessible EC2 pattern used by file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role, encrypted EBS, and DLM snapshots. Copy into lib/constructs/. * Add post-deploy health check template Template script for project-specific health checks. Copy to scripts/health-check.sh — CD workflows run it automatically.
57 lines
2 KiB
Markdown
57 lines
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.253.1**.
|
|
|
|
Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors. npm `overrides` cannot fix bundled deps. Always test `npm ci` locally before pushing a version bump.
|
|
|
|
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.
|