Detect and Stop Underutilized EC2 Instances by CPU

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReportIdleInstances",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "StopInstancesInOneRegion",
      "Effect": "Allow",
      "Action": "ec2:StopInstances",
      "Resource": "arn:aws:ec2:us-east-1:123456789012:instance/*"
    }
  ]
}

// stop-idle-ec2.ts
// Finds running EC2 instances whose CPUUtilization stayed low for N days.
// Report-only by default. Pass --stop to actually stop the instances it lists.
// Usage: npx tsx stop-idle-ec2.ts [--days 14] [--avg 5] [--max 20] [--stop]
import {
  EC2Client,
  paginateDescribeInstances,
  StopInstancesCommand,
  type Instance,
} from "@aws-sdk/client-ec2";
import {
  CloudWatchClient,
  GetMetricDataCommand,
  type MetricDataQuery,
} from "@aws-sdk/client-cloudwatch";

const SKIP_TAG = "cwc:keep-running"; // tag an instance with this key to exclude it

function numberArg(flag: string, fallback: number): number {
  const i = process.argv.indexOf(flag);
  const value = i === -1 ? fallback : Number(process.argv[i + 1]);
  if (!Number.isFinite(value) || value <= 0) throw new Error(`${flag} must be a positive number`);
  return value;
}

const tag = (i: Instance, key: string) => i.Tags?.find((t) => t.Key === key)?.Value;

// Why an instance must not be stopped by this script, or undefined if it's a candidate.
function skipReason(i: Instance, since: Date): string | undefined {
  if (i.InstanceLifecycle === "spot") return "Spot Instance";
  if (i.RootDeviceType === "instance-store") return "instance-store root volume";
  if (tag(i, "aws:autoscaling:groupName")) return "in an Auto Scaling group";
  if (tag(i, SKIP_TAG) !== undefined) return `tagged ${SKIP_TAG}`;
  if (i.LaunchTime && i.LaunchTime > since) return "launched inside the lookback window";
  return undefined;
}

async function main(): Promise<void> {
  const days = numberArg("--days", 14);
  const avgLimit = numberArg("--avg", 5); // mean of hourly averages, percent
  const maxLimit = numberArg("--max", 20); // highest hourly average, percent
  const stop = process.argv.includes("--stop");

  // No region given: the SDK uses AWS_REGION or the region in your AWS profile.
  const ec2 = new EC2Client({});
  const cloudwatch = new CloudWatchClient({});
  const end = new Date();
  const start = new Date(end.getTime() - days * 86_400_000);

  // 1. Running instances, split into candidates and skipped ones.
  const candidates: Instance[] = [];
  for await (const page of paginateDescribeInstances(
    { client: ec2 },
    { Filters: [{ Name: "instance-state-name", Values: ["running"] }] },
  )) {
    for (const reservation of page.Reservations ?? []) {
      for (const instance of reservation.Instances ?? []) {
        const reason = skipReason(instance, start);
        if (reason) console.log(`skip ${instance.InstanceId}: ${reason}`);
        else candidates.push(instance);
      }
    }
  }
  if (candidates.length === 0) {
    console.log("No running instances to evaluate.");
    return;
  }

  // 2. Hourly average CPUUtilization for each candidate (up to 500 queries per request).
  const values = new Map<string, number[]>();
  for (let i = 0; i < candidates.length; i += 500) {
    const batch = candidates.slice(i, i + 500);
    const queries: MetricDataQuery[] = batch.map((instance, j) => ({
      Id: `q${i + j}`,
      MetricStat: {
        Metric: {
          Namespace: "AWS/EC2",
          MetricName: "CPUUtilization",
          Dimensions: [{ Name: "InstanceId", Value: instance.InstanceId }],
        },
        Period: 3600,
        Stat: "Average",
      },
    }));
    let nextToken: string | undefined;
    do {
      const res = await cloudwatch.send(
        new GetMetricDataCommand({
          StartTime: start,
          EndTime: end,
          MetricDataQueries: queries,
          NextToken: nextToken,
        }),
      );
      for (const result of res.MetricDataResults ?? []) {
        const id = result.Id ?? "";
        values.set(id, [...(values.get(id) ?? []), ...(result.Values ?? [])]);
      }
      nextToken = res.NextToken;
    } while (nextToken);
  }

  // 3. Flag instances whose average and peak hourly CPU are both under the limits.
  const idle: { id: string; name: string; type: string; avg: number; max: number }[] = [];
  candidates.forEach((instance, index) => {
    const points = values.get(`q${index}`) ?? [];
    if (points.length < 24) {
      console.log(`skip ${instance.InstanceId}: only ${points.length} hourly datapoints`);
      return;
    }
    const avg = points.reduce((s, v) => s + v, 0) / points.length;
    const max = Math.max(...points);
    if (avg < avgLimit && max < maxLimit) {
      idle.push({
        id: instance.InstanceId ?? "",
        name: tag(instance, "Name") ?? "",
        type: instance.InstanceType ?? "",
        avg,
        max,
      });
    }
  });

  console.log(`\nUnderutilized over the last ${days} days (avg < ${avgLimit}%, peak hour < ${maxLimit}%):`);
  if (idle.length === 0) {
    console.log("none");
    return;
  }
  console.table(
    idle.map((r) => ({
      Instance: r.id,
      Name: r.name,
      Type: r.type,
      "Avg CPU %": r.avg.toFixed(1),
      "Peak hour %": r.max.toFixed(1),
    })),
  );

  if (!stop) {
    console.log("Report only. Nothing was stopped. Re-run with --stop to stop these instances.");
    return;
  }

  // 4. Stop in batches of 50 and show the state change EC2 reports.
  const ids = idle.map((r) => r.id);
  for (let i = 0; i < ids.length; i += 50) {
    const res = await ec2.send(new StopInstancesCommand({ InstanceIds: ids.slice(i, i + 50) }));
    for (const change of res.StoppingInstances ?? []) {
      console.log(`${change.InstanceId}: ${change.PreviousState?.Name} -> ${change.CurrentState?.Name}`);
    }
  }
}

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

# 1. Report only (default): nothing is changed
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx stop-idle-ec2.ts

# Stricter thresholds over 30 days
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx stop-idle-ec2.ts --days 30 --avg 2 --max 10

# 2. After reviewing the report: actually stop the listed instances
AWS_PROFILE=ops AWS_REGION=us-east-1 npx tsx stop-idle-ec2.ts --stop

skip i-0a1b2c3d4e5f60718: in an Auto Scaling group
skip i-0f9e8d7c6b5a40312: tagged cwc:keep-running
skip i-03c4d5e6f7a8b9012: launched inside the lookback window

Underutilized over the last 14 days (avg < 5%, peak hour < 20%):
┌─────────┬───────────────────────┬──────────────────┬─────────────┬───────────┬─────────────┐
│ (index) │ Instance              │ Name             │ Type        │ Avg CPU % │ Peak hour % │
├─────────┼───────────────────────┼──────────────────┼─────────────┼───────────┼─────────────┤
│ 0       │ 'i-0123456789abcdef0' │ 'staging-api-2'  │ 'm5.large'  │ '1.8'     │ '6.4'       │
│ 1       │ 'i-0fedcba9876543210' │ 'old-jenkins'    │ 't3.medium' │ '0.6'     │ '3.1'       │
└─────────┴───────────────────────┴──────────────────┴─────────────┴───────────┴─────────────┘
Report only. Nothing was stopped. Re-run with --stop to stop these instances.