AGENTS.md

Instructions for coding agents working in this repository.

Infrastructure as Code principles

CDK + EC2: this repo deploys an EC2 instance via CDK TypeScript. No Lambda, no SAM.
Lambda defaults (does not apply) — this is a pure EC2 stack.
Exact-pin all CDK library versions (aws-cdk-lib, aws-cdk, constructs). Never use * or ^ ranges.
Never commit account IDs, role ARNs, VPC IDs, subnet IDs, or volume IDs in new code. The existing cdk.context.json already contains resolved values — do not add new deployment-specific identifiers without documented defaults.
Deploy with least-privilege IAM. The instance role already has only AmazonSSMManagedInstanceCore + Secrets Manager read on file-share/*.
Verify: npm run build && npx cdk synth && npx cdk diff before pushing. Do not commit cdk.out/.

CDK directory layout

.
├── bin/
│   └── app.ts              # CDK app entrypoint
├── lib/
│   └── file-share-stack.ts  # All resource definitions
├── cdk.json                  # CDK context + config
├── cdk.context.json          # Resolved context (committed)
├── package.json              # Exact-pinned CDK dependencies
├── tsconfig.json
└── .github/
    └── workflows/            # CI/CD

`overrideLogicalId` — never remove

Removing overrideLogicalId on a deployed resource forces replacement. Never remove an existing call without documenting the replacement impact.

Persistent EBS volumes

This repo's data volume (vol-04d951cccacc435b5) is imported by ID, not managed by CloudFormation. It survives instance replacement and stack deletion.

Snapshot before an EC2-replacing deploy

Before any deploy that would replace the EC2 instance (AMI change, user-data change, instance type change):

Run cdk diff to confirm the instance will be replaced.
Stop and ask for confirmation — an instance replacement detaches the imported volume. A snapshot is the safety net.
If a DLM snapshot already exists from the same day, reference it rather than creating a duplicate.

Security group rules

Never open 0.0.0.0/0. All rules use specific CIDR ranges (10.10.0.0/16 VPN, 10.20.0.0/16 VPC).
SSM Session Manager for instance access — no SSH key, no public port 22.

Secrets

Stored in AWS Secrets Manager (file-share/smb-password, file-share/filebrowser-password). The instance role reads them at boot. Do not embed secrets in UserData or source files.

Documentation

The Confluence "AWS Architecture Map" (page 1540098) should be updated alongside any architecture change.

2.6 KiB Raw Blame History