Get EC2 Right-Sizing Recommendations From Compute Optimizer

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadEc2Recommendations",
      "Effect": "Allow",
      "Action": [
        "compute-optimizer:GetEnrollmentStatus",
        "compute-optimizer:GetEC2InstanceRecommendations",
        "ec2:DescribeInstances"
      ],
      "Resource": "*"
    },
    {
      "Sid": "OptInOnlyWithApply",
      "Effect": "Allow",
      "Action": "compute-optimizer:UpdateEnrollmentStatus",
      "Resource": "*"
    },
    {
      "Sid": "CreateServiceLinkedRoleOnOptIn",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/compute-optimizer.amazonaws.com/AWSServiceRoleForComputeOptimizer*",
      "Condition": { "StringLike": { "iam:AWSServiceName": "compute-optimizer.amazonaws.com" } }
    },
    {
      "Sid": "ConfigureServiceLinkedRole",
      "Effect": "Allow",
      "Action": "iam:PutRolePolicy",
      "Resource": "arn:aws:iam::*:role/aws-service-role/compute-optimizer.amazonaws.com/AWSServiceRoleForComputeOptimizer"
    }
  ]
}

// get-ec2-rightsizing-recommendations.ts
// Reads AWS Compute Optimizer EC2 instance recommendations in one or more Regions and prints the
// over- and under-provisioned instances with the top-ranked alternative, its performance risk and the
// estimated monthly savings. Report only by default. --apply opts the account in to Compute Optimizer
// (UpdateEnrollmentStatus) when it isn't enrolled yet; it never changes an instance.
// Usage: npx tsx get-ec2-rightsizing-recommendations.ts [--regions us-east-1,eu-west-1]
//        [--findings Overprovisioned,Underprovisioned] [--csv rightsizing.csv] [--apply]
import { writeFileSync } from "node:fs";
import {
  ComputeOptimizerClient,
  GetEC2InstanceRecommendationsCommand,
  GetEnrollmentStatusCommand,
  UpdateEnrollmentStatusCommand,
  type InstanceRecommendation,
  type InstanceRecommendationOption,
} from "@aws-sdk/client-compute-optimizer";

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 findings = (flag("--findings") ?? "Overprovisioned,Underprovisioned").split(",").map((f) => f.trim()).filter(Boolean);
const csvPath = flag("--csv");
const apply = args.includes("--apply");

interface Row {
  Region: string;
  Instance: string;
  Name: string;
  Finding: string;
  Reasons: string;
  Current: string;
  Suggested: string;
  Risk: string;
  Migration: string;
  Differences: string;
  SavingPerMonth: number;
  Basis: string;
  LookBackDays: number;
}

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

/** The rank-1 option, or the first option when no rank is present. */
function topOption(rec: InstanceRecommendation): InstanceRecommendationOption | undefined {
  const options = [...(rec.recommendationOptions ?? [])];
  options.sort((a, b) => (a.rank ?? 99) - (b.rank ?? 99));
  return options[0];
}

/** Savings after Savings Plans and RI discounts when Compute Optimizer has them, otherwise On-Demand based. */
function saving(option: InstanceRecommendationOption | undefined): { value: number; basis: string } {
  const after = option?.savingsOpportunityAfterDiscounts?.estimatedMonthlySavings?.value;
  if (after !== undefined) return { value: after, basis: "after discounts" };
  const onDemand = option?.savingsOpportunity?.estimatedMonthlySavings?.value;
  return { value: onDemand ?? 0, basis: onDemand !== undefined ? "on-demand" : "none" };
}

async function ensureEnrolled(client: ComputeOptimizerClient): Promise<boolean> {
  const status = await client.send(new GetEnrollmentStatusCommand({}));
  if (status.status === "Active") return true;
  console.log(`Compute Optimizer enrollment status: ${status.status ?? "unknown"} ${status.statusReason ?? ""}`.trim());
  if (!apply) {
    console.log("Re-run with --apply to opt this account in. Recommendations can take up to 24 hours to appear.");
    return false;
  }
  const out = await client.send(new UpdateEnrollmentStatusCommand({ status: "Active" }));
  console.log(`Opt-in requested: status is now ${out.status ?? "unknown"}. Run the report again tomorrow.`);
  return false;
}

async function scanRegion(region: string): Promise<Row[]> {
  const client = new ComputeOptimizerClient({ region });
  const rows: Row[] = [];
  let nextToken: string | undefined;
  do {
    const page = await client.send(new GetEC2InstanceRecommendationsCommand({
      filters: [{ name: "Finding", values: findings }],
      maxResults: 100,
      nextToken,
    }));
    for (const e of page.errors ?? []) console.error(`${region}: ${e.identifier ?? ""} ${e.code ?? ""} ${e.message ?? ""}`.trim());
    for (const rec of page.instanceRecommendations ?? []) {
      const option = topOption(rec);
      const { value, basis } = saving(option);
      rows.push({
        Region: region,
        Instance: rec.instanceArn?.split("/").pop() ?? "",
        Name: rec.instanceName ?? "",
        Finding: rec.finding ?? "",
        Reasons: (rec.findingReasonCodes ?? []).map((c) => c.replace(/provisioned$/, "")).join(" "),
        Current: rec.currentInstanceType ?? "",
        Suggested: option?.instanceType ?? "",
        Risk: option?.performanceRisk !== undefined ? option.performanceRisk.toFixed(1) : "",
        Migration: option?.migrationEffort ?? "",
        Differences: (option?.platformDifferences ?? []).join(" ") || "-",
        SavingPerMonth: Math.round(value * 100) / 100,
        Basis: basis,
        LookBackDays: Math.round(rec.lookBackPeriodInDays ?? 0),
      });
    }
    nextToken = page.nextToken;
  } while (nextToken);
  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> {
  if (!(await ensureEnrolled(new ComputeOptimizerClient({ region: regions[0] })))) return;

  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 ${findings.join(" or ")} EC2 instances in ${regions.join(", ")}.`);
    return;
  }
  rows.sort((a, b) => b.SavingPerMonth - a.SavingPerMonth);
  console.table(rows.map(({ Basis, LookBackDays, ...shown }) => shown));

  const over = rows.filter((r) => r.Finding === "Overprovisioned");
  const total = over.reduce((sum, r) => sum + r.SavingPerMonth, 0);
  const risky = over.filter((r) => Number(r.Risk) >= 3 || r.Differences !== "-").length;
  console.log(`${over.length} over-provisioned instances could save about $${total.toFixed(2)} a month ` +
    `(${risky} need extra testing: performance risk 3+ or platform differences).`);
  console.log(`${rows.length - over.length} under-provisioned instances may need a larger type.`);
  if (csvPath) {
    writeFileSync(csvPath, toCsv(rows));
    console.log(`Wrote ${rows.length} rows to ${csvPath}`);
  }
}

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

npm install @aws-sdk/client-compute-optimizer
npm install --save-dev tsx typescript @types/node

# Over- and under-provisioned instances in two Regions, saved to CSV
AWS_PROFILE=readonly npx tsx get-ec2-rightsizing-recommendations.ts --regions us-east-1,eu-west-1 --csv rightsizing.csv

# Only under-provisioned instances
AWS_PROFILE=readonly npx tsx get-ec2-rightsizing-recommendations.ts --findings Underprovisioned

# Opt the account in if it isn't enrolled yet
AWS_PROFILE=finops-admin npx tsx get-ec2-rightsizing-recommendations.ts --apply

┌─────────┬─────────────┬───────────────────────┬─────────────────┬────────────────────┬──────────────────────┬──────────────┬───────────────┬───────┬───────────┬───────────────────────────────┬────────────────┐
│ (index) │ Region      │ Instance              │ Name            │ Finding            │ Reasons              │ Current      │ Suggested     │ Risk  │ Migration │ Differences                   │ SavingPerMonth │
├─────────┼─────────────┼───────────────────────┼─────────────────┼────────────────────┼──────────────────────┼──────────────┼───────────────┼───────┼───────────┼───────────────────────────────┼────────────────┤
│ 0       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60002' │ 'batch-worker'  │ 'Overprovisioned'  │ 'CPUOver'            │ 'c5.4xlarge' │ 'c7g.2xlarge' │ '2.0' │ 'Medium'  │ 'Architecture'                │ 314.63         │
│ 1       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60001' │ 'reporting-api' │ 'Overprovisioned'  │ 'CPUOver MemoryOver' │ 'm5.2xlarge' │ 'm5.xlarge'   │ '1.0' │ 'VeryLow' │ '-'                           │ 112.13         │
│ 2       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60003' │ 'legacy-cms'    │ 'Overprovisioned'  │ 'CPUOver'            │ 't2.large'   │ 't3.medium'   │ '3.0' │ 'VeryLow' │ 'Hypervisor NetworkInterface' │ 37.23          │
│ 3       │ 'us-east-1' │ 'i-0a1b2c3d4e5f60004' │ 'search-node'   │ 'Underprovisioned' │ 'MemoryUnder'        │ 'r5.large'   │ 'r5.xlarge'   │ '0.0' │ 'VeryLow' │ '-'                           │ 0              │
└─────────┴─────────────┴───────────────────────┴─────────────────┴────────────────────┴──────────────────────┴──────────────┴───────────────┴───────┴───────────┴───────────────────────────────┴────────────────┘
3 over-provisioned instances could save about $463.99 a month (2 need extra testing: performance risk 3+ or platform differences).
1 under-provisioned instances may need a larger type.