@oneuptime/common 11.7.3 → 12.0.0

package/Tests/Types/Kubernetes/KubernetesRightSizing.test.ts

@@ -0,0 +1,323 @@
+import {
+  MIN_RECOMMENDED_CPU_CORES,
+  MIN_RECOMMENDED_MEMORY_BYTES,
+  RightSizingObservation,
+  RightSizingRecommendation,
+  RightSizingVerdict,
+  buildRightSizingRecommendation,
+  formatCpuCores,
+  formatMemoryBytes,
+  hasActionableRecommendation,
+} from "../../../Types/Kubernetes/KubernetesRightSizing";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Right-sizing turns cost-window aggregates into "set this request to that".
+ * The dangerous failure is not an imprecise saving — it is advising a memory
+ * request below what a container actually peaked at, which turns into an
+ * OOMKill in production. So the tests below lean hardest on the cases where
+ * the recommendation must refuse to answer.
+ */
+
+const MIB: number = 1024 * 1024;
+const GIB: number = 1024 * MIB;
+
+// A week of hourly windows for a single replica.
+const WEEK_HOURS: number = 168;
+
+function observation(
+  overrides: Partial<RightSizingObservation> = {},
+): RightSizingObservation {
+  return {
+    namespace: "prod",
+    controllerKind: "Deployment",
+    controllerName: "api",
+    containerName: "api",
+    sampleCount: WEEK_HOURS,
+    cpuCoreRequestAverage: 1,
+    cpuCoreUsageP95: 0.2,
+    cpuCost: 10,
+    ramBytesRequestAverage: GIB,
+    ramBytesUsagePeak: 256 * MIB,
+    ramCost: 6,
+    ...overrides,
+  };
+}
+
+describe("buildRightSizingRecommendation - CPU", () => {
+  test("flags an over-provisioned request and sizes it from P95 plus headroom", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ cpuCoreRequestAverage: 1, cpuCoreUsageP95: 0.2 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Overprovisioned);
+    // 0.2 * 1.25 = 0.25 cores, already on a 10m boundary.
+    expect(result.cpu.recommended).toBeCloseTo(0.25, 5);
+    expect(result.cpu.current).toBe(1);
+  });
+
+  test("rounds the recommendation up to the next 10 millicores", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ cpuCoreUsageP95: 0.101 }),
+      WEEK_HOURS,
+    );
+
+    // 0.101 * 1.25 = 0.12625 -> 0.13
+    expect(result.cpu.recommended).toBeCloseTo(0.13, 5);
+  });
+
+  test("flags an under-provisioned request", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ cpuCoreRequestAverage: 0.1, cpuCoreUsageP95: 0.5 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Underprovisioned);
+    expect(result.cpu.recommended).toBeCloseTo(0.63, 5);
+  });
+
+  test("leaves a request inside the significance band alone", () => {
+    // 0.8 * 1.25 = 1.0 exactly, so the request is already right.
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ cpuCoreRequestAverage: 1, cpuCoreUsageP95: 0.8 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Optimal);
+    expect(result.cpu.costDeltaInWindow).toBe(0);
+  });
+
+  test("never recommends below the CPU floor", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ cpuCoreRequestAverage: 0.5, cpuCoreUsageP95: 0.0001 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.recommended).toBe(MIN_RECOMMENDED_CPU_CORES);
+  });
+
+  test("reports a container with no request as a scheduling problem, not a saving", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        cpuCoreRequestAverage: 0,
+        cpuCoreUsageP95: 0.4,
+        ramBytesRequestAverage: 0,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.NoRequestSet);
+    expect(result.cpu.current).toBeNull();
+    expect(result.cpu.recommended).toBeCloseTo(0.5, 5);
+    expect(result.cpu.costDeltaInWindow).toBe(0);
+    expect(result.estimatedMonthlySavings).toBe(0);
+  });
+});
+
+describe("buildRightSizingRecommendation - memory", () => {
+  test("sizes memory from the peak, not the request", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        ramBytesRequestAverage: GIB,
+        ramBytesUsagePeak: 256 * MIB,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(result.memory.verdict).toBe(RightSizingVerdict.Overprovisioned);
+    // 256Mi * 1.25 = 320Mi, already a multiple of the 16Mi step.
+    expect(result.memory.recommended).toBe(320 * MIB);
+  });
+
+  test("refuses to size memory when no peak was reported", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ ramBytesUsagePeak: 0 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.memory.verdict).toBe(RightSizingVerdict.Unavailable);
+    expect(result.memory.recommended).toBeNull();
+    expect(result.memory.costDeltaInWindow).toBe(0);
+    expect(result.memory.unavailableReason).toContain("Prometheus");
+  });
+
+  test("a missing memory peak does not block the CPU recommendation", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ ramBytesUsagePeak: 0 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Overprovisioned);
+    expect(result.estimatedMonthlySavings).toBeGreaterThan(0);
+  });
+
+  test("rounds memory up to the next 16Mi", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ ramBytesUsagePeak: 100 * MIB }),
+      WEEK_HOURS,
+    );
+
+    // 100Mi * 1.25 = 125Mi -> 128Mi
+    expect(result.memory.recommended).toBe(128 * MIB);
+  });
+
+  test("never recommends below the memory floor", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ ramBytesUsagePeak: 1024 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.memory.recommended).toBe(MIN_RECOMMENDED_MEMORY_BYTES);
+  });
+});
+
+describe("buildRightSizingRecommendation - confidence gate", () => {
+  test("advises nothing when the window is shorter than a day", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ sampleCount: 4 }),
+      4,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Unavailable);
+    expect(result.memory.verdict).toBe(RightSizingVerdict.Unavailable);
+    expect(result.estimatedMonthlySavings).toBe(0);
+    expect(hasActionableRecommendation(result)).toBe(false);
+  });
+
+  test("advises nothing when a long window holds only a few samples", () => {
+    // A workload that existed for two hours of a week-long window.
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ sampleCount: 2 }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Unavailable);
+    expect(result.cpu.unavailableReason).toContain("at least a day");
+  });
+});
+
+describe("buildRightSizingRecommendation - savings", () => {
+  test("scales the window saving to a month", () => {
+    /*
+     * CPU: request 1 core, P95 0.2 -> recommend 0.25, so 75% of $10 goes.
+     * RAM: request 1Gi, peak 256Mi -> recommend 320Mi, so 68.75% of $6 goes.
+     * Window saving = 7.5 + 4.125 = 11.625 over 168h; a 730h month is
+     * 4.3452... times that window.
+     */
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation(),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.costDeltaInWindow).toBeCloseTo(-7.5, 5);
+    expect(result.memory.costDeltaInWindow).toBeCloseTo(-4.125, 5);
+    expect(result.estimatedMonthlySavings).toBeCloseTo(11.625 * (730 / 168), 4);
+    expect(result.estimatedMonthlyIncrease).toBe(0);
+  });
+
+  test("an under-provisioned workload reports an increase, never a saving", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        cpuCoreRequestAverage: 0.1,
+        cpuCoreUsageP95: 0.5,
+        ramBytesRequestAverage: 64 * MIB,
+        ramBytesUsagePeak: 512 * MIB,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(result.estimatedMonthlySavings).toBe(0);
+    expect(result.estimatedMonthlyIncrease).toBeGreaterThan(0);
+  });
+
+  test("prices the increase off actual usage when usage already exceeds the request", () => {
+    /*
+     * Request 0.1 but P95 usage 0.5: the engine already bills for 0.5, so
+     * moving to a 0.63 request costs 26% more, not 530% more.
+     */
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        cpuCoreRequestAverage: 0.1,
+        cpuCoreUsageP95: 0.5,
+        cpuCost: 10,
+        ramBytesUsagePeak: 0,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.costDeltaInWindow).toBeCloseTo(10 * (0.63 / 0.5 - 1), 5);
+  });
+
+  test("a replica count in sampleCount does not inflate the monthly projection", () => {
+    // Same window, same spend, three replicas' worth of rows.
+    const single: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ sampleCount: WEEK_HOURS }),
+      WEEK_HOURS,
+    );
+    const triple: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({ sampleCount: WEEK_HOURS * 3 }),
+      WEEK_HOURS,
+    );
+
+    expect(triple.estimatedMonthlySavings).toBeCloseTo(
+      single.estimatedMonthlySavings,
+      5,
+    );
+  });
+});
+
+describe("hasActionableRecommendation", () => {
+  test("is false when both resources are already right-sized", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        cpuCoreRequestAverage: 1,
+        cpuCoreUsageP95: 0.8,
+        ramBytesRequestAverage: 320 * MIB,
+        ramBytesUsagePeak: 256 * MIB,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(result.cpu.verdict).toBe(RightSizingVerdict.Optimal);
+    expect(result.memory.verdict).toBe(RightSizingVerdict.Optimal);
+    expect(hasActionableRecommendation(result)).toBe(false);
+  });
+
+  test("is true when only one resource needs a change", () => {
+    const result: RightSizingRecommendation = buildRightSizingRecommendation(
+      observation({
+        cpuCoreRequestAverage: 1,
+        cpuCoreUsageP95: 0.8,
+        ramBytesRequestAverage: GIB,
+        ramBytesUsagePeak: 128 * MIB,
+      }),
+      WEEK_HOURS,
+    );
+
+    expect(hasActionableRecommendation(result)).toBe(true);
+  });
+});
+
+describe("formatting", () => {
+  test("writes sub-core CPU as millicores", () => {
+    expect(formatCpuCores(0.25)).toBe("250m");
+    expect(formatCpuCores(0.01)).toBe("10m");
+  });
+
+  test("writes whole cores as decimals", () => {
+    expect(formatCpuCores(1)).toBe("1");
+    expect(formatCpuCores(2.5)).toBe("2.5");
+  });
+
+  test("writes memory as Kubernetes binary quantities", () => {
+    expect(formatMemoryBytes(320 * MIB)).toBe("320Mi");
+    expect(formatMemoryBytes(2 * GIB)).toBe("2Gi");
+    expect(formatMemoryBytes(1.5 * GIB)).toBe("1.5Gi");
+  });
+
+  test("renders unknown values as a dash", () => {
+    expect(formatCpuCores(null)).toBe("-");
+    expect(formatMemoryBytes(null)).toBe("-");
+  });
+});

package/Tests/Types/Metrics/MetricDownsamplingRetentionDays.test.ts

@@ -0,0 +1,77 @@
+import MetricDownsamplingRetentionDays, {
+  DEFAULT_METRIC_CARDINALITY_BUDGET,
+  DEFAULT_METRIC_DOWNSAMPLING_RETENTION_DAYS,
+  resolveTierRetentionDays,
+} from "../../../Types/Metrics/MetricDownsamplingRetentionDays";
+import { describe, expect, test } from "@jest/globals";
+
+describe("MetricDownsamplingRetentionDays", () => {
+  describe("defaults", () => {
+    test("exposes the documented per-tier default retention", () => {
+      expect(DEFAULT_METRIC_DOWNSAMPLING_RETENTION_DAYS).toEqual({
+        raw: 7,
+        "1m": 14,
+        "5m": 30,
+        "1h": 90,
+        "1d": 365,
+      });
+    });
+
+    test("exposes the default cardinality budget", () => {
+      expect(DEFAULT_METRIC_CARDINALITY_BUDGET).toBe(10000);
+    });
+  });
+
+  describe("resolveTierRetentionDays", () => {
+    test("prefers a positive service override over everything else", () => {
+      const serviceOverride: MetricDownsamplingRetentionDays = { raw: 3 };
+      const projectDefault: MetricDownsamplingRetentionDays = { raw: 20 };
+
+      expect(
+        resolveTierRetentionDays("raw", serviceOverride, projectDefault),
+      ).toBe(3);
+    });
+
+    test("falls back to the project default when the service override is missing", () => {
+      const projectDefault: MetricDownsamplingRetentionDays = { "1m": 21 };
+
+      expect(resolveTierRetentionDays("1m", null, projectDefault)).toBe(21);
+      expect(resolveTierRetentionDays("1m", {}, projectDefault)).toBe(21);
+      expect(resolveTierRetentionDays("1m", undefined, projectDefault)).toBe(
+        21,
+      );
+    });
+
+    test("falls back to the hardcoded default when neither override is set", () => {
+      expect(resolveTierRetentionDays("5m", null, null)).toBe(30);
+      expect(resolveTierRetentionDays("1h", undefined, undefined)).toBe(90);
+      expect(resolveTierRetentionDays("1d", {}, {})).toBe(365);
+    });
+
+    test("ignores non-positive service values and continues the fallback chain", () => {
+      const projectDefault: MetricDownsamplingRetentionDays = { raw: 12 };
+
+      // 0 and negative must NOT win — they fall through to the project default.
+      expect(resolveTierRetentionDays("raw", { raw: 0 }, projectDefault)).toBe(
+        12,
+      );
+      expect(resolveTierRetentionDays("raw", { raw: -5 }, projectDefault)).toBe(
+        12,
+      );
+    });
+
+    test("ignores null service values and uses the project default", () => {
+      const projectDefault: MetricDownsamplingRetentionDays = { raw: 9 };
+
+      expect(
+        resolveTierRetentionDays("raw", { raw: null }, projectDefault),
+      ).toBe(9);
+    });
+
+    test("ignores a non-positive project default and uses the hardcoded default", () => {
+      // service missing, project default is 0 -> hardcoded default (7).
+      expect(resolveTierRetentionDays("raw", null, { raw: 0 })).toBe(7);
+      expect(resolveTierRetentionDays("raw", null, { raw: -1 })).toBe(7);
+    });
+  });
+});

package/Tests/Types/Monitor/KubernetesAlertTemplates.test.ts

@@ -7,17 +7,21 @@ import {
 import MonitorStep from "../../../Types/Monitor/MonitorStep";
 import MonitorStepKubernetesMonitor from "../../../Types/Monitor/MonitorStepKubernetesMonitor";
 import MetricsAggregationType from "../../../Types/Metrics/MetricsAggregationType";
+import { FilterType } from "../../../Types/Monitor/CriteriaFilter";
 import ObjectID from "../../../Types/ObjectID";
 
 /*
- * These tests lock in the subtle, easy-to-regress decisions in the per-node
- * ratio alert templates (request utilization + usage utilization):
+ * These tests lock in the subtle, easy-to-regress decisions in the
+ * per-series ratio alert templates (node request/usage utilization, plus
+ * the autoscaling and container-limit saturation templates):
  *
  *   1. Group-by uses the ClickHouse-stored `resource.`-prefixed attribute
  *      name (`resource.k8s.node.name`), not the bare `k8s.node.name`.
  *      OneUptime stamps OTel resource attributes with a `resource.` prefix
  *      at ingest, so the bare key would match nothing and collapse every
- *      node into one mislabeled series.
+ *      node into one mislabeled series. The key differs per template — the
+ *      HPA template groups per HPA and the pod-limit templates per pod —
+ *      so each case carries its own expected key.
  *
  *   2. The aggregation differs by numerator shape:
  *        - Request utilization sums MANY container series per node, and both
@@ -27,9 +31,17 @@ import ObjectID from "../../../Types/ObjectID";
  *          (kubeletstats) and denominator (k8s_cluster) come from different
  *          receivers, so `Avg` on both sides gives the correct per-minute
  *          ratio regardless of each receiver's scrape count.
+ *        - The saturation templates are all `Avg` — see the pod-memory
+ *          template's note in KubernetesAlertTemplates.ts for the
+ *          multi-container trade-off that choice accepts.
  *
  *   3. The criteria reference the FORMULA alias (the computed percentage),
  *      not a raw query alias.
+ *
+ *   4. The unhealthy and healthy criteria PARTITION the value range — no
+ *      gap (a value that matches neither leaves the monitor stuck in its
+ *      previous status) and no overlap (a value that matches both makes the
+ *      resulting status depend on evaluation order).
  */
 
 interface RatioTemplateCase {
@@ -41,6 +53,7 @@ interface RatioTemplateCase {
   resultAlias: string;
   aggregation: MetricsAggregationType;
   threshold: number;
+  groupBy: string;
 }
 
 const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
@@ -54,6 +67,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_cpu_request_utilization",
     aggregation: MetricsAggregationType.Sum,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   {
     id: "k8s-node-memory-request-utilization",
@@ -64,6 +78,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_memory_request_utilization",
     aggregation: MetricsAggregationType.Sum,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   // Usage utilization — Avg/Avg (one series per node, cross-receiver).
   {
@@ -75,6 +90,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_cpu_utilization",
     aggregation: MetricsAggregationType.Avg,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   {
     id: "k8s-high-memory",
@@ -85,6 +101,50 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_memory_utilization",
     aggregation: MetricsAggregationType.Avg,
     threshold: 85,
+    groupBy: "resource.k8s.node.name",
+  },
+  /*
+   * Autoscaling / limit saturation — Avg/Avg, and NOT keyed on the node.
+   *
+   * The HPA ratio groups per HPA object; the two pod-limit ratios group
+   * per pod. Locking the group-by key here is the point of these cases:
+   * these were the first ratio templates in this file not keyed on
+   * `resource.k8s.node.name`, so a copy-paste of the node key would
+   * silently collapse every HPA (or every pod) into one mislabeled
+   * series that still renders and still alerts.
+   */
+  {
+    id: "k8s-hpa-at-max-replicas",
+    numerator: "k8s.hpa.current_replicas",
+    denominator: "k8s.hpa.max_replicas",
+    numAlias: "current_replicas",
+    denAlias: "max_replicas",
+    resultAlias: "hpa_replica_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.hpa.name",
+  },
+  {
+    id: "k8s-pod-memory-limit-saturation",
+    numerator: "k8s.pod.memory.usage",
+    denominator: "k8s.container.memory_limit",
+    numAlias: "used_mem",
+    denAlias: "limit_mem",
+    resultAlias: "pod_memory_limit_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.pod.name",
+  },
+  {
+    id: "k8s-pod-cpu-limit-saturation",
+    numerator: "k8s.pod.cpu.utilization",
+    denominator: "k8s.container.cpu_limit",
+    numAlias: "used_cpu",
+    denAlias: "limit_cpu",
+    resultAlias: "pod_cpu_limit_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.pod.name",
   },
 ];
 
@@ -108,8 +168,8 @@ function getKubernetesMonitor(step: MonitorStep): MonitorStepKubernetesMonitor {
   return kubernetesMonitor;
 }
 
-describe("KubernetesAlertTemplates - per-node ratio templates", () => {
-  test("all four ratio templates are registered", () => {
+describe("KubernetesAlertTemplates - per-series ratio templates", () => {
+  test("all ratio templates are registered", () => {
     const ids: Array<string> = getAllKubernetesAlertTemplates().map(
       (t: KubernetesAlertTemplate) => {
         return t.id;
@@ -121,7 +181,7 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
   });
 
   test.each(RATIO_TEMPLATES)(
-    "$id is a per-node ($aggregation/$aggregation) ratio keyed on resource.k8s.node.name",
+    "$id is a ($aggregation/$aggregation) ratio keyed on $groupBy",
     (tc: RatioTemplateCase) => {
       const template: KubernetesAlertTemplate | undefined =
         getKubernetesAlertTemplateById(tc.id);
@@ -162,16 +222,19 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
       );
 
       /*
-       * Decision (1): group by the resource-prefixed node attribute on BOTH
+       * Decision (1): group by the resource-prefixed attribute on BOTH
        * queries so the per-series fingerprints line up for the formula join.
        */
       expect(numerator.metricQueryData.groupByAttributeKeys).toEqual([
-        "resource.k8s.node.name",
+        tc.groupBy,
       ]);
       expect(denominator.metricQueryData.groupByAttributeKeys).toEqual([
-        "resource.k8s.node.name",
+        tc.groupBy,
       ]);
 
+      // The `resource.` prefix is load-bearing — a bare OTel key matches nothing.
+      expect(tc.groupBy.startsWith("resource.")).toBe(true);
+
       // Formula divides numerator by denominator and scales to a percentage.
       expect(formulaConfigs[0].metricFormulaData.metricFormula).toBe(
         `(${tc.numAlias} / ${tc.denAlias}) * 100`,
@@ -190,4 +253,109 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
       expect(offlineFilters[0].value).toBe(tc.threshold);
     },
   );
+
+  /*
+   * Decision (4): unhealthy and healthy must be exact complements at the
+   * same threshold. Both halves are hand-written per template, so the
+   * failure mode is a strict/non-strict slip — pairing `> 90` with
+   * `< 90` leaves exactly 90 matching neither criterion (the monitor
+   * silently holds its previous status), and pairing `>= 90` with
+   * `<= 90` makes 90 match both (status depends on evaluation order).
+   */
+  const COMPLEMENT_OF: Record<string, string> = {
+    [FilterType.GreaterThan]: FilterType.LessThanOrEqualTo,
+    [FilterType.GreaterThanOrEqualTo]: FilterType.LessThan,
+  };
+
+  test.each(RATIO_TEMPLATES)(
+    "$id unhealthy/healthy criteria partition the range at $threshold",
+    (tc: RatioTemplateCase) => {
+      const template: KubernetesAlertTemplate | undefined =
+        getKubernetesAlertTemplateById(tc.id);
+      const step: MonitorStep = template!.getMonitorStep(buildArgs());
+
+      const instances: Array<any> = step.data?.monitorCriteria.data
+        ?.monitorCriteriaInstanceArray as Array<any>;
+      const [offline, online] = instances;
+
+      const offlineFilter: any = offline.data.filters[0];
+      const onlineFilter: any = online.data.filters[0];
+
+      // Same metric, same threshold — only the comparison direction differs.
+      expect(onlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.resultAlias,
+      );
+      expect(onlineFilter.value).toBe(tc.threshold);
+
+      expect(COMPLEMENT_OF[offlineFilter.filterType]).toBe(
+        onlineFilter.filterType,
+      );
+
+      // The unhealthy criterion is the one that opens incidents/alerts.
+      expect(offline.data.createIncidents).toBe(true);
+      expect(offline.data.createAlerts).toBe(true);
+      expect(online.data.createIncidents).toBe(false);
+      expect(online.data.createAlerts).toBe(false);
+    },
+  );
+});
+
+/*
+ * The three saturation templates exist to catch the CAUSE of the
+ * "under-resourced workload behind an autoscaler" failure — limits too
+ * low, HPA driven to its ceiling, cluster filled — rather than its
+ * downstream symptoms (node pressure, pending pods, NotReady), which the
+ * older node-side templates already cover. These assertions pin the
+ * properties that make them useful for that: they must be discoverable in
+ * the picker under a category, and severity must reflect that memory
+ * saturation ends in an OOMKill while CPU saturation only throttles.
+ */
+describe("KubernetesAlertTemplates - autoscaling & limit saturation", () => {
+  const SATURATION_TEMPLATES: Array<{
+    id: string;
+    category: string;
+    severity: string;
+  }> = [
+    {
+      id: "k8s-hpa-at-max-replicas",
+      category: "Workload",
+      severity: "Critical",
+    },
+    {
+      id: "k8s-pod-memory-limit-saturation",
+      category: "Workload",
+      // Crossing a memory limit is an immediate kill, not a slowdown.
+      severity: "Critical",
+    },
+    {
+      id: "k8s-pod-cpu-limit-saturation",
+      category: "Workload",
+      // CFS throttling degrades latency; it never kills the container.
+      severity: "Warning",
+    },
+  ];
+
+  test.each(SATURATION_TEMPLATES)(
+    "$id is registered as a $severity $category template",
+    (tc: { id: string; category: string; severity: string }) => {
+      const template: KubernetesAlertTemplate | undefined =
+        getKubernetesAlertTemplateById(tc.id);
+
+      expect(template).toBeDefined();
+      expect(template!.category).toBe(tc.category);
+      expect(template!.severity).toBe(tc.severity);
+      expect(template!.name.length).toBeGreaterThan(0);
+      expect(template!.description.length).toBeGreaterThan(0);
+    },
+  );
+
+  test("every template id is unique", () => {
+    const ids: Array<string> = getAllKubernetesAlertTemplates().map(
+      (t: KubernetesAlertTemplate) => {
+        return t.id;
+      },
+    );
+
+    expect(new Set(ids).size).toBe(ids.length);
+  });
 });