@intentius/chant-lexicon-k8s 0.0.24 → 0.1.4

package/src/generated/lexicon-k8s.json

@@ -46,6 +46,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "AutoscalerOptions": {
+    "resourceType": "K8s::Ray::RayCluster.autoscalerOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "BatchJob": {
     "resourceType": "K8s::Batch::Job",
     "kind": "resource",
@@ -439,6 +444,11 @@
     "apiVersion": "flowcontrol.apiserver.k8s.io/v1",
     "gvkKind": "FlowSchemaList"
   },
+  "GcsFaultToleranceOptions": {
+    "resourceType": "K8s::Ray::RayCluster.gcsFaultToleranceOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "HPA": {
     "resourceType": "K8s::Autoscaling::HorizontalPodAutoscaler",
     "kind": "resource",
@@ -456,6 +466,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "HeadGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.headGroupSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "HorizontalPodAutoscaler": {
     "resourceType": "K8s::Autoscaling::HorizontalPodAutoscaler",
     "kind": "resource",
@@ -942,6 +957,87 @@
       }
     }
   },
+  "RayCluster": {
+    "resourceType": "K8s::Ray::RayCluster",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayCluster"
+  },
+  "RayClusterConfig": {
+    "resourceType": "K8s::Ray::RayService.rayClusterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayClusterSpec": {
+    "resourceType": "K8s::Ray::RayJob.rayClusterSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_AutoscalerOptions": {
+    "resourceType": "K8s::Ray::RayCluster.autoscalerOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_GcsFaultToleranceOptions": {
+    "resourceType": "K8s::Ray::RayCluster.gcsFaultToleranceOptions",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_HeadGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.headGroupSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayCluster_WorkerGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.workerGroupSpecs",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob": {
+    "resourceType": "K8s::Ray::RayJob",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayJob"
+  },
+  "RayJob_RayClusterSpec": {
+    "resourceType": "K8s::Ray::RayJob.rayClusterSpec",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob_SubmitterConfig": {
+    "resourceType": "K8s::Ray::RayJob.submitterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayJob_SubmitterPodTemplate": {
+    "resourceType": "K8s::Ray::RayJob.submitterPodTemplate",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService": {
+    "resourceType": "K8s::Ray::RayService",
+    "kind": "resource",
+    "lexicon": "k8s",
+    "apiVersion": "ray.io/v1",
+    "gvkKind": "RayService"
+  },
+  "RayService_RayClusterConfig": {
+    "resourceType": "K8s::Ray::RayService.rayClusterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService_ServeService": {
+    "resourceType": "K8s::Ray::RayService.serveService",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "RayService_UpgradeStrategy": {
+    "resourceType": "K8s::Ray::RayService.upgradeStrategy",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ReplicaSet": {
     "resourceType": "K8s::Apps::ReplicaSet",
     "kind": "resource",
@@ -1164,6 +1260,11 @@
     "apiVersion": "authorization.k8s.io/v1",
     "gvkKind": "SelfSubjectRulesReview"
   },
+  "ServeService": {
+    "resourceType": "K8s::Ray::RayService.serveService",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Service": {
     "resourceType": "K8s::Core::Service",
     "kind": "resource",
@@ -1281,6 +1382,16 @@
     "apiVersion": "authorization.k8s.io/v1",
     "gvkKind": "SubjectAccessReview"
   },
+  "SubmitterConfig": {
+    "resourceType": "K8s::Ray::RayJob.submitterConfig",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
+  "SubmitterPodTemplate": {
+    "resourceType": "K8s::Ray::RayJob.submitterPodTemplate",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "TCPSocketAction": {
     "resourceType": "K8s::Core::TCPSocketAction",
     "kind": "property",
@@ -1323,6 +1434,11 @@
       }
     }
   },
+  "UpgradeStrategy": {
+    "resourceType": "K8s::Ray::RayService.upgradeStrategy",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ValidatingAdmissionPolicy": {
     "resourceType": "K8s::Admissionregistration::ValidatingAdmissionPolicy",
     "kind": "resource",
@@ -1409,5 +1525,10 @@
     "lexicon": "k8s",
     "apiVersion": "v1",
     "gvkKind": "WatchEvent"
+  },
+  "WorkerGroupSpec": {
+    "resourceType": "K8s::Ray::RayCluster.workerGroupSpecs",
+    "kind": "property",
+    "lexicon": "k8s"
   }
 }

package/src/index.ts

@@ -22,6 +22,7 @@ export {
   IrsaServiceAccount, AlbIngress, EbsStorageClass, EfsStorageClass, FluentBitAgent, ExternalDnsAgent, AdotCollector,
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
   GceIngress, CockroachDbCluster,
+  RayCluster, RayJob, RayService,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
   GkeFluentBitAgent, GkeOtelCollector, GkeExternalDnsAgent, AksExternalDnsAgent,
@@ -44,6 +45,9 @@ export type {
   GkeGatewayProps, GkeGatewayResult,
   ConfigConnectorContextProps, ConfigConnectorContextResult,
   GceIngressProps, GceIngressResult, CockroachDbClusterProps, CockroachDbClusterResult,
+  RayClusterProps, RayClusterResult, RayClusterSpec, ResourceSpec, HeadGroupSpec, WorkerGroupSpec,
+  RayJobProps, RayJobResult,
+  RayServiceProps, RayServiceResult,
   AgicIngressProps, AgicIngressResult,
   AzureDiskStorageClassProps, AzureDiskStorageClassResult,
   AzureFileStorageClassProps, AzureFileStorageClassResult,

package/src/lint/post-synth/k8s-helpers.ts

@@ -147,3 +147,42 @@ export const WORKLOAD_KINDS = new Set([
   "Job",
   "CronJob",
 ]);
+
+/**
+ * Parse a Kubernetes memory string to bytes.
+ *
+ * Handles binary suffixes (Ki, Mi, Gi, Ti) and SI suffixes (K, M, G, T).
+ * Returns NaN for unrecognised strings — callers should skip checks on NaN.
+ *
+ * @example
+ * parseMemoryBytes("4Gi")  // 4294967296
+ * parseMemoryBytes("512Mi") // 536870912
+ * parseMemoryBytes("2048") // 2048
+ */
+export function parseMemoryBytes(s: string): number {
+  const m = /^([0-9]+(?:\.[0-9]+)?)(Ki|Mi|Gi|Ti|K|M|G|T)?$/.exec(s.trim());
+  if (!m) return NaN;
+  const n = parseFloat(m[1]);
+  const multipliers: Record<string, number> = {
+    Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4,
+    K: 1000, M: 1000 ** 2, G: 1000 ** 3, T: 1000 ** 4,
+  };
+  return n * (multipliers[m[2] ?? ""] ?? 1);
+}
+
+/**
+ * Extract the Ray version from an image tag.
+ *
+ * Looks for a semver-style version prefix in the image tag:
+ *   "rayproject/ray:2.40.0"          → "2.40.0"
+ *   "rayproject/ray:2.40.0-py310"    → "2.40.0"
+ *   "us-docker.pkg.dev/.../ray:2.9.3-gpu" → "2.9.3"
+ *   "rayproject/ray:latest"          → undefined
+ *
+ * Returns undefined when no version can be found.
+ */
+export function extractRayVersion(image: string): string | undefined {
+  const tag = image.includes(":") ? image.split(":").pop()! : image;
+  const m = /^([0-9]+\.[0-9]+\.[0-9]+)/.exec(tag);
+  return m ? m[1] : undefined;
+}

package/src/lint/post-synth/post-synth.test.ts

@@ -25,6 +25,9 @@ import { wk8303 } from "./wk8303";
 import { wk8304 } from "./wk8304";
 import { wk8305 } from "./wk8305";
 import { wk8306 } from "./wk8306";
+import { wk8401 } from "./wk8401";
+import { wk8402 } from "./wk8402";
+import { wk8403 } from "./wk8403";
 
 function makeCtx(yaml: string): PostSynthContext {
   return {
@@ -1328,3 +1331,148 @@ describe("WK8306: Container command starts with flag", () => {
     expect(diags.length).toBe(0);
   });
 });
+
+// ── WK8401: shmSize exceeds memory limit ────────────────────────────────────
+
+function makeRayCluster(overrides: {
+  shmSizeLimit?: string;
+  memoryLimit?: string;
+  workerShmSizeLimit?: string;
+  workerMemoryLimit?: string;
+  rayVersion?: string;
+  headImage?: string;
+}) {
+  const headImage = overrides.headImage ?? "rayproject/ray:2.40.0-py310-cpu";
+  return JSON.stringify({
+    apiVersion: "ray.io/v1alpha1",
+    kind: "RayCluster",
+    metadata: { name: "ray" },
+    spec: {
+      ...(overrides.rayVersion !== undefined && { rayVersion: overrides.rayVersion }),
+      headGroupSpec: {
+        template: {
+          spec: {
+            volumes: [{ name: "dshm", emptyDir: { medium: "Memory", ...(overrides.shmSizeLimit !== undefined && { sizeLimit: overrides.shmSizeLimit }) } }],
+            containers: [{ name: "ray-head", image: headImage, resources: { limits: { memory: overrides.memoryLimit ?? "8Gi" } } }],
+          },
+        },
+      },
+      workerGroupSpecs: [
+        {
+          groupName: "cpu",
+          template: {
+            spec: {
+              volumes: [{ name: "dshm", emptyDir: { medium: "Memory", ...(overrides.workerShmSizeLimit !== undefined && { sizeLimit: overrides.workerShmSizeLimit }) } }],
+              containers: [{ name: "ray-worker", image: headImage, resources: { limits: { memory: overrides.workerMemoryLimit ?? "4Gi" } } }],
+            },
+          },
+        },
+      ],
+    },
+  });
+}
+
+describe("WK8401: shmSize exceeds memory limit", () => {
+  test("passes when shmSize equals memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "8Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("passes when shmSize is less than memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "2Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("errors when head shmSize exceeds memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: "16Gi", memoryLimit: "8Gi" }));
+    const diags = wk8401.check(ctx);
+    const errors = diags.filter((d) => d.checkId === "WK8401" && d.severity === "error");
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].message).toContain("head");
+    expect(errors[0].message).toContain("16Gi");
+  });
+
+  test("errors when worker shmSize exceeds memory limit", () => {
+    const ctx = makeCtx(makeRayCluster({ workerShmSizeLimit: "8Gi", workerMemoryLimit: "4Gi" }));
+    const diags = wk8401.check(ctx);
+    const errors = diags.filter((d) => d.checkId === "WK8401" && d.severity === "error");
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].message).toContain("worker");
+  });
+
+  test("skips check when no sizeLimit set on emptyDir", () => {
+    const ctx = makeCtx(makeRayCluster({ shmSizeLimit: undefined }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+
+  test("ignores non-RayCluster manifests", () => {
+    const ctx = makeCtx(JSON.stringify({
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { name: "app" },
+      spec: { template: { spec: { volumes: [{ name: "dshm", emptyDir: { medium: "Memory", sizeLimit: "16Gi" } }], containers: [{ name: "app", image: "app:1.0", resources: { limits: { memory: "4Gi" } } }] } } },
+    }));
+    const diags = wk8401.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8401").length).toBe(0);
+  });
+});
+
+// ── WK8402: RayCluster missing spec.rayVersion ───────────────────────────────
+
+describe("WK8402: RayCluster missing spec.rayVersion", () => {
+  test("passes when rayVersion is set", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0" }));
+    const diags = wk8402.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8402").length).toBe(0);
+  });
+
+  test("warns when rayVersion is absent", () => {
+    const ctx = makeCtx(makeRayCluster({}));
+    const diags = wk8402.check(ctx);
+    const warns = diags.filter((d) => d.checkId === "WK8402");
+    expect(warns.length).toBe(1);
+    expect(warns[0].severity).toBe("warning");
+    expect(warns[0].message).toContain("latest");
+  });
+
+  test("ignores non-RayCluster manifests", () => {
+    const ctx = makeCtx(JSON.stringify({ apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "app" }, spec: {} }));
+    const diags = wk8402.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8402").length).toBe(0);
+  });
+});
+
+// ── WK8403: spec.rayVersion / image tag mismatch ─────────────────────────────
+
+describe("WK8403: spec.rayVersion does not match image tag", () => {
+  test("passes when versions match", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0", headImage: "rayproject/ray:2.40.0-py310-cpu" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+
+  test("warns when rayVersion does not match image tag", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.39.0", headImage: "rayproject/ray:2.40.0-py310-cpu" }));
+    const diags = wk8403.check(ctx);
+    const warns = diags.filter((d) => d.checkId === "WK8403");
+    expect(warns.length).toBe(1);
+    expect(warns[0].severity).toBe("warning");
+    expect(warns[0].message).toContain("2.39.0");
+    expect(warns[0].message).toContain("2.40.0");
+  });
+
+  test("skips when rayVersion is absent (WK8402 covers that)", () => {
+    const ctx = makeCtx(makeRayCluster({ headImage: "rayproject/ray:2.40.0" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+
+  test("skips when image tag has no parseable version", () => {
+    const ctx = makeCtx(makeRayCluster({ rayVersion: "2.40.0", headImage: "rayproject/ray:latest" }));
+    const diags = wk8403.check(ctx);
+    expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
+  });
+});

package/src/lint/post-synth/wk8401.ts

@@ -0,0 +1,98 @@
+/**
+ * WK8401: shmSize exceeds container memory limit
+ *
+ * A RayCluster pod uses an emptyDir volume with medium: Memory for /dev/shm.
+ * Kubernetes counts that memory against the container's memory limit — if the
+ * sizeLimit exceeds the container's memory limit the pod will never schedule
+ * (Kubelet rejects it with "Invalid value … must be less than or equal to memory limit").
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, parseMemoryBytes } from "./k8s-helpers";
+
+export const wk8401: PostSynthCheck = {
+  id: "WK8401",
+  description: "shmSize must not exceed the container memory limit — pod will not schedule if it does",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "RayCluster") continue;
+
+        const clusterName = manifest.metadata?.name ?? "RayCluster";
+        const spec = manifest.spec as Record<string, unknown> | undefined;
+        if (!spec) continue;
+
+        const groups: Array<{ label: string; templateSpec: Record<string, unknown> }> = [];
+
+        // Head group
+        const headGroupSpec = spec.headGroupSpec as Record<string, unknown> | undefined;
+        if (headGroupSpec) {
+          const tmpl = headGroupSpec.template as Record<string, unknown> | undefined;
+          const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+          if (podSpec) groups.push({ label: "head", templateSpec: podSpec });
+        }
+
+        // Worker groups
+        const workerGroupSpecs = spec.workerGroupSpecs as Array<Record<string, unknown>> | undefined;
+        if (Array.isArray(workerGroupSpecs)) {
+          for (const wg of workerGroupSpecs) {
+            const name = (wg.groupName as string | undefined) ?? "worker";
+            const tmpl = wg.template as Record<string, unknown> | undefined;
+            const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+            if (podSpec) groups.push({ label: `worker "${name}"`, templateSpec: podSpec });
+          }
+        }
+
+        for (const { label, templateSpec } of groups) {
+          // Find the emptyDir Memory volume (dshm)
+          const volumes = templateSpec.volumes as Array<Record<string, unknown>> | undefined;
+          if (!Array.isArray(volumes)) continue;
+
+          for (const vol of volumes) {
+            const emptyDir = vol.emptyDir as Record<string, unknown> | undefined;
+            if (!emptyDir || emptyDir.medium !== "Memory") continue;
+
+            const sizeLimit = emptyDir.sizeLimit as string | undefined;
+            if (!sizeLimit) continue;
+
+            const shmBytes = parseMemoryBytes(sizeLimit);
+            if (isNaN(shmBytes)) continue;
+
+            // Find memory limit from the first container that mounts this volume
+            const containers = templateSpec.containers as Array<Record<string, unknown>> | undefined;
+            if (!Array.isArray(containers)) continue;
+
+            for (const container of containers) {
+              const resources = container.resources as Record<string, unknown> | undefined;
+              const limits = resources?.limits as Record<string, unknown> | undefined;
+              const memLimit = limits?.memory as string | undefined;
+              if (!memLimit) continue;
+
+              const memBytes = parseMemoryBytes(memLimit);
+              if (isNaN(memBytes)) continue;
+
+              if (shmBytes > memBytes) {
+                diagnostics.push({
+                  checkId: "WK8401",
+                  severity: "error",
+                  message: `RayCluster "${clusterName}" ${label}: shmSize "${sizeLimit}" exceeds memory limit "${memLimit}" — pod will not schedule`,
+                  entity: clusterName,
+                  lexicon: "k8s",
+                });
+              }
+              break; // Only check the first container per group
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wk8402.ts

@@ -0,0 +1,43 @@
+/**
+ * WK8402: RayCluster missing spec.rayVersion
+ *
+ * KubeRay uses spec.rayVersion to select the Ray autoscaler sidecar image.
+ * Without it, KubeRay defaults to the "latest" tag — autoscaler and Ray head
+ * may run mismatched versions, leading to silent protocol failures.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8402: PostSynthCheck = {
+  id: "WK8402",
+  description: "RayCluster should set spec.rayVersion so KubeRay selects the correct autoscaler image",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "RayCluster") continue;
+
+        const name = manifest.metadata?.name ?? "RayCluster";
+        const rayVersion = (manifest.spec as Record<string, unknown> | undefined)?.rayVersion;
+
+        if (!rayVersion) {
+          diagnostics.push({
+            checkId: "WK8402",
+            severity: "warning",
+            message: `RayCluster "${name}" is missing spec.rayVersion — KubeRay autoscaler will pull the "latest" image tag`,
+            entity: name,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wk8403.ts

@@ -0,0 +1,60 @@
+/**
+ * WK8403: spec.rayVersion does not match head image tag
+ *
+ * When spec.rayVersion is set but doesn't match the version in the head
+ * container image tag, the KubeRay autoscaler sidecar will run a different
+ * Ray version than the cluster. This can cause gRPC compatibility failures.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractRayVersion } from "./k8s-helpers";
+
+export const wk8403: PostSynthCheck = {
+  id: "WK8403",
+  description: "spec.rayVersion should match the Ray version in the head container image tag",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "RayCluster") continue;
+
+        const clusterName = manifest.metadata?.name ?? "RayCluster";
+        const spec = manifest.spec as Record<string, unknown> | undefined;
+        if (!spec) continue;
+
+        const rayVersion = spec.rayVersion as string | undefined;
+        if (!rayVersion) continue; // WK8402 covers the missing case
+
+        // Extract version from head container image
+        const headGroupSpec = spec.headGroupSpec as Record<string, unknown> | undefined;
+        const tmpl = headGroupSpec?.template as Record<string, unknown> | undefined;
+        const podSpec = tmpl?.spec as Record<string, unknown> | undefined;
+        const containers = podSpec?.containers as Array<Record<string, unknown>> | undefined;
+        if (!Array.isArray(containers) || containers.length === 0) continue;
+
+        const image = containers[0].image as string | undefined;
+        if (!image) continue;
+
+        const imageVersion = extractRayVersion(image);
+        if (!imageVersion) continue; // Can't determine version from tag
+
+        if (imageVersion !== rayVersion) {
+          diagnostics.push({
+            checkId: "WK8403",
+            severity: "warning",
+            message: `RayCluster "${clusterName}": spec.rayVersion "${rayVersion}" does not match head image tag "${imageVersion}" — autoscaler may run a mismatched Ray version`,
+            entity: clusterName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/plugin.test.ts

@@ -30,10 +30,10 @@ describe("k8sPlugin", () => {
     expect(rules.some((r) => r.id === "WK8001")).toBe(true);
   });
 
-  test("postSynthChecks() returns array of 22 checks", () => {
+  test("postSynthChecks() returns array of post-synth checks", () => {
     const checks = k8sPlugin.postSynthChecks!();
     expect(Array.isArray(checks)).toBe(true);
-    expect(checks.length).toBe(23);
+    expect(checks.length).toBe(26);
   });
 
   test("intrinsics() returns empty array", () => {

package/src/serializer.ts

@@ -91,6 +91,12 @@ const API_GROUP_VERSIONS: Record<string, string> = {
   GKE: "cloud.google.com/v1",
   NetworkingGKE: "networking.gke.io/v1",
   NetworkingGKEBeta: "networking.gke.io/v1beta1",
+  // Common Kubernetes operator CRDs
+  CertManager: "cert-manager.io/v1",
+  ExternalSecrets: "external-secrets.io/v1",
+  Monitoring: "monitoring.coreos.com/v1",
+  // KubeRay operator CRDs
+  Ray: "ray.io/v1",
 };
 
 function deriveGVKFromType(entityType: string): { apiVersion: string; kind: string } | null {

package/src/skills/chant-k8s-gke.md

@@ -206,7 +206,7 @@ import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";
 const { context } = ConfigConnectorContext({
   googleServiceAccountEmail: "cc-sa@my-project.iam.gserviceaccount.com",
   namespace: "config-connector",
-  stateIntoSpec: "absent",
+  stateIntoSpec: "Absent",
 });
 ```