Clean Up AMIs and Snapshots Older Than 30 Days

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "FindOldImagesAndSnapshots",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeImages",
        "ec2:DescribeSnapshots",
        "ec2:DescribeInstances",
        "ec2:DescribeLaunchTemplateVersions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "RemoveOldImagesAndSnapshots",
      "Effect": "Allow",
      "Action": [
        "ec2:DeregisterImage",
        "ec2:DeleteSnapshot"
      ],
      "Resource": [
        "arn:aws:ec2:*::image/*",
        "arn:aws:ec2:*::snapshot/*"
      ]
    }
  ]
}

// cleanup-old-amis-snapshots.ts
// Finds AMIs you own that are older than N days (default 30) and not used by any
// instance or launch template, plus EBS snapshots older than N days that no
// remaining AMI needs. Report-only by default; pass --apply to deregister and delete.
import {
  EC2Client,
  paginateDescribeImages,
  paginateDescribeInstances,
  paginateDescribeLaunchTemplateVersions,
  paginateDescribeSnapshots,
  DeregisterImageCommand,
  DeleteSnapshotCommand,
  type Image,
  type Tag,
} from "@aws-sdk/client-ec2";

const args = process.argv.slice(2);
const APPLY = args.includes("--apply");
const daysArg = args.indexOf("--days");
const DAYS = daysArg !== -1 ? Number(args[daysArg + 1]) : 30;
if (!Number.isFinite(DAYS) || DAYS < 1) throw new Error("--days must be a positive number");

const region = process.env.AWS_REGION ?? "us-east-1";
const ec2 = new EC2Client({ region });
const cutoff = new Date(Date.now() - DAYS * 24 * 60 * 60 * 1000);

const isKept = (tags: Tag[] | undefined) =>
  (tags ?? []).some((t) => t.Key?.toLowerCase() === "keep" && t.Value?.toLowerCase() === "true");
const isManaged = (tags: Tag[] | undefined) =>
  (tags ?? []).some((t) => t.Key?.startsWith("aws:dlm:") || t.Key?.startsWith("aws:backup:"));
const snapshotsOf = (image: Image) =>
  (image.BlockDeviceMappings ?? []).map((m) => m.Ebs?.SnapshotId).filter((id): id is string => !!id);

// AMI IDs referenced by instances in any state except terminated, and by launch templates.
async function amisInUse(): Promise<Set<string>> {
  const used = new Set<string>();
  const instanceFilter = [
    { Name: "instance-state-name", Values: ["pending", "running", "stopping", "stopped", "shutting-down"] },
  ];
  for await (const page of paginateDescribeInstances({ client: ec2 }, { Filters: instanceFilter })) {
    for (const r of page.Reservations ?? []) {
      for (const i of r.Instances ?? []) if (i.ImageId) used.add(i.ImageId);
    }
  }
  // Without a template ID, $Latest and $Default return those versions of every template.
  for await (const page of paginateDescribeLaunchTemplateVersions(
    { client: ec2 },
    { Versions: ["$Latest", "$Default"] },
  )) {
    for (const v of page.LaunchTemplateVersions ?? []) {
      const imageId = v.LaunchTemplateData?.ImageId;
      if (imageId) used.add(imageId);
    }
  }
  return used;
}

async function main(): Promise<void> {
  console.log(`${APPLY ? "APPLY" : "DRY RUN"} in ${region}: older than ${DAYS} days (${cutoff.toISOString()})`);
  const inUse = await amisInUse();

  const images: Image[] = [];
  // IncludeDisabled so snapshots behind disabled AMIs are protected (or cleaned up with them).
  for await (const page of paginateDescribeImages({ client: ec2 }, { Owners: ["self"], IncludeDisabled: true })) {
    images.push(...(page.Images ?? []));
  }

  // 1. Decide which AMIs go.
  const amisToRemove: Image[] = [];
  for (const image of images) {
    const created = image.CreationDate ? new Date(image.CreationDate) : undefined;
    if (!image.ImageId || !created || created >= cutoff) continue;
    let reason = "";
    if (inUse.has(image.ImageId)) reason = "used by an instance or launch template";
    else if (isKept(image.Tags)) reason = "tagged keep=true";
    else if (image.DeregistrationProtection?.startsWith("enabled")) reason = "deregistration protection";
    console.log(`AMI ${image.ImageId} ${image.Name ?? ""} (${image.CreationDate}): ${reason ? `skip, ${reason}` : "remove"}`);
    if (!reason) amisToRemove.push(image);
  }

  // 2. Snapshots still needed by any AMI that stays registered are off limits.
  const removing = new Set(amisToRemove.map((i) => i.ImageId));
  const protectedSnapshots = new Set(
    images.filter((i) => !removing.has(i.ImageId)).flatMap(snapshotsOf),
  );

  const snapshotsToDelete = new Set<string>();
  for await (const page of paginateDescribeSnapshots({ client: ec2 }, { OwnerIds: ["self"] })) {
    for (const s of page.Snapshots ?? []) {
      if (!s.SnapshotId || !s.StartTime || s.StartTime >= cutoff) continue;
      let reason = "";
      if (protectedSnapshots.has(s.SnapshotId)) reason = "backs a registered AMI";
      else if (isKept(s.Tags)) reason = "tagged keep=true";
      else if (isManaged(s.Tags)) reason = "managed by DLM or AWS Backup";
      console.log(`Snapshot ${s.SnapshotId} ${s.VolumeSize ?? "?"} GiB (${s.StartTime.toISOString()}): ${reason ? `skip, ${reason}` : "delete"}`);
      if (!reason) snapshotsToDelete.add(s.SnapshotId);
    }
  }

  console.log(`\nPlan: deregister ${amisToRemove.length} AMI(s), delete ${snapshotsToDelete.size} snapshot(s).`);
  if (!APPLY) {
    console.log("Dry run: nothing was changed. Re-run with --apply to act.");
    return;
  }

  // 3. Deregister first: a snapshot that backs a registered AMI can't be deleted.
  for (const image of amisToRemove) {
    try {
      await ec2.send(new DeregisterImageCommand({ ImageId: image.ImageId }));
      console.log(`Deregistered ${image.ImageId}`);
    } catch (err) {
      console.error(`Could not deregister ${image.ImageId}: ${(err as Error).message}`);
      for (const id of snapshotsOf(image)) snapshotsToDelete.delete(id); // still in use
    }
  }
  for (const id of snapshotsToDelete) {
    try {
      await ec2.send(new DeleteSnapshotCommand({ SnapshotId: id }));
      console.log(`Deleted ${id}`);
    } catch (err) {
      console.error(`Could not delete ${id}: ${(err as Error).message}`);
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-ec2
npm install --save-dev tsx typescript

# Dry run: report AMIs and snapshots older than 30 days (the default)
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx cleanup-old-amis-snapshots.ts

# Use a 90-day cutoff instead
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx cleanup-old-amis-snapshots.ts --days 90

# Act on the plan after reviewing it
AWS_PROFILE=admin AWS_REGION=us-east-1 npx tsx cleanup-old-amis-snapshots.ts --days 90 --apply

DRY RUN in us-east-1: older than 30 days (2026-08-28T09:14:02.511Z)
AMI ami-0a12b34c56d78e901 web-2026-06-02 (2026-06-02T03:10:44.000Z): remove
AMI ami-0b98c76d54e32f109 web-2026-07-01 (2026-07-01T03:11:02.000Z): skip, used by an instance or launch template
AMI ami-0c55d44e33f22a110 golden-base (2026-03-15T12:00:31.000Z): skip, tagged keep=true
Snapshot snap-01a2b3c4d5e6f7a8b 30 GiB (2026-06-02T03:10:47.000Z): delete
Snapshot snap-02b3c4d5e6f7a8b9c 30 GiB (2026-07-01T03:11:05.000Z): skip, backs a registered AMI
Snapshot snap-03c4d5e6f7a8b9c0d 100 GiB (2026-05-20T01:00:12.000Z): delete
Snapshot snap-04d5e6f7a8b9c0d1e 50 GiB (2026-08-01T05:00:00.000Z): skip, managed by DLM or AWS Backup

Plan: deregister 1 AMI(s), delete 2 snapshot(s).
Dry run: nothing was changed. Re-run with --apply to act.