Convert EBS gp2 Volumes to gp3 With AWS SDK v3

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PlanAndTrack",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVolumes",
        "ec2:DescribeVolumesModifications"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ConvertVolumes",
      "Effect": "Allow",
      "Action": "ec2:ModifyVolume",
      "Resource": "arn:aws:ec2:*:123456789012:volume/*"
    }
  ]
}

// convert-gp2-to-gp3.ts
// Plans (default) or applies (--apply) a gp2 -> gp3 change for EBS volumes in one region,
// keeping IOPS and throughput at or above what each gp2 volume delivers today.
// Usage: npx tsx convert-gp2-to-gp3.ts [--apply] [--max 5] [--volume vol-123] | --status
import {
  EC2Client,
  ModifyVolumeCommand,
  paginateDescribeVolumes,
  paginateDescribeVolumesModifications,
  type Filter,
  type Volume,
} from "@aws-sdk/client-ec2";

// USD, us-east-1, as of September 2026. Other regions differ.
const GP2_PER_GB = 0.1;
const GP3_PER_GB = 0.08;
const GP3_PER_IOPS = 0.005; // per provisioned IOPS-month above 3,000
const GP3_PER_MIBPS = 0.04; // per provisioned MiB/s-month above 125
const GP3_BASE_IOPS = 3000;
const GP3_BASE_MIBPS = 125;

const ec2 = new EC2Client({}); // region from AWS_REGION or your profile

function arg(name: string): string | undefined {
  const i = process.argv.indexOf(name);
  return i === -1 ? undefined : process.argv[i + 1];
}

// What a gp2 volume delivers: 3 IOPS per GiB (min 100, max 16,000);
// 128 MiB/s up to 170 GiB, up to 250 MiB/s above that.
function gp2Performance(sizeGiB: number) {
  const iops = Math.min(16_000, Math.max(100, sizeGiB * 3));
  const mibps = sizeGiB <= 170 ? 128 : 250;
  return { iops, mibps };
}

function plan(v: Volume) {
  const size = v.Size ?? 0;
  const gp2 = gp2Performance(size);
  const iops = Math.max(GP3_BASE_IOPS, gp2.iops);
  const mibps = Math.max(GP3_BASE_MIBPS, gp2.mibps);
  const gp2Cost = size * GP2_PER_GB;
  const gp3Cost = size * GP3_PER_GB + (iops - GP3_BASE_IOPS) * GP3_PER_IOPS + (mibps - GP3_BASE_MIBPS) * GP3_PER_MIBPS;
  return { id: v.VolumeId ?? "", size, state: v.State ?? "", gp2, iops, mibps, gp2Cost, gp3Cost };
}

async function showStatus(): Promise<void> {
  const filters: Filter[] = [{ Name: "original-volume-type", Values: ["gp2"] }];
  const rows = [];
  for await (const page of paginateDescribeVolumesModifications({ client: ec2 }, { Filters: filters })) {
    for (const m of page.VolumesModifications ?? []) {
      if (m.TargetVolumeType !== "gp3") continue;
      rows.push({
        Volume: m.VolumeId,
        State: m.ModificationState,
        "Progress %": m.Progress,
        IOPS: m.TargetIops,
        "MiB/s": m.TargetThroughput,
        Started: m.StartTime?.toISOString().slice(0, 16),
      });
    }
  }
  if (rows.length === 0) console.log("No gp2 -> gp3 modifications found.");
  else console.table(rows);
}

async function main(): Promise<void> {
  if (process.argv.includes("--status")) return showStatus();
  const apply = process.argv.includes("--apply");
  const max = Number(arg("--max") ?? 5);
  const only = arg("--volume");

  const filters: Filter[] = [{ Name: "volume-type", Values: ["gp2"] }];
  if (only) filters.push({ Name: "volume-id", Values: [only] });
  const volumes: Volume[] = [];
  for await (const page of paginateDescribeVolumes({ client: ec2 }, { Filters: filters })) {
    volumes.push(...(page.Volumes ?? []));
  }
  if (volumes.length === 0) {
    console.log("No gp2 volumes in this region.");
    return;
  }

  const plans = volumes.map(plan).sort((a, b) => b.gp2Cost - b.gp3Cost - (a.gp2Cost - a.gp3Cost));
  console.table(
    plans.map((p) => ({
      Volume: p.id,
      "Size GiB": p.size,
      State: p.state,
      "gp2 IOPS": p.gp2.iops,
      "gp3 IOPS": p.iops,
      "gp3 MiB/s": p.mibps,
      "gp2 $/mo": p.gp2Cost.toFixed(2),
      "gp3 $/mo": p.gp3Cost.toFixed(2),
      "Saves $/mo": (p.gp2Cost - p.gp3Cost).toFixed(2),
    })),
  );
  const saving = plans.reduce((s, p) => s + p.gp2Cost - p.gp3Cost, 0);
  console.log(`${plans.length} gp2 volumes; converting all saves about $${saving.toFixed(2)}/month.`);

  if (!apply) {
    console.log(`Dry run. Re-run with --apply to convert up to ${max} volumes (use --max to change).`);
    return;
  }

  // Tiny volumes can cost more as gp3 (matching 128 MiB/s is billed above 125), so skip those.
  for (const p of plans.filter((x) => x.gp3Cost < x.gp2Cost).slice(0, max)) {
    try {
      const res = await ec2.send(
        new ModifyVolumeCommand({
          VolumeId: p.id,
          VolumeType: "gp3",
          // Only send values above the gp3 baseline; the baseline is included in the price.
          Iops: p.iops > GP3_BASE_IOPS ? p.iops : undefined,
          Throughput: p.mibps > GP3_BASE_MIBPS ? p.mibps : undefined,
        }),
      );
      console.log(`${p.id}: ${res.VolumeModification?.ModificationState ?? "requested"}`);
    } catch (err) {
      // e.g. IncorrectModificationState when a previous modification hasn't completed
      console.error(`${p.id}: ${(err as Error).name}: ${(err as Error).message}`);
    }
  }
  console.log("Track progress with --status. Volumes stay usable while they change.");
}

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

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

# 1. Dry run: plan and price every gp2 volume
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx convert-gp2-to-gp3.ts

# 2. Convert one volume first, then check it
AWS_PROFILE=ops AWS_REGION=us-east-1 npx tsx convert-gp2-to-gp3.ts --apply --volume vol-0a1b2c3d4e5f60718
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx convert-gp2-to-gp3.ts --status

# 3. Convert the next 10 biggest savings
AWS_PROFILE=ops AWS_REGION=us-east-1 npx tsx convert-gp2-to-gp3.ts --apply --max 10

┌─────────┬─────────────────────────┬──────────┬───────────┬──────────┬──────────┬───────────┬──────────┬──────────┬────────────┐
│ (index) │ Volume                  │ Size GiB │ State     │ gp2 IOPS │ gp3 IOPS │ gp3 MiB/s │ gp2 $/mo │ gp3 $/mo │ Saves $/mo │
├─────────┼─────────────────────────┼──────────┼───────────┼──────────┼──────────┼───────────┼──────────┼──────────┼────────────┤
│ 0       │ 'vol-0fedcba9876543210' │ 2000     │ 'in-use'  │ 6000     │ 6000     │ 250       │ '200.00' │ '180.00' │ '20.00'    │
│ 1       │ 'vol-0123456789abcdef0' │ 1000     │ 'in-use'  │ 3000     │ 3000     │ 250       │ '100.00' │ '85.00'  │ '15.00'    │
│ 2       │ 'vol-0a1b2c3d4e5f60718' │ 500      │ 'in-use'  │ 1500     │ 3000     │ 250       │ '50.00'  │ '45.00'  │ '5.00'     │
│ 3       │ 'vol-0b2c3d4e5f6071829' │ 100      │ 'in-use'  │ 300      │ 3000     │ 128       │ '10.00'  │ '8.12'   │ '1.88'     │
│ 4       │ 'vol-0c3d4e5f607182930' │ 8        │ 'in-use'  │ 100      │ 3000     │ 128       │ '0.80'   │ '0.76'   │ '0.04'     │
└─────────┴─────────────────────────┴──────────┴───────────┴──────────┴──────────┴───────────┴──────────┴──────────┴────────────┘
5 gp2 volumes; converting all saves about $41.92/month.
Dry run. Re-run with --apply to convert up to 5 volumes (use --max to change).