Find and Tag Unattached EBS Volumes to Cut Costs

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListVolumes",
      "Effect": "Allow",
      "Action": "ec2:DescribeVolumes",
      "Resource": "*"
    },
    {
      "Sid": "TagVolumesForReviewOnly",
      "Effect": "Allow",
      "Action": "ec2:CreateTags",
      "Resource": "arn:aws:ec2:*:123456789012:volume/*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "aws:TagKeys": ["cost-review:unattached-first-seen"]
        }
      }
    }
  ]
}

// tag-unattached-ebs.ts
// Lists EBS volumes in the "available" state (not attached to any instance),
// estimates their monthly storage cost and, with --tag, tags them for review.
// Report-only by default. It never detaches, snapshots or deletes anything.
// Usage: npx tsx tag-unattached-ebs.ts [--tag]
import {
  EC2Client,
  paginateDescribeVolumes,
  CreateTagsCommand,
  type Volume,
} from "@aws-sdk/client-ec2";

const TAG_KEY = "cost-review:unattached-first-seen";

// USD per GB-month for storage only, us-east-1, as of September 2026.
// Provisioned IOPS/throughput are billed on top and not included. Other regions differ.
const PRICE_PER_GB_MONTH: Record<string, number> = {
  gp3: 0.08,
  gp2: 0.1,
  io1: 0.125,
  st1: 0.045,
  sc1: 0.015,
  standard: 0.05,
};

const today = new Date().toISOString().slice(0, 10);
const tagValue = (v: Volume, key: string) => v.Tags?.find((t) => t.Key === key)?.Value;

function daysSince(isoDate: string | undefined): number | undefined {
  if (!isoDate) return undefined;
  const ms = Date.now() - new Date(`${isoDate}T00:00:00Z`).getTime();
  return Number.isNaN(ms) ? undefined : Math.floor(ms / 86_400_000);
}

async function main(): Promise<void> {
  const applyTags = process.argv.includes("--tag");
  const ec2 = new EC2Client({}); // region from AWS_REGION or your AWS profile

  const volumes: Volume[] = [];
  for await (const page of paginateDescribeVolumes(
    { client: ec2 },
    { Filters: [{ Name: "status", Values: ["available"] }] },
  )) {
    volumes.push(...(page.Volumes ?? []));
  }
  if (volumes.length === 0) {
    console.log("No unattached EBS volumes in this region.");
    return;
  }

  const rows = volumes
    .map((v) => {
      const type = v.VolumeType ?? "unknown";
      const price = PRICE_PER_GB_MONTH[type];
      const firstSeen = tagValue(v, TAG_KEY);
      return {
        id: v.VolumeId ?? "",
        name: tagValue(v, "Name") ?? "",
        type,
        sizeGiB: v.Size ?? 0,
        zone: v.AvailabilityZone ?? "",
        created: v.CreateTime?.toISOString().slice(0, 10) ?? "",
        firstSeen,
        monthly: price === undefined ? undefined : (v.Size ?? 0) * price,
      };
    })
    .sort((a, b) => (b.monthly ?? 0) - (a.monthly ?? 0));

  console.table(
    rows.map((r) => ({
      Volume: r.id,
      Name: r.name,
      Type: r.type,
      "Size GiB": r.sizeGiB,
      Zone: r.zone,
      Created: r.created,
      "Unattached (days seen)": r.firstSeen ? daysSince(r.firstSeen) ?? "?" : "new",
      "Est. $/month": r.monthly === undefined ? "n/a" : r.monthly.toFixed(2),
    })),
  );
  const total = rows.reduce((s, r) => s + (r.monthly ?? 0), 0);
  const totalGiB = rows.reduce((s, r) => s + r.sizeGiB, 0);
  console.log(`${rows.length} unattached volumes, ${totalGiB} GiB, about $${total.toFixed(2)}/month in storage`);

  const untagged = rows.filter((r) => !r.firstSeen).map((r) => r.id);
  if (!applyTags) {
    console.log(`Report only. ${untagged.length} volumes would get ${TAG_KEY}=${today}. Re-run with --tag to apply.`);
    return;
  }

  // Tag only volumes without the tag, so the first-seen date survives later runs.
  for (let i = 0; i < untagged.length; i += 50) {
    const batch = untagged.slice(i, i + 50);
    await ec2.send(new CreateTagsCommand({ Resources: batch, Tags: [{ Key: TAG_KEY, Value: today }] }));
    console.log(`Tagged ${batch.join(", ")}`);
  }
  console.log(`Done. ${untagged.length} volumes tagged; ${rows.length - untagged.length} already had the tag.`);
}

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

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

# 1. Report only (default): nothing is changed
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx tag-unattached-ebs.ts

# 2. Tag volumes that don't have the review tag yet
AWS_PROFILE=ops AWS_REGION=us-east-1 npx tsx tag-unattached-ebs.ts --tag

┌─────────┬─────────────────────────┬────────────────┬───────┬──────────┬──────────────┬──────────────┬────────────────────────┬──────────────┐
│ (index) │ Volume                  │ Name           │ Type  │ Size GiB │ Zone         │ Created      │ Unattached (days seen) │ Est. $/month │
├─────────┼─────────────────────────┼────────────────┼───────┼──────────┼──────────────┼──────────────┼────────────────────────┼──────────────┤
│ 0       │ 'vol-0a1b2c3d4e5f60718' │ 'old-db-data'  │ 'gp2' │ 500      │ 'us-east-1a' │ '2025-11-03' │ 34                     │ '50.00'      │
│ 1       │ 'vol-0123456789abcdef0' │ ''             │ 'gp3' │ 200      │ 'us-east-1b' │ '2026-08-14' │ 'new'                  │ '16.00'      │
│ 2       │ 'vol-0fedcba9876543210' │ 'backup-cold'  │ 'sc1' │ 1000     │ 'us-east-1a' │ '2026-02-20' │ 12                     │ '15.00'      │
│ 3       │ 'vol-0b2c3d4e5f6071829' │ 'perf-test'    │ 'io2' │ 100      │ 'us-east-1c' │ '2026-09-02' │ 'new'                  │ 'n/a'        │
└─────────┴─────────────────────────┴────────────────┴───────┴──────────┴──────────────┴──────────────┴────────────────────────┴──────────────┘
4 unattached volumes, 1800 GiB, about $81.00/month in storage
Report only. 2 volumes would get cost-review:unattached-first-seen=2026-09-27. Re-run with --tag to apply.