Find Idle EC2 Dedicated Hosts

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadHostsAndPrices",
      "Effect": "Allow",
      "Action": ["ec2:DescribeHosts", "pricing:GetProducts"],
      "Resource": "*"
    },
    {
      "Sid": "ReleaseOnlyWithApply",
      "Effect": "Allow",
      "Action": "ec2:ReleaseHosts",
      "Resource": "arn:aws:ec2:*:123456789012:dedicated-host/*"
    }
  ]
}

// find-idle-ec2-dedicated-hosts.ts
// Reports EC2 Dedicated Host utilization: vCPUs in use, instance count and the On-Demand hourly rate
// (from the AWS Price List API) for every allocated host, and flags empty and under-used hosts.
// Report only by default. --apply --release h-1,h-2 releases only the named hosts, and only when they
// are empty, On-Demand (no Host Reservation), not in a License Manager host resource group and, for Mac
// hosts, allocated more than 24 hours ago.
// Usage: npx tsx find-idle-ec2-dedicated-hosts.ts [--regions us-east-1,eu-west-1] [--low 50]
//        [--release h-0123456789abcdef0 --apply]
import { EC2Client, ReleaseHostsCommand, paginateDescribeHosts, type Host } from "@aws-sdk/client-ec2";
import { PricingClient, GetProductsCommand } from "@aws-sdk/client-pricing";

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 list = (v: string | undefined): string[] => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
const regions = list(flag("--regions") ?? process.env.AWS_REGION ?? "us-east-1");
const lowPercent = Number(flag("--low") ?? 50);
const toRelease = new Set(list(flag("--release")));
const apply = args.includes("--apply");
const HOURS_PER_MONTH = 730;

interface Row {
  Region: string;
  Host: string;
  Name: string;
  Family: string;
  AZ: string;
  Instances: number;
  VCpusUsed: string;
  Utilization: number;
  Status: string;
  Billing: string;
  PerMonth: number | null;
  host: Host;
}

const errorText = (err: unknown): string => (err instanceof Error ? `${err.name}: ${err.message}` : String(err));

// ---- Price List API: On-Demand hourly rate for a Dedicated Host of one instance family ----
const pricing = new PricingClient({ region: "us-east-1" });
const priceCache = new Map<string, number | null>();

async function hostHourlyRate(region: string, family: string): Promise<number | null> {
  const key = `${region}|${family}`;
  if (priceCache.has(key)) return priceCache.get(key) ?? null;
  let rate: number | null = null;
  try {
    const out = await pricing.send(new GetProductsCommand({
      ServiceCode: "AmazonEC2",
      Filters: [
        { Type: "TERM_MATCH", Field: "productFamily", Value: "Dedicated Host" },
        { Type: "TERM_MATCH", Field: "regionCode", Value: region },
        { Type: "TERM_MATCH", Field: "instanceType", Value: family }, // the family, for example "m5"
      ],
      MaxResults: 10,
    }));
    for (const item of out.PriceList ?? []) {
      const product = JSON.parse(String(item)) as {
        terms?: { OnDemand?: Record<string, { priceDimensions: Record<string, { pricePerUnit: { USD?: string } }> }> };
      };
      for (const offer of Object.values(product.terms?.OnDemand ?? {})) {
        for (const dim of Object.values(offer.priceDimensions)) {
          const usd = Number(dim.pricePerUnit.USD);
          if (usd > 0) rate = usd;
        }
      }
    }
  } catch (err) {
    console.error(`price lookup for ${family} hosts in ${region}: ${errorText(err)}`);
  }
  priceCache.set(key, rate);
  return rate;
}

const familyOf = (h: Host): string =>
  h.HostProperties?.InstanceFamily ?? (h.HostProperties?.InstanceType ?? "").split(".")[0] ?? "";
const isMac = (h: Host): boolean => familyOf(h).startsWith("mac");
const hoursAllocated = (h: Host): number =>
  h.AllocationTime ? (Date.now() - h.AllocationTime.getTime()) / 3_600_000 : Number.POSITIVE_INFINITY;

/** Why this host must not be released by the script, or undefined when it's safe. */
function releaseBlocker(h: Host): string | undefined {
  if (h.State !== "available") return `state is ${h.State}`;
  if ((h.Instances ?? []).length > 0) return `${h.Instances?.length} instances still on it`;
  if (h.HostReservationId) return `covered by Host Reservation ${h.HostReservationId}`;
  if (h.MemberOfServiceLinkedResourceGroup) return "in a License Manager host resource group";
  if (isMac(h) && hoursAllocated(h) < 24) return "Mac hosts have a 24-hour minimum allocation";
  return undefined;
}

async function scanRegion(region: string): Promise<Row[]> {
  const ec2 = new EC2Client({ region });
  const rows: Row[] = [];
  for await (const page of paginateDescribeHosts({ client: ec2 }, { MaxResults: 100 })) {
    for (const h of page.Hosts ?? []) {
      if (h.State === "released" || h.State === "released-permanent-failure") continue;
      const total = h.HostProperties?.TotalVCpus ?? 0;
      const free = h.AvailableCapacity?.AvailableVCpus ?? total;
      const used = total - free;
      const utilization = total > 0 ? Math.round((used / total) * 100) : 0;
      const instances = (h.Instances ?? []).length;
      const family = familyOf(h);
      const reserved = Boolean(h.HostReservationId);
      const rate = reserved ? null : await hostHourlyRate(region, family);
      rows.push({
        Region: region,
        Host: h.HostId ?? "",
        Name: h.Tags?.find((t) => t.Key === "Name")?.Value ?? "",
        Family: h.AllowsMultipleInstanceTypes === "on" ? `${family} (mixed)` : h.HostProperties?.InstanceType ?? family,
        AZ: h.AvailabilityZone ?? "",
        Instances: instances,
        VCpusUsed: `${used}/${total}`,
        Utilization: utilization,
        Status: instances === 0 ? "EMPTY" : utilization < lowPercent ? "LOW" : "ok",
        Billing: reserved ? "reservation" : "on-demand",
        PerMonth: rate === null ? null : Math.round(rate * HOURS_PER_MONTH * 100) / 100,
        host: h,
      });
    }
  }
  return rows;
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  for (const region of regions) {
    try {
      rows.push(...(await scanRegion(region)));
    } catch (err) {
      console.error(`${region}: ${errorText(err)}`);
    }
  }
  if (rows.length === 0) {
    console.log(`No allocated Dedicated Hosts in ${regions.join(", ")}.`);
    return;
  }
  rows.sort((a, b) => a.Utilization - b.Utilization || (b.PerMonth ?? 0) - (a.PerMonth ?? 0));
  console.table(rows.map(({ host, PerMonth, Utilization, ...shown }) => ({
    ...shown, "Util %": Utilization, "$/month": PerMonth ?? (shown.Billing === "reservation" ? "reserved" : "unknown"),
  })));

  const empty = rows.filter((r) => r.Status === "EMPTY");
  const emptyCost = empty.reduce((sum, r) => sum + (r.PerMonth ?? 0), 0);
  const flags = rows.filter((r) => r.host.AutoPlacement === "on" && r.Status === "EMPTY").length;
  const low = rows.filter((r) => r.Status === "LOW").length;
  console.log(`${empty.length} empty hosts cost about $${emptyCost.toFixed(2)} a month On-Demand; ` +
    `${low} more ${low === 1 ? "is" : "are"} under ${lowPercent}% vCPU utilization.`);
  if (flags > 0) console.log(`${flags} empty hosts have auto-placement on: untargeted launches could land there, so check before releasing.`);

  for (const id of toRelease) {
    const row = rows.find((r) => r.Host === id);
    if (!row) {
      console.log(`skip ${id}: not found in ${regions.join(", ")}`);
      continue;
    }
    const blocker = releaseBlocker(row.host);
    if (blocker) {
      console.log(`skip ${id}: ${blocker}`);
      continue;
    }
    if (!apply) {
      console.log(`would release ${id} in ${row.Region} (re-run with --apply)`);
      continue;
    }
    try {
      const out = await new EC2Client({ region: row.Region }).send(new ReleaseHostsCommand({ HostIds: [id] }));
      for (const ok of out.Successful ?? []) console.log(`released ${ok} in ${row.Region}`);
      for (const bad of out.Unsuccessful ?? []) {
        console.log(`not released ${bad.ResourceId ?? id}: ${bad.Error?.Code ?? ""} ${bad.Error?.Message ?? ""}`.trim());
      }
    } catch (err) {
      console.error(`release ${id}: ${errorText(err)}`);
    }
  }
}

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

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

# Utilization report for two Regions
AWS_PROFILE=readonly npx tsx find-idle-ec2-dedicated-hosts.ts --regions us-east-1,eu-west-1

# Flag hosts under 30% vCPU utilization as LOW
AWS_PROFILE=readonly npx tsx find-idle-ec2-dedicated-hosts.ts --low 30

# Preview, then release two empty hosts
AWS_PROFILE=readonly npx tsx find-idle-ec2-dedicated-hosts.ts --release h-0a1b2c3d4e5f60001,h-0a1b2c3d4e5f60003
AWS_PROFILE=ops-admin npx tsx find-idle-ec2-dedicated-hosts.ts --release h-0a1b2c3d4e5f60001 --apply

┌─────────┬─────────────┬───────────────────────┬────────────────┬──────────────┬──────────────┬───────────┬───────────┬─────────┬───────────────┬────────┬────────────┐
│ (index) │ Region      │ Host                  │ Name           │ Family       │ AZ           │ Instances │ VCpusUsed │ Status  │ Billing       │ Util % │ $/month    │
├─────────┼─────────────┼───────────────────────┼────────────────┼──────────────┼──────────────┼───────────┼───────────┼─────────┼───────────────┼────────┼────────────┤
│ 0       │ 'us-east-1' │ 'h-0a1b2c3d4e5f60001' │ 'sql-byol-old' │ 'm5.large'   │ 'us-east-1a' │ 0         │ '0/96'    │ 'EMPTY' │ 'on-demand'   │ 0      │ 3700.37    │
│ 1       │ 'us-east-1' │ 'h-0a1b2c3d4e5f60003' │ 'ios-build-2'  │ 'mac2.metal' │ 'us-east-1a' │ 0         │ '0/12'    │ 'EMPTY' │ 'on-demand'   │ 0      │ 474.5      │
│ 2       │ 'us-east-1' │ 'h-0a1b2c3d4e5f60002' │ 'oracle-dev'   │ 'r5 (mixed)' │ 'us-east-1b' │ 2         │ '16/96'   │ 'LOW'   │ 'on-demand'   │ 17     │ 4856.69    │
│ 3       │ 'us-east-1' │ 'h-0a1b2c3d4e5f60004' │ 'win-licensed' │ 'c5.large'   │ 'us-east-1c' │ 36        │ '72/72'   │ 'ok'    │ 'reservation' │ 100    │ 'reserved' │
└─────────┴─────────────┴───────────────────────┴────────────────┴──────────────┴──────────────┴───────────┴───────────┴─────────┴───────────────┴────────┴────────────┘
2 empty hosts cost about $4174.87 a month On-Demand; 1 more is under 50% vCPU utilization.
would release h-0a1b2c3d4e5f60001 in us-east-1 (re-run with --apply)
skip h-0a1b2c3d4e5f60003: Mac hosts have a 24-hour minimum allocation