# AGENTS.md — EC2 + persistent EBS conventions

Supplement to `AGENTS.md.aws` (and `AGENTS.md.cdk` when using CDK). Merge into
the repo root `AGENTS.md` alongside the other templates.

## Persistent EBS volumes

EC2 instances managed through CDK or CloudFormation should treat EBS volumes
as durable, not disposable. The pattern is:

### Standalone `Volume` resource with `RETAIN`

```typescript
import * as ec2 from 'aws-cdk-lib/aws-ec2';

const dataVolume = new ec2.CfnVolume(this, 'DataVolume', {
  availabilityZone: instance.instanceAvailabilityZone,
  size: 100,
  volumeType: 'gp3',
});

dataVolume.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);
```

- Always create the EBS volume as a **separate `CfnVolume` resource**, not
  inline on the instance.
- Set the removal policy to `RETAIN` so the volume survives stack deletion.
- Attach the volume to the instance with a `CfnVolumeAttachment`.

### Snapshot before an EC2-replacing deploy

Before any deploy that would replace the EC2 instance (AMI change, user-data
change, instance type change), take a manual snapshot of the attached EBS
volume. The agent should:

1. Run `cdk diff` to confirm the instance will be replaced.
2. **Stop and ask for confirmation** before proceeding — an instance
   replacement with `RETAIN` volumes will detach the volume, but the snapshot
   is a safety net. Do not proceed unilaterally.
3. If a snapshot already exists from the same day, reference it rather than
   creating a duplicate.

## Security group rules

- Never open 0.0.0.0/0 on port 22 (SSH). Use a specific CIDR range or
  Systems Manager Session Manager.
- All security group rules must use the narrowest source (specific CIDR or
  security group reference).