Find Overprovisioned EBS IOPS on io1 and io2 Volumes

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadVolumesAndMetrics",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVolumes",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    }
  ]
}

// find-overprovisioned-ebs-iops.ts
// Finds io1 and io2 volumes whose provisioned IOPS sit far above what the workload used.
// For each volume it reads 14 days of 1-minute CloudWatch data, takes the busiest minute
// (read + write ops, and consumed ops normalized to 256 KiB), adds headroom, and prices
// the provisioned IOPS you could drop, or a move to gp3. Report only: nothing is modified.
// Usage:
//   npx tsx find-overprovisioned-ebs-iops.ts [--regions us-east-1,eu-west-1] [--days 14] [--headroom 0.3] [--csv iops.csv]
import { writeFileSync } from "node:fs";
import { CloudWatchClient, paginateGetMetricData, type MetricDataQuery } from "@aws-sdk/client-cloudwatch";
import { EC2Client, paginateDescribeVolumes, type Volume } from "@aws-sdk/client-ec2";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const regions = (flag("--regions") ?? process.env.AWS_REGION ?? "us-east-1").split(",").map((r) => r.trim()).filter(Boolean);
const days = Math.min(Number(flag("--days") ?? "14"), 15); // 1-minute datapoints are kept for 15 days
const headroom = Number(flag("--headroom") ?? "0.3");
const csvPath = flag("--csv");

// us-east-1 list prices per month, checked September 2026 (aws.amazon.com/ebs/pricing/). Edit for other Regions.
const PRICE = {
  pioGb: 0.125, // io1 and io2, per GB-month
  io1Iops: 0.065, // per provisioned IOPS-month
  io2Tiers: [
    { upTo: 32_000, rate: 0.065 },
    { upTo: 64_000, rate: 0.046 },
  ],
  gp3Gb: 0.08,
  gp3Iops: 0.005, // per IOPS-month above the included 3,000
  gp3Mibps: 0.06, // per MiB/s-month above the included 125
};
const GP3_MAX_IOPS = 80_000;
const GP3_MAX_MIBPS = 2_000;

/** Monthly IOPS charge, or undefined when io2 goes past the tiers priced above. */
function iopsCost(type: string, iops: number): number | undefined {
  if (type === "io1") return iops * PRICE.io1Iops;
  let cost = 0;
  let from = 0;
  for (const tier of PRICE.io2Tiers) {
    cost += Math.max(0, Math.min(iops, tier.upTo) - from) * tier.rate;
    from = tier.upTo;
  }
  return iops > from ? undefined : cost;
}

interface Row {
  Region: string;
  Volume: string;
  Type: string;
  GiB: number;
  Provisioned: number;
  PeakIops: number;
  PeakMiBps: number;
  Suggested: number;
  IopsSaving: string; // $ per month from lowering provisioned IOPS on the same type
  Gp3Saving: string; // $ per month from moving to gp3 at the suggested IOPS and throughput
  Note: string;
}

const money = (n: number | undefined) => (n === undefined ? "n/a" : `$${n.toFixed(2)}`);

async function peakUsage(cw: CloudWatchClient, volumeId: string, start: Date, end: Date) {
  const metric = (id: string, name: string): MetricDataQuery => ({
    Id: id,
    MetricStat: { Metric: { Namespace: "AWS/EBS", MetricName: name, Dimensions: [{ Name: "VolumeId", Value: volumeId }] }, Period: 60, Stat: "Sum" },
    ReturnData: false,
  });
  const queries: MetricDataQuery[] = [
    metric("r", "VolumeReadOps"),
    metric("w", "VolumeWriteOps"),
    metric("c", "VolumeConsumedReadWriteOps"),
    metric("rb", "VolumeReadBytes"),
    metric("wb", "VolumeWriteBytes"),
    { Id: "ops", Expression: "(FILL(r,0) + FILL(w,0)) / 60", ReturnData: true }, // IOPS per minute
    { Id: "consumed", Expression: "FILL(c,0) / 60", ReturnData: true }, // 256 KiB-normalized IOPS
    { Id: "mibps", Expression: "(FILL(rb,0) + FILL(wb,0)) / 60 / 1048576", ReturnData: true },
  ];
  const peak = { ops: 0, consumed: 0, mibps: 0, points: 0 };
  for await (const page of paginateGetMetricData({ client: cw }, { StartTime: start, EndTime: end, MetricDataQueries: queries })) {
    for (const r of page.MetricDataResults ?? []) {
      const values = r.Values ?? [];
      const max = values.reduce((m, v) => Math.max(m, v), 0);
      if (r.Id === "ops") {
        peak.ops = Math.max(peak.ops, max);
        peak.points += values.length;
      } else if (r.Id === "consumed") peak.consumed = Math.max(peak.consumed, max);
      else if (r.Id === "mibps") peak.mibps = Math.max(peak.mibps, max);
    }
  }
  return peak;
}

async function scanRegion(region: string): Promise<Row[]> {
  const ec2 = new EC2Client({ region });
  const cw = new CloudWatchClient({ region });
  const end = new Date(Math.floor(Date.now() / 60_000) * 60_000);
  const start = new Date(end.getTime() - days * 86_400_000);

  const volumes: Volume[] = [];
  for await (const page of paginateDescribeVolumes({ client: ec2 }, { Filters: [{ Name: "volume-type", Values: ["io1", "io2"] }] })) {
    volumes.push(...(page.Volumes ?? []));
  }

  const rows: Row[] = [];
  for (const v of volumes) {
    const type = v.VolumeType ?? "";
    const gib = v.Size ?? 0;
    const provisioned = v.Iops ?? 0;
    const row: Row = {
      Region: region, Volume: v.VolumeId ?? "", Type: type, GiB: gib, Provisioned: provisioned,
      PeakIops: 0, PeakMiBps: 0, Suggested: provisioned, IopsSaving: "", Gp3Saving: "", Note: "",
    };
    rows.push(row);
    if (v.State !== "in-use") {
      row.Note = `${v.State}: no metrics while detached; see the unattached-volume check`;
      continue;
    }
    if (v.MultiAttachEnabled) row.Note = "Multi-Attach: check per-instance load before changing";

    const peak = await peakUsage(cw, row.Volume, start, end);
    if (peak.points < days * 1440 * 0.5) row.Note ||= `only ${peak.points} minutes of data: attached recently?`;
    row.PeakIops = Math.ceil(Math.max(peak.ops, peak.consumed));
    row.PeakMiBps = Math.round(peak.mibps * 10) / 10;
    row.Suggested = Math.max(100, Math.ceil((row.PeakIops * (1 + headroom)) / 100) * 100);
    if (row.Suggested >= provisioned) {
      row.Suggested = provisioned;
      row.IopsSaving = "$0.00";
    } else {
      const now = iopsCost(type, provisioned);
      const after = iopsCost(type, row.Suggested);
      row.IopsSaving = money(now === undefined || after === undefined ? undefined : now - after);
    }

    // gp3 alternative: storage + IOPS above 3,000 + throughput above 125 MiB/s, against today's io1/io2 bill.
    const gp3Iops = Math.max(3000, row.Suggested);
    const gp3Mibps = Math.max(125, Math.ceil(row.PeakMiBps * (1 + headroom)));
    const current = iopsCost(type, provisioned);
    if (gp3Iops <= GP3_MAX_IOPS && gp3Mibps <= GP3_MAX_MIBPS && current !== undefined) {
      const gp3 = gib * PRICE.gp3Gb + (gp3Iops - 3000) * PRICE.gp3Iops + (gp3Mibps - 125) * PRICE.gp3Mibps;
      row.Gp3Saving = money(gib * PRICE.pioGb + current - gp3);
    } else {
      row.Gp3Saving = "n/a";
    }
  }
  return rows;
}

function toCsv(rows: Row[]): string {
  const cols = Object.keys(rows[0] ?? {}) as (keyof Row)[];
  const cell = (v: string | number) => `"${String(v).replace(/"/g, '""')}"`;
  return [cols.join(","), ...rows.map((r) => cols.map((c) => cell(r[c])).join(","))].join("\n") + "\n";
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  for (const region of regions) rows.push(...(await scanRegion(region)));
  rows.sort((a, b) => Number(b.IopsSaving.replace(/[^0-9.]/g, "")) - Number(a.IopsSaving.replace(/[^0-9.]/g, "")));
  console.table(rows);

  const total = rows.reduce((n, r) => n + (Number(r.IopsSaving.replace(/[^0-9.]/g, "")) || 0), 0);
  const over = rows.filter((r) => r.Suggested < r.Provisioned).length;
  console.log(`${rows.length} io1/io2 volumes, ${over} provisioned above peak + ${headroom * 100}% headroom`);
  console.log(`Lowering their IOPS would save about $${total.toFixed(2)} a month (us-east-1 list prices, before gp3)`);
  if (csvPath) {
    writeFileSync(csvPath, toCsv(rows));
    console.log(`Wrote ${rows.length} rows to ${csvPath}`);
  }
  console.log("Report only: no volume was modified.");
}

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

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

# Two Regions, default 30% headroom, with a CSV for the database owners
AWS_PROFILE=readonly npx tsx find-overprovisioned-ebs-iops.ts --regions us-east-1,eu-west-1 --csv io-volumes.csv

# Spiky workload: keep 60% headroom
AWS_PROFILE=readonly npx tsx find-overprovisioned-ebs-iops.ts --headroom 0.6

┌─────────┬─────────────┬─────────────────────────┬───────┬──────┬─────────────┬──────────┬───────────┬───────────┬────────────┬────────────┬──────────────────────────────────────────────────────────────┐
│ (index) │ Region      │ Volume                  │ Type  │ GiB  │ Provisioned │ PeakIops │ PeakMiBps │ Suggested │ IopsSaving │ Gp3Saving  │ Note                                                         │
├─────────┼─────────────┼─────────────────────────┼───────┼──────┼─────────────┼──────────┼───────────┼───────────┼────────────┼────────────┼──────────────────────────────────────────────────────────────┤
│ 0       │ 'us-east-1' │ 'vol-0a1b2c3d4e5f60718' │ 'io1' │ 500  │ 20000       │ 4100     │ 180.2     │ 5400      │ '$949.00'  │ '$1303.90' │ ''                                                           │
│ 1       │ 'us-east-1' │ 'vol-0b2c3d4e5f6071829' │ 'io2' │ 2000 │ 40000       │ 21800    │ 610.4     │ 28400     │ '$602.00'  │ '$2370.86' │ ''                                                           │
│ 2       │ 'us-east-1' │ 'vol-0c3d4e5f607182930' │ 'io1' │ 100  │ 3000        │ 2650     │ 48.3      │ 3000      │ '$0.00'    │ '$199.50'  │ ''                                                           │
│ 3       │ 'eu-west-1' │ 'vol-0d4e5f60718293a41' │ 'io2' │ 64   │ 3200        │ 0        │ 0         │ 3200      │ ''         │ ''         │ 'available: no metrics while detached; see the unattached-volume check' │
└─────────┴─────────────┴─────────────────────────┴───────┴──────┴─────────────┴──────────┴───────────┴───────────┴────────────┴────────────┴──────────────────────────────────────────────────────────────┘
4 io1/io2 volumes, 2 provisioned above peak + 30% headroom
Lowering their IOPS would save about $1551.00 a month (us-east-1 list prices, before gp3)
Report only: no volume was modified.