@intentius/chant-lexicon-k8s 0.45.0 → 0.49.0

package/src/composites/vllm-serving-runtime.test.ts

@@ -0,0 +1,167 @@
+import { describe, test, expect } from "vitest";
+import { emitYAML } from "@intentius/chant/yaml";
+import { VllmServingRuntime } from "./vllm-serving-runtime";
+
+/** Helper to access props on a Declarable member. */
+function p(member: unknown): Record<string, unknown> {
+  return (member as any).props;
+}
+
+describe("VllmServingRuntime", () => {
+  test("emits a namespaced ServingRuntime by default", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+    });
+    const props = p(result.servingRuntime);
+    expect(props.metadata).toMatchObject({ name: "vllm-runtime", namespace: "models" });
+  });
+
+  test("emits a ClusterServingRuntime when clusterScoped is true", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      clusterScoped: true,
+      image: "vllm/vllm-openai:v0.7.0",
+    });
+    const props = p(result.servingRuntime);
+    expect(props.metadata).toMatchObject({ name: "vllm-runtime" });
+    expect((props.metadata as any).namespace).toBeUndefined();
+  });
+
+  test("throws when namespace is missing and clusterScoped is false", () => {
+    expect(() =>
+      VllmServingRuntime({
+        name: "vllm-runtime",
+        image: "vllm/vllm-openai:v0.7.0",
+      } as any),
+    ).toThrow(/namespace is required/);
+  });
+
+  test("registers the vllm supportedModelFormats entry", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.supportedModelFormats).toEqual([{ name: "vllm", autoSelect: true }]);
+  });
+
+  test("supports overriding the model format", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      modelFormat: { name: "vllm", version: "1", priority: 1 },
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.supportedModelFormats).toEqual([{ name: "vllm", version: "1", priority: 1 }]);
+  });
+
+  // ── Golden test: vLLM args are spec-true (real `vllm serve` flag names) ──
+
+  test("wires typed vLLM props to real container args, in flag order", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      tensorParallelSize: 2,
+      maxModelLen: 8192,
+      dtype: "bfloat16",
+      quantization: "awq",
+      gpuMemoryUtilization: 0.9,
+      maxNumSeqs: 256,
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    const container = spec.containers[0];
+    expect(container.name).toBe("kserve-container");
+    expect(container.command).toEqual(["vllm", "serve", "/mnt/models"]);
+    expect(container.args).toEqual([
+      "--tensor-parallel-size", "2",
+      "--max-model-len", "8192",
+      "--dtype", "bfloat16",
+      "--quantization", "awq",
+      "--gpu-memory-utilization", "0.9",
+      "--max-num-seqs", "256",
+    ]);
+  });
+
+  test("containerArgs escape hatch appends after typed flags", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      tensorParallelSize: 1,
+      containerArgs: ["--enable-prefix-caching", "--disable-log-requests"],
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.containers[0].args).toEqual([
+      "--tensor-parallel-size", "1",
+      "--enable-prefix-caching",
+      "--disable-log-requests",
+    ]);
+  });
+
+  test("omits unset vLLM flags rather than emitting empty/undefined args", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.containers[0].args).toEqual([]);
+  });
+
+  test("GPU count maps to nvidia.com/gpu in resource requests and limits", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      resources: { cpu: "8", memory: "32Gi", gpu: 2 },
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    const resources = spec.containers[0].resources;
+    expect(resources).toEqual({
+      requests: { cpu: "8", memory: "32Gi", "nvidia.com/gpu": "2" },
+      limits: { cpu: "8", memory: "32Gi", "nvidia.com/gpu": "2" },
+    });
+  });
+
+  test("resources is omitted entirely when not provided", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.containers[0].resources).toBeUndefined();
+  });
+
+  test("serializes to valid YAML", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      tensorParallelSize: 2,
+      resources: { cpu: "8", memory: "32Gi", gpu: 2 },
+    });
+    const yaml = emitYAML(p(result.servingRuntime), 0);
+    expect(yaml).toContain("vllm-runtime");
+    expect(yaml).toContain("tensor-parallel-size");
+    expect(yaml).not.toContain("[object Object]");
+  });
+
+  test("defaults.servingRuntime passthrough merges into the resource", () => {
+    const result = VllmServingRuntime({
+      name: "vllm-runtime",
+      namespace: "models",
+      image: "vllm/vllm-openai:v0.7.0",
+      defaults: {
+        servingRuntime: { spec: { replicas: 3 } },
+      },
+    });
+    const spec = p(result.servingRuntime).spec as any;
+    expect(spec.replicas).toBe(3);
+  });
+});

package/src/composites/vllm-serving-runtime.ts

@@ -0,0 +1,196 @@
+/**
+ * VllmServingRuntime composite — KServe ServingRuntime/ClusterServingRuntime
+ * running vLLM.
+ *
+ * Design rule (chant #982, #984): spec-true, not chant-flavored. Props mirror
+ * vLLM's real `vllm serve` CLI args — no generic runtime abstraction. KServe's
+ * ServingRuntime CRD is the pluggability seam; this composite types vLLM
+ * faithfully on top of it, it doesn't invent a wrapper around it.
+ *
+ * The model itself is not a prop here — an InferenceService (chant #985)
+ * references this runtime and supplies storageUri, which KServe mounts at
+ * /mnt/models inside the pod. That's the path this composite passes to
+ * `vllm serve`.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  ServingRuntime,
+  ClusterServingRuntime,
+} from "../generated";
+
+/** Container resource spec. GPU count maps to nvidia.com/gpu requests/limits. */
+export interface VllmResourceSpec {
+  /** CPU request/limit (e.g. "4", "500m"). */
+  cpu?: string;
+  /** Memory request/limit (e.g. "16Gi"). */
+  memory?: string;
+  /** GPU count — adds nvidia.com/gpu to resource requests and limits. */
+  gpu?: number;
+}
+
+export interface VllmServingRuntimeProps {
+  /** ServingRuntime/ClusterServingRuntime name. */
+  name: string;
+  /** Namespace — required unless clusterScoped is true. */
+  namespace?: string;
+  /**
+   * Emit a cluster-scoped ClusterServingRuntime instead of a namespaced
+   * ServingRuntime. Default false.
+   */
+  clusterScoped?: boolean;
+  /** vLLM container image (e.g. "vllm/vllm-openai:v0.7.0"). */
+  image: string;
+
+  // ── vLLM args (spec-true to `vllm serve --help`) ──────────────────────
+  /** --tensor-parallel-size */
+  tensorParallelSize?: number;
+  /** --max-model-len */
+  maxModelLen?: number;
+  /** --dtype */
+  dtype?: "auto" | "half" | "float16" | "bfloat16" | "float" | "float32";
+  /** --quantization (e.g. "awq", "gptq", "fp8") */
+  quantization?: string;
+  /** --gpu-memory-utilization (0.0-1.0) */
+  gpuMemoryUtilization?: number;
+  /** --max-num-seqs */
+  maxNumSeqs?: number;
+
+  /** Container resources. gpu maps to nvidia.com/gpu. */
+  resources?: VllmResourceSpec;
+  /**
+   * Additional raw args appended after the typed vLLM flags — escape hatch
+   * for anything not yet modeled as a typed prop.
+   */
+  containerArgs?: string[];
+  /**
+   * supportedModelFormats entry registered on the runtime. Default
+   * `{ name: "vllm", autoSelect: true }`.
+   */
+  modelFormat?: { name: string; version?: string; autoSelect?: boolean; priority?: number };
+  /** Additional labels applied to the resource. */
+  labels?: Record<string, string>;
+  /** Per-member defaults for fine-grained overrides via mergeDefaults. */
+  defaults?: {
+    servingRuntime?: Partial<Record<string, unknown>>;
+  };
+}
+
+export interface VllmServingRuntimeResult {
+  servingRuntime: InstanceType<typeof ServingRuntime> | InstanceType<typeof ClusterServingRuntime>;
+}
+
+/** Build the container args list, in `vllm serve --help` flag order. */
+function buildVllmArgs(props: VllmServingRuntimeProps): string[] {
+  const {
+    tensorParallelSize,
+    maxModelLen,
+    dtype,
+    quantization,
+    gpuMemoryUtilization,
+    maxNumSeqs,
+    containerArgs = [],
+  } = props;
+
+  const args: string[] = [];
+  if (tensorParallelSize !== undefined) args.push("--tensor-parallel-size", String(tensorParallelSize));
+  if (maxModelLen !== undefined) args.push("--max-model-len", String(maxModelLen));
+  if (dtype !== undefined) args.push("--dtype", dtype);
+  if (quantization !== undefined) args.push("--quantization", quantization);
+  if (gpuMemoryUtilization !== undefined) args.push("--gpu-memory-utilization", String(gpuMemoryUtilization));
+  if (maxNumSeqs !== undefined) args.push("--max-num-seqs", String(maxNumSeqs));
+  args.push(...containerArgs);
+  return args;
+}
+
+/** Build container resource requests/limits. GPU count maps to nvidia.com/gpu. */
+function buildResources(spec?: VllmResourceSpec): Record<string, unknown> | undefined {
+  if (!spec) return undefined;
+  const base: Record<string, unknown> = {};
+  if (spec.cpu) base.cpu = spec.cpu;
+  if (spec.memory) base.memory = spec.memory;
+  if (spec.gpu) base["nvidia.com/gpu"] = String(spec.gpu);
+  if (Object.keys(base).length === 0) return undefined;
+  return { requests: { ...base }, limits: { ...base } };
+}
+
+/**
+ * Create a VllmServingRuntime composite — a KServe ServingRuntime (or, with
+ * `clusterScoped: true`, a ClusterServingRuntime) that runs vLLM's OpenAI-
+ * compatible server, with vLLM's own flags surfaced as typed props.
+ *
+ * @example
+ * ```ts
+ * import { VllmServingRuntime } from "@intentius/chant-lexicon-k8s";
+ *
+ * const runtime = VllmServingRuntime({
+ *   name: "vllm-runtime",
+ *   namespace: "models",
+ *   image: "vllm/vllm-openai:v0.7.0",
+ *   tensorParallelSize: 2,
+ *   maxModelLen: 8192,
+ *   dtype: "bfloat16",
+ *   gpuMemoryUtilization: 0.9,
+ *   resources: { cpu: "8", memory: "32Gi", gpu: 2 },
+ * });
+ * ```
+ */
+export const VllmServingRuntime = Composite((props: VllmServingRuntimeProps) => {
+  const {
+    name,
+    namespace,
+    clusterScoped = false,
+    image,
+    modelFormat = { name: "vllm", autoSelect: true },
+    labels: extraLabels = {},
+    defaults: defs,
+  } = props;
+
+  if (!clusterScoped && !namespace) {
+    throw new Error(
+      `VllmServingRuntime("${name}"): namespace is required unless clusterScoped is true.`,
+    );
+  }
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    "app.kubernetes.io/component": "vllm-serving-runtime",
+    ...extraLabels,
+  };
+
+  const resources = buildResources(props.resources);
+
+  const spec: Record<string, unknown> = {
+    supportedModelFormats: [modelFormat],
+    containers: [
+      {
+        name: "kserve-container",
+        image,
+        command: ["vllm", "serve", "/mnt/models"],
+        args: buildVllmArgs(props),
+        ports: [{ containerPort: 8000, protocol: "TCP", name: "http1" }],
+        ...(resources && { resources }),
+      },
+    ],
+  };
+
+  const servingRuntime = clusterScoped
+    ? new ClusterServingRuntime(mergeDefaults({
+        metadata: {
+          name,
+          labels: commonLabels,
+        },
+        spec,
+      }, defs?.servingRuntime))
+    : new ServingRuntime(mergeDefaults({
+        metadata: {
+          name,
+          namespace,
+          labels: commonLabels,
+        },
+        spec,
+      }, defs?.servingRuntime));
+
+  return { servingRuntime };
+}, "VllmServingRuntime");

package/src/crd/cnpg.test.ts

@@ -9,7 +9,12 @@
  */
 
 import { describe, test, expect } from "vitest";
-import { Cluster, ScheduledBackup, ObjectStore } from "../generated";
+// chant #10 — CAPI's own `Cluster` kind (K8s::CAPI::Cluster) collides with
+// CNPG's `Cluster` (K8s::Cnpg::Cluster) on the bare class name, so codegen's
+// disambiguation now exports this one as `CnpgCluster`. The generated
+// resource type name (K8s::Cnpg::Cluster) and the serialized `kind: Cluster`
+// are unaffected — only the TS identifier changed.
+import { CnpgCluster, ScheduledBackup, ObjectStore } from "../generated";
 import { k8sSerializer } from "../serializer";
 import { parseYAML } from "@intentius/chant/yaml";
 
@@ -20,7 +25,7 @@ function synth(logicalName: string, resource: unknown): any {
 }
 
 describe("CNPG Cluster", () => {
-  const cluster = new Cluster({
+  const cluster = new CnpgCluster({
     metadata: { name: "fountain-pg", namespace: "fountain", labels: { app: "fountain" } },
     spec: {
       instances: 1,
@@ -166,7 +171,7 @@ describe("barman-cloud ObjectStore", () => {
     // not exist.
     const clusterDoc = synth(
       "fountainPg",
-      new Cluster({
+      new CnpgCluster({
         metadata: { name: "fountain-pg", namespace: "fountain" },
         spec: {
           instances: 1,

package/src/crd/crd-sources.ts

@@ -311,6 +311,172 @@ const K3S_API_VERSION = "v0.1.4"; // vendored by k3s v1.36.3+k3s1
 const K3S_HELM_CONTROLLER_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/helm-controller/${K3S_HELM_CONTROLLER_VERSION}/pkg/crds/yaml/generated`;
 const K3S_API_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/api/${K3S_API_VERSION}/pkg/crds/yaml/generated`;
 
+/**
+ * KServe CRDs — serving.kserve.io
+ *
+ * The model-serving control plane chant #982 builds vLLM composites on top
+ * of. Produces (the `serving.kserve.io` group maps to the `KServe` namespace
+ * — see GROUP_NAMESPACE_OVERRIDES in group-namespace.ts; the first-segment
+ * rule would otherwise give `K8s::Serving::*`):
+ *   K8s::KServe::InferenceService       → serving.kserve.io/v1beta1, kind: InferenceService
+ *   K8s::KServe::ServingRuntime         → serving.kserve.io/v1alpha1, kind: ServingRuntime
+ *   K8s::KServe::ClusterServingRuntime  → serving.kserve.io/v1alpha1, kind: ClusterServingRuntime
+ *
+ * Sourced from `config/crd/full`, not `config/crd/minimal` — `full` is what
+ * the release's own kustomization.yaml (and `kubectl apply -k config/crd`)
+ * actually installs; `minimal` is a stripped, non-validating variant with no
+ * OpenAPI schema to speak of. `full`'s InferenceService schema is the entire
+ * spec-true predictor/transformer/explainer union (~1MB of YAML) — see
+ * schemaPatches in codegen/patches.ts if generation trips on its recursion
+ * depth.
+ *
+ * Pinned to the last patch of the 0.15 line rather than latest (0.20.0,
+ * weeks old at pin time) — a release that's had over a year to settle,
+ * matching the CNPG precedent above of tracking what a real operator runs
+ * rather than the newest tag.
+ *
+ * Operator install: kubectl apply --server-side -k
+ *   "github.com/kserve/kserve/config/default?ref=v0.15.2"
+ */
+const KSERVE_VERSION = "v0.15.2";
+const KSERVE_CRD_BASE = `https://raw.githubusercontent.com/kserve/kserve/${KSERVE_VERSION}/config/crd/full`;
+
+/**
+ * Cluster API (CAPI) core CRDs — cluster.x-k8s.io/v1beta2
+ *
+ * The provider-agnostic cluster-lifecycle surface CAPA, CAAPH, and every
+ * other CAPI provider build on. Only the two kinds a project actually
+ * declares are taken; `ClusterClass`, `MachineDeployment`, `MachineSet`,
+ * `MachineHealthCheck`, `MachineDrainRule`, the `ipam.cluster.x-k8s.io` pair,
+ * and `ExtensionConfig` are deliberately left out (the scale note at the top
+ * of this file: add the kinds a project uses). `ClusterResourceSet`, CAPI
+ * core's other addons.cluster.x-k8s.io kind, is a separate source below —
+ * see the CAAPH block for why it's grouped there. Produces (the group takes
+ * the `CAPI` override — see GROUP_NAMESPACE_OVERRIDES in group-namespace.ts,
+ * which avoids the `K8s::Cluster::Cluster` stutter):
+ *   K8s::CAPI::Cluster      → cluster.x-k8s.io/v1beta2, kind: Cluster
+ *   K8s::CAPI::MachinePool  → cluster.x-k8s.io/v1beta2, kind: MachinePool
+ *
+ * Controller install: kubectl apply -f
+ *   https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.14.0/cluster-api-components.yaml
+ */
+const CAPI_VERSION = "v1.14.0";
+const CAPI_CRD_BASE = `https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/${CAPI_VERSION}/core/config/crd/bases`;
+
+/**
+ * Cluster API Provider AWS (CAPA) CRDs — infrastructure.cluster.x-k8s.io + controlplane.cluster.x-k8s.io
+ *
+ * The AWS infrastructure and EKS control-plane providers for CAPI. Produces
+ * (first-segment rule, no override — the `AWS` kind prefix already keeps
+ * these from reading like anything else in the file):
+ *   K8s::Infrastructure::AWSManagedCluster            → infrastructure.cluster.x-k8s.io/v1beta2
+ *   K8s::Infrastructure::AWSManagedMachinePool         → infrastructure.cluster.x-k8s.io/v1beta2
+ *   K8s::Infrastructure::AWSClusterControllerIdentity  → infrastructure.cluster.x-k8s.io/v1beta2
+ *   K8s::Controlplane::AWSManagedControlPlane          → controlplane.cluster.x-k8s.io/v1beta2
+ *
+ * Contradicts chant #10's own text: the issue describes AWSManagedControlPlane
+ * as an `infrastructure.cluster.x-k8s.io` kind alongside the other three. The
+ * shipped CRD (`config/crd/bases/controlplane.cluster.x-k8s.io_awsmanagedcontrolplanes.yaml`
+ * in the v2.13.0 tag) puts it under `controlplane.cluster.x-k8s.io` instead —
+ * CAPA's EKS control-plane provider is a `controlplane.*` provider like
+ * kubeadm's, not an infra one. The parser reads `spec.group` from the fetched
+ * CRD document itself (`parseCRDSpec` in `crd/parser.ts`), so the source list
+ * below only needs the right URL; the resulting type name follows upstream's
+ * actual group, not the issue text's.
+ *
+ * Operator install: with clusterctl,
+ *   clusterctl init --infrastructure aws:v2.13.0
+ */
+const CAPA_VERSION = "v2.13.0";
+const CAPA_CRD_BASE = `https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-aws/${CAPA_VERSION}/config/crd/bases`;
+
+/**
+ * Cluster API Addon Provider for Helm (CAAPH) CRD, plus CAPI core's own
+ * addon-binding kind — both addons.cluster.x-k8s.io/v1alpha1|v1beta2
+ *
+ * `HelmChartProxy` is CAAPH's kind — installs a Helm chart across every
+ * cluster a label selector matches. `ClusterResourceSet` ships in CAPI
+ * core's own `core/` component (same CAPI_VERSION/CAPI_CRD_BASE pin as the
+ * `Cluster`/`MachinePool` source above), not a separate provider — it binds
+ * a set of raw manifests (ConfigMaps/Secrets) to matching clusters. They're
+ * grouped in one source block because both are what the RegionCluster
+ * composite's flux-addon wiring needs (chant#11) and both share the
+ * `addons.cluster.x-k8s.io` group, so both land under `K8s::Addons::*`:
+ *   K8s::Addons::HelmChartProxy      → addons.cluster.x-k8s.io/v1alpha1, kind: HelmChartProxy
+ *   K8s::Addons::ClusterResourceSet  → addons.cluster.x-k8s.io/v1beta2,  kind: ClusterResourceSet
+ *
+ * `HelmReleaseProxy` (CAAPH's per-cluster status-tracking CR, never authored
+ * directly) is deliberately left out.
+ *
+ * Operator install: with clusterctl,
+ *   clusterctl init --addon helm:v0.6.4
+ */
+const CAAPH_VERSION = "v0.6.4";
+const CAAPH_CRD_BASE = `https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-addon-provider-helm/${CAAPH_VERSION}/config/crd/bases`;
+
+/**
+ * AWS Controllers for Kubernetes (ACK) — S3 controller CRD — s3.services.k8s.aws/v1alpha1
+ *
+ * Each ACK service controller is its own release train with its own CRDs, so
+ * (per the docs' "add the specific kinds a project uses" guidance, and
+ * matching how the ACK IAM group below stays split from EKS/RDS/S3) it is
+ * its own scoped source rather than one entry per AWS "provider". Produces:
+ *   K8s::S3::Bucket  → s3.services.k8s.aws/v1alpha1, kind: Bucket
+ *
+ * Controller install: helm install ack-s3-controller
+ *   oci://public.ecr.aws/aws-controllers-k8s/s3-chart --version 1.10.0
+ */
+const ACK_S3_VERSION = "v1.10.0";
+const ACK_S3_CRD_BASE = `https://raw.githubusercontent.com/aws-controllers-k8s/s3-controller/${ACK_S3_VERSION}/config/crd/bases`;
+
+/**
+ * ACK RDS controller CRD — rds.services.k8s.aws/v1alpha1
+ *
+ * Only `DBInstance` — the standalone-instance kind a project provisions
+ * directly. `DBCluster` and its endpoint/parameter-group/snapshot satellites
+ * are left out (no known consumer; add them when one shows up). Produces:
+ *   K8s::Rds::DBInstance  → rds.services.k8s.aws/v1alpha1, kind: DBInstance
+ *
+ * Controller install: helm install ack-rds-controller
+ *   oci://public.ecr.aws/aws-controllers-k8s/rds-chart --version 1.11.1
+ */
+const ACK_RDS_VERSION = "v1.11.1";
+const ACK_RDS_CRD_BASE = `https://raw.githubusercontent.com/aws-controllers-k8s/rds-controller/${ACK_RDS_VERSION}/config/crd/bases`;
+
+/**
+ * ACK IAM controller CRDs — iam.services.k8s.aws/v1alpha1
+ *
+ * `Role`, `User`, `Policy` — the three IAM primitives a cluster workload
+ * needing AWS access declares (a Role's trust policy, a User's access keys,
+ * a Policy document attached to either). `Group`, `InstanceProfile`,
+ * `OpenIDConnectProvider`, and `ServiceLinkedRole` are left out. Produces:
+ *   K8s::Iam::Role    → iam.services.k8s.aws/v1alpha1, kind: Role
+ *   K8s::Iam::User    → iam.services.k8s.aws/v1alpha1, kind: User
+ *   K8s::Iam::Policy  → iam.services.k8s.aws/v1alpha1, kind: Policy
+ *
+ * Controller install: helm install ack-iam-controller
+ *   oci://public.ecr.aws/aws-controllers-k8s/iam-chart --version 1.8.1
+ */
+const ACK_IAM_VERSION = "v1.8.1";
+const ACK_IAM_CRD_BASE = `https://raw.githubusercontent.com/aws-controllers-k8s/iam-controller/${ACK_IAM_VERSION}/config/crd/bases`;
+
+/**
+ * ACK EKS controller CRD — eks.services.k8s.aws/v1alpha1
+ *
+ * Only `PodIdentityAssociation` — EKS Pod Identity is the modern replacement
+ * for IRSA, and the ACK-managed way to bind a Kubernetes ServiceAccount to
+ * an IAM role without a webhook. `Cluster`, `Addon`, `Nodegroup`,
+ * `FargateProfile`, `AccessEntry`, `IdentityProviderConfig`, and
+ * `Capability` are left out (this k8s lexicon doesn't provision the EKS
+ * cluster itself). Produces:
+ *   K8s::Eks::PodIdentityAssociation  → eks.services.k8s.aws/v1alpha1, kind: PodIdentityAssociation
+ *
+ * Controller install: helm install ack-eks-controller
+ *   oci://public.ecr.aws/aws-controllers-k8s/eks-chart --version 1.20.0
+ */
+const ACK_EKS_VERSION = "v1.20.0";
+const ACK_EKS_CRD_BASE = `https://raw.githubusercontent.com/aws-controllers-k8s/eks-controller/${ACK_EKS_VERSION}/config/crd/bases`;
+
 export const CRD_SOURCES: CRDSource[] = [
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayclusters.yaml` },
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayjobs.yaml` },
@@ -378,4 +544,21 @@ export const CRD_SOURCES: CRDSource[] = [
     version: KUBEMICROVM_VERSION,
     kinds: ["MicroVM", "MicroVMImage", "MicroVMNetwork", "MicroVMClass", "MicroVMReplicaSet"],
   },
+  { type: "url", url: `${KSERVE_CRD_BASE}/serving.kserve.io_inferenceservices.yaml` },
+  { type: "url", url: `${KSERVE_CRD_BASE}/serving.kserve.io_servingruntimes.yaml` },
+  { type: "url", url: `${KSERVE_CRD_BASE}/serving.kserve.io_clusterservingruntimes.yaml` },
+  { type: "url", url: `${CAPI_CRD_BASE}/cluster.x-k8s.io_clusters.yaml` },
+  { type: "url", url: `${CAPI_CRD_BASE}/cluster.x-k8s.io_machinepools.yaml` },
+  { type: "url", url: `${CAPA_CRD_BASE}/controlplane.cluster.x-k8s.io_awsmanagedcontrolplanes.yaml` },
+  { type: "url", url: `${CAPA_CRD_BASE}/infrastructure.cluster.x-k8s.io_awsmanagedclusters.yaml` },
+  { type: "url", url: `${CAPA_CRD_BASE}/infrastructure.cluster.x-k8s.io_awsmanagedmachinepools.yaml` },
+  { type: "url", url: `${CAPA_CRD_BASE}/infrastructure.cluster.x-k8s.io_awsclustercontrolleridentities.yaml` },
+  { type: "url", url: `${CAAPH_CRD_BASE}/addons.cluster.x-k8s.io_helmchartproxies.yaml` },
+  { type: "url", url: `${CAPI_CRD_BASE}/addons.cluster.x-k8s.io_clusterresourcesets.yaml` },
+  { type: "url", url: `${ACK_S3_CRD_BASE}/s3.services.k8s.aws_buckets.yaml` },
+  { type: "url", url: `${ACK_RDS_CRD_BASE}/rds.services.k8s.aws_dbinstances.yaml` },
+  { type: "url", url: `${ACK_IAM_CRD_BASE}/iam.services.k8s.aws_roles.yaml` },
+  { type: "url", url: `${ACK_IAM_CRD_BASE}/iam.services.k8s.aws_users.yaml` },
+  { type: "url", url: `${ACK_IAM_CRD_BASE}/iam.services.k8s.aws_policies.yaml` },
+  { type: "url", url: `${ACK_EKS_CRD_BASE}/eks.services.k8s.aws_podidentityassociations.yaml` },
 ];

package/src/crd/parser.test.ts

@@ -286,6 +286,20 @@ describe("parseCRDSpec", () => {
     expect(results[0].resource.typeName).toBe("K8s::Argo::Application");
   });
 
+  test("serving.kserve.io group maps to the KServe namespace (override)", () => {
+    const spec = {
+      group: "serving.kserve.io",
+      names: { kind: "InferenceService", plural: "inferenceservices" },
+      scope: "Namespaced" as const,
+      versions: [
+        { name: "v1beta1", served: true, storage: true },
+      ],
+    };
+
+    const results = parseCRDSpec(spec);
+    expect(results[0].resource.typeName).toBe("K8s::KServe::InferenceService");
+  });
+
   test("all Flux toolkit + operator groups collapse to the Flux namespace", () => {
     const cases: Array<[string, string]> = [
       ["source.toolkit.fluxcd.io", "GitRepository"],

package/src/deep-observe-hooks.ts

@@ -55,6 +55,7 @@ import {
   k8sListMapOrderKey,
 } from "@intentius/chant/managed-fields";
 import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { GENERATED_ONCE_LABEL_KEY } from "./secret-labels";
 
 /**
  * Kubernetes-defaulted fields, per entity type, as index-erased property
@@ -115,6 +116,10 @@ export const K8S_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
     "spec.ipFamilyPolicy": "SingleStack",
     "spec.ports[].protocol": "TCP",
   },
+  "K8s::Core::Secret": {
+    // The API server defaults an untyped Secret to Opaque (#1830).
+    "type": "Opaque",
+  },
 };
 
 /**
@@ -142,6 +147,9 @@ export const K8S_SERVER_ASSIGNED_PATTERNS: Record<string, ReadonlySet<string>> =
 const K8S_OWNERSHIP_LABEL_PATTERNS: ReadonlySet<string> = new Set([
   `metadata.labels.${LABEL_OWNERSHIP_KEYS.stack}`,
   `metadata.labels.${LABEL_OWNERSHIP_KEYS.env}`,
+  // The generated-once marker (#1830) is stamped by the secret store at
+  // mint time, never by a serializer — chant's own signature, not drift.
+  `metadata.labels.${GENERATED_ONCE_LABEL_KEY}`,
 ]);
 
 const K8S_MANAGED_BY_LABEL_PATTERN = `metadata.labels.${LABEL_OWNERSHIP_KEYS.managedBy}`;
@@ -306,7 +314,23 @@ function isRecordLike(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * The paths on a `K8s::Core::Secret` whose values are secret material —
+ * `data.<key>` (live and declared base64) and `stringData.<key>` (declared
+ * plaintext). Masked on BOTH sides by core's normalization pass, so presence
+ * and key names still classify as drift while no value (or value-derived
+ * comparison) ever reaches a diff row — #1365 decision 6, the contract #1830's
+ * generated-once secrets rely on. Key-name masking alone cannot do this:
+ * Secret keys are arbitrary (`app.conf`), not name-shaped.
+ */
+const K8S_SECRET_ENTITY_TYPE = "K8s::Core::Secret";
+const K8S_SECRET_VALUE_PATTERN = /^(?:data|stringData)\./;
+
 export const k8sDeepNormalizationHooks: DeepNormalizationHooks = {
+  mask(node: DeepNode): boolean {
+    return node.entityType === K8S_SECRET_ENTITY_TYPE && K8S_SECRET_VALUE_PATTERN.test(node.pattern);
+  },
+
   prune(node: DeepNode): boolean {
     if (K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS.has(node.pattern)) return true;