@intentius/chant-lexicon-k8s 0.1.0 → 0.1.5

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/lint/rules/rules.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { hardcodedNamespaceRule } from "./hardcoded-namespace";
 import { latestImageTagRule } from "./latest-image-tag";
 import { missingResourceLimitsRule } from "./missing-resource-limits";

package/src/lsp/completions.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";

package/src/lsp/hover.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";

package/src/package-cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env tsx
 /**
  * CLI entry point for Kubernetes lexicon packaging.
  */

package/src/plugin.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -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/plugin.ts

@@ -5,24 +5,26 @@
  * lint rules, and LSP/MCP integration for Kubernetes manifests.
  */
 
-import { createRequire } from "module";
 import type { LexiconPlugin, InitTemplateSet, ResourceMetadata } from "@intentius/chant/lexicon";
-const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
 import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { k8sSerializer } from "./serializer";
+import { hardcodedNamespaceRule } from "./lint/rules/hardcoded-namespace";
+import { latestImageTagRule } from "./lint/rules/latest-image-tag";
+import { missingResourceLimitsRule } from "./lint/rules/missing-resource-limits";
+import { k8sCompletions } from "./lsp/completions";
+import { k8sHover } from "./lsp/hover";
+import { K8sParser } from "./import/parser";
+import { K8sGenerator } from "./import/generator";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
   serializer: k8sSerializer,
 
   lintRules(): LintRule[] {
-    const { hardcodedNamespaceRule } = require("./lint/rules/hardcoded-namespace");
-    const { latestImageTagRule } = require("./lint/rules/latest-image-tag");
-    const { missingResourceLimitsRule } = require("./lint/rules/missing-resource-limits");
     return [hardcodedNamespaceRule, latestImageTagRule, missingResourceLimitsRule];
   },
 
@@ -204,22 +206,18 @@ export const service = new Service({
   },
 
   completionProvider(ctx: import("@intentius/chant/lsp/types").CompletionContext) {
-    const { k8sCompletions } = require("./lsp/completions");
     return k8sCompletions(ctx);
   },
 
   hoverProvider(ctx: import("@intentius/chant/lsp/types").HoverContext) {
-    const { k8sHover } = require("./lsp/hover");
     return k8sHover(ctx);
   },
 
   templateParser() {
-    const { K8sParser } = require("./import/parser");
     return new K8sParser();
   },
 
   templateGenerator() {
-    const { K8sGenerator } = require("./import/generator");
     return new K8sGenerator();
   },
 

package/src/serializer.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { k8sSerializer } from "./serializer";
 import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
 import {

package/src/serializer.ts

@@ -95,6 +95,8 @@ const API_GROUP_VERSIONS: Record<string, string> = {
   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-ray.md

@@ -0,0 +1,252 @@
+---
+skill: chant-k8s-ray
+description: KubeRay composites for distributed Ray clusters on Kubernetes — RayCluster, RayJob, RayService
+user-invocable: true
+---
+
+# KubeRay Composites
+
+Three composites cover the full KubeRay surface: persistent clusters, ephemeral batch jobs, and Ray Serve HTTP endpoints.
+
+## Prerequisites
+
+KubeRay operator must be installed before applying any Ray CRs:
+
+```bash
+kubectl apply -f https://github.com/ray-project/kuberay/releases/download/v1.3.0/kuberay-operator.yaml
+kubectl -n kuberay-operator wait deploy/kuberay-operator --for=condition=Available --timeout=120s
+```
+
+## When to use which composite
+
+| Composite | Use case |
+|---|---|
+| `RayCluster` | Interactive dev, long-lived infra, jobs submitted via CLI / Ray client |
+| `RayJob` | Training pipelines, batch jobs — spins up → runs → tears down |
+| `RayService` | Ray Serve HTTP endpoints with zero-downtime blue-green upgrades |
+
+---
+
+## RayCluster — persistent cluster
+
+```typescript
+import { RayCluster } from "@intentius/chant-lexicon-k8s";
+
+export const {
+  serviceAccount,
+  clusterRole,          // only when enableAutoscaler: true
+  clusterRoleBinding,   // only when enableAutoscaler: true
+  networkPolicy,
+  pdb,
+  pvc,                  // only when sharedStorage is set
+  dashboardService,     // only when exposeDashboard: true
+  rayCluster,
+} = RayCluster({
+  name: "ray",
+  namespace: "ray-system",
+  cluster: {
+    image: "us-central1-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+    head: {
+      resources: { cpu: "2", memory: "8Gi" },
+      shmSize: "4Gi",    // /dev/shm for PyTorch multi-process tensor sharing
+    },
+    workerGroups: [
+      {
+        groupName: "cpu",
+        replicas: 2,
+        minReplicas: 1,
+        maxReplicas: 8,
+        resources: { cpu: "2", memory: "4Gi" },
+        idleTimeoutSeconds: 60,
+      },
+      {
+        groupName: "gpu",
+        replicas: 0,
+        minReplicas: 0,
+        maxReplicas: 4,
+        resources: { cpu: "4", memory: "16Gi", gpu: 1 },
+        gpuTolerations: true,
+        idleTimeoutSeconds: 300,   // higher — amortize GPU init overhead
+      },
+    ],
+  },
+  sharedStorage: {
+    storageClass: "ray-filestore",
+    size: "1Ti",
+    mountPath: "/mnt/ray-data",   // mounted on all pods (head + all workers)
+  },
+  spilloverBucket: "ray-spill",         // GCS bucket for object store overflow
+  enableAutoscaler: true,
+  exposeDashboard: false,               // use kubectl port-forward 8265 in dev
+});
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `name` | `string` | Resource name prefix |
+| `namespace` | `string` | Kubernetes namespace |
+| `cluster.image` | `string` | Ray Docker image (pre-built recommended) |
+| `cluster.head.resources` | `ResourceSpec` | CPU/memory for the head pod |
+| `cluster.head.shmSize` | `string?` | Size of /dev/shm emptyDir (default: `"2Gi"`) |
+| `cluster.workerGroups` | `WorkerGroupSpec[]` | One entry per worker group |
+| `sharedStorage` | `object?` | PVC + volume mounts on all pods |
+| `spilloverBucket` | `string?` | GCS bucket for Ray object store spillover |
+| `enableAutoscaler` | `boolean?` | Emit ClusterRole/CRB for in-tree autoscaler |
+| `exposeDashboard` | `boolean?` | Emit LoadBalancer Service for port 8265 |
+| `labels` | `Record<string, string>?` | Extra labels on all resources |
+| `defaults` | `object?` | Deep-merge overrides onto any generated resource |
+
+---
+
+## RayJob — ephemeral cluster per batch job
+
+```typescript
+import { RayJob } from "@intentius/chant-lexicon-k8s";
+
+export const { serviceAccount, networkPolicy, pvc, rayJob } = RayJob({
+  name: "train-job",
+  namespace: "ray-system",
+  entrypoint: "python train.py --epochs 10",
+  cluster: {
+    image: "us-central1-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+    head: { resources: { cpu: "2", memory: "8Gi" } },
+    workerGroups: [
+      { groupName: "cpu", replicas: 4, resources: { cpu: "4", memory: "16Gi" } },
+    ],
+  },
+  shutdownAfterJobFinishes: true,    // default: true — cluster tears down after job
+  ttlSecondsAfterFinished: 300,      // default: 300 — delay before RayJob CR is deleted
+  runtimeEnvYAML: "pip:\n  - torch==2.3.0",
+  spilloverBucket: "ray-spill",
+});
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `entrypoint` | `string` | Shell command to run as the Ray job |
+| `runtimeEnvYAML` | `string?` | Ray runtime env YAML (pip packages, env vars, working_dir) |
+| `shutdownAfterJobFinishes` | `boolean?` | Tear down cluster after job completes (default: `true`) |
+| `ttlSecondsAfterFinished` | `number?` | Seconds before deleting the RayJob CR (default: `300`) |
+
+All other props (`cluster`, `sharedStorage`, `spilloverBucket`, `enableAutoscaler`) work the same as `RayCluster`.
+
+---
+
+## RayService — persistent Ray Serve endpoint
+
+```typescript
+import { RayService } from "@intentius/chant-lexicon-k8s";
+
+export const {
+  serviceAccount, networkPolicy, pdb, pvc,
+  serveService,   // LoadBalancer Service on port 8000
+  rayService,
+} = RayService({
+  name: "inference",
+  namespace: "ray-system",
+  serveConfigV2: `
+applications:
+  - name: classifier
+    import_path: app:deployment
+    route_prefix: /
+    deployments:
+      - name: Classifier
+        num_replicas: 2
+        ray_actor_options:
+          num_cpus: 1
+`,
+  cluster: {
+    image: "us-central1-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+    head: { resources: { cpu: "2", memory: "8Gi" } },
+    workerGroups: [
+      { groupName: "serve", replicas: 2, minReplicas: 1, maxReplicas: 8,
+        resources: { cpu: "4", memory: "16Gi" } },
+    ],
+  },
+  enableAutoscaler: true,
+});
+// Access: kubectl port-forward svc/inference-serve-svc 8000:8000
+```
+
+`serveService` is always emitted — a LoadBalancer Service on port 8000. To expose it via Ingress, add an annotation via `defaults.serveService`.
+
+---
+
+## Shared types
+
+```typescript
+interface ResourceSpec {
+  cpu: string;      // "2", "500m"
+  memory: string;   // "4Gi", "512Mi"
+  gpu?: number;     // adds nvidia.com/gpu resource limit
+}
+
+interface HeadGroupSpec {
+  resources: ResourceSpec;
+  shmSize?: string;                          // /dev/shm size, default "2Gi"
+  rayStartParams?: Record<string, string>;   // extra ray start flags
+  env?: Array<{ name: string; value: string }>;
+}
+
+interface WorkerGroupSpec {
+  groupName: string;
+  replicas: number;
+  minReplicas?: number;
+  maxReplicas?: number;
+  resources: ResourceSpec;
+  idleTimeoutSeconds?: number;               // default 60; use 300+ for GPU
+  gpuTolerations?: boolean;                  // tolerate nvidia.com/gpu taint
+  rayStartParams?: Record<string, string>;
+  env?: Array<{ name: string; value: string }>;
+}
+```
+
+---
+
+## Production defaults (encoded in composites)
+
+All three composites automatically apply these defaults — no manual configuration needed:
+
+| Default | Why |
+|---|---|
+| `preStop: ["ray", "stop"]` + `terminationGracePeriodSeconds: 120` | Graceful drain on pod eviction; in-flight tasks complete rather than fail |
+| `idleTimeoutSeconds: 60` (default) | Prevents stuck idle workers consuming resources |
+| `--num-cpus` derived from `resources.cpu` | Prevents autoscaler over-commit; without this Ray reads host CPU count, not container limit |
+| `RAY_object_spilling_config` env var | Routes large object spills to GCS; without this, large models or shuffled datasets OOM the head |
+| `shmSize` dshm emptyDir | PyTorch tensor sharing via /dev/shm; default 2Gi, set 4Gi+ for multi-process training |
+| `gpuTolerations: true` | Adds `nvidia.com/gpu: present: NoSchedule` toleration; required for GPU node pools with standard taints |
+
+---
+
+## NetworkPolicy strategy
+
+The composites emit a `NetworkPolicy` using `podSelector` only for intra-cluster rules — no IP CIDR blocks for Ray traffic. This avoids the GKE secondary IP range mismatch problem: GKE allocates pod CIDRs from secondary ranges that differ from declared subnet CIDRs, so CIDR-based NetworkPolicy rules silently fail when pods move nodes.
+
+GCS/HTTPS egress uses an ipBlock rule with RFC1918 ranges excluded — this allows Google APIs (storage.googleapis.com) while blocking internal lateral movement.
+
+Ports covered: 6379 (GCS object store), 8265 (dashboard), 10001–10002 (Ray client), 8080 (metrics), 32768–60999 (ephemeral gRPC).
+
+DNS egress (port 53 UDP/TCP) is always allowed — required for head service resolution.
+
+---
+
+## Troubleshooting
+
+**Workers not joining the cluster**
+Check the NetworkPolicy allows port 6379 from worker pods. The composite uses `ray.io/cluster-name: <name>` as the podSelector label — confirm this label is present on the pods (`kubectl get pods -n ray-system --show-labels`).
+
+**Autoscaler not scaling up**
+`enableAutoscaler: true` is required to emit the ClusterRole with pod CRUD permissions. Without it, the autoscaler controller cannot create or delete pods and will silently fail.
+
+**GPU workers not scheduling**
+Set `gpuTolerations: true` on the GPU worker group. Without the `nvidia.com/gpu: present: NoSchedule` toleration, pods won't schedule on GPU-tainted nodes. Also confirm the node pool taint key matches.
+
+**Head OOM on large workloads**
+Set `spilloverBucket` to a GCS bucket the head pod can write to. The head pod needs GCS access — use Workload Identity and bind the K8s ServiceAccount to a GCP SA with `roles/storage.objectAdmin` on the bucket. The composite injects `RAY_object_spilling_config` automatically when `spilloverBucket` is set.
+
+**Pre-built images vs runtimeEnv pip installs**
+Avoid `runtimeEnvYAML` pip installs in production. Each worker restart re-runs pip install, adding minutes to cold start at scale. Pre-build a Docker image with all dependencies baked in and push it to Artifact Registry.

package/src/spec/fetch.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { fetchK8sSchema, fetchSchemas, K8S_SCHEMA_VERSION } from "./fetch";
 
 describe("fetch", () => {

package/src/spec/parse.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import {
   gvkToTypeName,
   gvkToApiVersion,

package/src/validate-cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env tsx
 /**
  * CLI entry point for Kubernetes lexicon validation.
  */

package/src/validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "bun:test";
+import { describe, test, expect } from "vitest";
 import { validate } from "./validate";
 
 describe("validate", () => {