@intentius/chant-lexicon-k8s 0.0.16 → 0.0.22

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "12a8a5033319b618",
+    "manifest.json": "b91b5f6c197826b1",
     "meta.json": "1ce194f36f9b5f90",
     "types/index.d.ts": "beec4cc869064186",
     "rules/missing-resource-limits.ts": "a6f776d2ff477948",
@@ -31,8 +31,8 @@
     "rules/wk8105.ts": "8dbcfe399f23656a",
     "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
     "rules/wk8207.ts": "6f2bc621d530afa2",
-    "skills/chant-k8s.md": "c7db82c3ba37c78",
+    "skills/chant-k8s.md": "177efa9794242096",
     "skills/chant-k8s-patterns.md": "c5151ed799145c4b"
   },
-  "composite": "592308cdbd70d2ee"
+  "composite": "c7b4bc8445140fdf"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.0.16",
+  "version": "0.0.22",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/skills/chant-k8s.md

@@ -8,7 +8,7 @@ user-invocable: true
 
 ## How chant and Kubernetes relate
 
-chant is a **synthesis-only** tool — it compiles TypeScript source files into Kubernetes YAML manifests. chant does NOT call the Kubernetes API. Your job as an agent is to bridge the two:
+chant is a **synthesis compiler** — it compiles TypeScript source files into Kubernetes YAML manifests. `chant build` does not call the Kubernetes API; synthesis is pure and deterministic. The optional `chant state snapshot` command queries the Kubernetes API to capture deployment metadata (pod names, status, UIDs) for observability. Your job as an agent is to bridge synthesis and deployment:
 
 - Use **chant** for: build, lint, diff (local YAML comparison)
 - Use **kubectl / k8s API** for: apply, rollback, monitoring, troubleshooting

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.0.16",
+  "version": "0.0.22",
+  "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "lexicons/k8s"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "kubernetes",
+    "k8s",
+    "chant"
+  ],
   "type": "module",
   "files": [
     "src/",
@@ -25,7 +43,7 @@
     "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.15"
+    "@intentius/chant": "0.0.22"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/codegen/docs.ts

@@ -1134,6 +1134,16 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources:
       },
     ],
     basePath: "/chant/lexicons/k8s/",
+    sidebarExtra: [
+      {
+        label: "Vendor Composites",
+        items: [
+          { label: "EKS Composites", slug: "eks-composites" },
+          { label: "AKS Composites", slug: "aks-composites" },
+          { label: "GKE Composites", slug: "gke-composites" },
+        ],
+      },
+    ],
   };
 
   const result = await docsPipeline(config);

package/src/composites/cockroachdb-cluster.ts

@@ -0,0 +1,421 @@
+/**
+ * CockroachDbCluster composite — StatefulSet + Services + RBAC + PDB + Jobs.
+ *
+ * Deploys a CockroachDB cluster on Kubernetes with TLS support via self-signed
+ * certificates. Produces all K8s resources needed for a single cloud's slice of
+ * a CockroachDB cluster (typically 3 nodes). Multi-cloud deployments use one
+ * CockroachDbCluster per cloud, sharing joinAddresses across clouds.
+ */
+
+export interface CockroachDbClusterProps {
+  /** Cluster name — used in metadata, labels, and service names. */
+  name: string;
+  /** Namespace for all namespaced resources. */
+  namespace?: string;
+  /** Number of StatefulSet replicas (default: 3). */
+  replicas?: number;
+  /** CockroachDB container image (default: "cockroachdb/cockroach:v24.3.0"). */
+  image?: string;
+  /** PVC storage size per node (default: "100Gi"). */
+  storageSize?: string;
+  /** StorageClass name for PVCs. */
+  storageClassName?: string;
+  /** CPU limit per pod (default: "2"). */
+  cpuLimit?: string;
+  /** Memory limit per pod (default: "8Gi"). */
+  memoryLimit?: string;
+  /** Fraction of container memory for CockroachDB cache (default: ".25"). */
+  cachePercent?: string;
+  /** Fraction of container memory for SQL temp storage (default: ".25"). */
+  sqlMemoryPercent?: string;
+  /** CockroachDB locality flag (e.g., "cloud=aws,region=us-east-1"). */
+  locality?: string;
+  /** All node DNS names for --join (cross-cloud cluster membership). */
+  joinAddresses?: string[];
+  /** Enable TLS via self-signed CA certs (default: true). */
+  secure?: boolean;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+}
+
+export interface CockroachDbClusterResult {
+  serviceAccount: Record<string, unknown>;
+  role: Record<string, unknown>;
+  roleBinding: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  /** Client-facing service (ClusterIP, ports 26257+8080). */
+  publicService: Record<string, unknown>;
+  /** Pod discovery service (headless, publishNotReadyAddresses). */
+  headlessService: Record<string, unknown>;
+  pdb: Record<string, unknown>;
+  statefulSet: Record<string, unknown>;
+  /** One-shot cockroach init job. */
+  initJob: Record<string, unknown>;
+  /** Generates self-signed CA + node certs, stores in Secrets. */
+  certGenJob: Record<string, unknown>;
+}
+
+/**
+ * Create a CockroachDbCluster composite — returns prop objects for a full
+ * CockroachDB StatefulSet deployment including RBAC, Services, PDB, and Jobs.
+ *
+ * @example
+ * ```ts
+ * import { CockroachDbCluster } from "@intentius/chant-lexicon-k8s";
+ *
+ * const crdb = CockroachDbCluster({
+ *   name: "cockroachdb",
+ *   namespace: "crdb",
+ *   replicas: 3,
+ *   locality: "cloud=aws,region=us-east-1",
+ *   joinAddresses: [
+ *     "cockroachdb-0.cockroachdb.crdb.svc.cluster.local",
+ *     "cockroachdb-1.cockroachdb.crdb.svc.cluster.local",
+ *     "cockroachdb-2.cockroachdb.crdb.svc.cluster.local",
+ *   ],
+ * });
+ * ```
+ */
+export function CockroachDbCluster(props: CockroachDbClusterProps): CockroachDbClusterResult {
+  const {
+    name,
+    namespace,
+    replicas = 3,
+    image = "cockroachdb/cockroach:v24.3.0",
+    storageSize = "100Gi",
+    storageClassName,
+    cpuLimit = "2",
+    memoryLimit = "8Gi",
+    cachePercent = ".25",
+    sqlMemoryPercent = ".25",
+    locality,
+    joinAddresses = [],
+    secure = true,
+    labels: extraLabels = {},
+  } = props;
+
+  const saName = name;
+  const certsDir = "/cockroach/cockroach-certs";
+  const dataDir = "/cockroach/cockroach-data";
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // ── RBAC ─────────────────────────────────────────────────────────
+
+  const serviceAccount: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+    },
+  };
+
+  const role: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: [""], resources: ["secrets"], verbs: ["get", "create", "patch"] },
+    ],
+  };
+
+  const roleBinding: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "Role",
+      name,
+    },
+    subjects: [
+      { kind: "ServiceAccount", name: saName, ...(namespace && { namespace }) },
+    ],
+  };
+
+  const clusterRole: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: ["certificates.k8s.io"], resources: ["certificatesigningrequests"], verbs: ["get", "create", "watch"] },
+    ],
+  };
+
+  const clusterRoleBinding: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name,
+    },
+    subjects: [
+      { kind: "ServiceAccount", name: saName, ...(namespace && { namespace }) },
+    ],
+  };
+
+  // ── Services ────────────────────────────────────────────────────
+
+  const publicService: Record<string, unknown> = {
+    metadata: {
+      name: `${name}-public`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [
+        { port: 26257, targetPort: 26257, protocol: "TCP", name: "grpc" },
+        { port: 8080, targetPort: 8080, protocol: "TCP", name: "http" },
+      ],
+      type: "ClusterIP",
+    },
+  };
+
+  const headlessService: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+      annotations: {
+        "service.alpha.kubernetes.io/tolerate-unready-endpoints": "true",
+      },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [
+        { port: 26257, targetPort: 26257, protocol: "TCP", name: "grpc" },
+        { port: 8080, targetPort: 8080, protocol: "TCP", name: "http" },
+      ],
+      clusterIP: "None",
+      publishNotReadyAddresses: true,
+    },
+  };
+
+  // ── PodDisruptionBudget ─────────────────────────────────────────
+
+  const pdb: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+    },
+    spec: {
+      maxUnavailable: 1,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+    },
+  };
+
+  // ── StatefulSet ─────────────────────────────────────────────────
+
+  const cockroachArgs = [
+    "start",
+    `--logtostderr=WARNING`,
+    `--certs-dir=${secure ? certsDir : ""}`,
+    ...(secure ? [] : ["--insecure"]),
+    `--advertise-host=$(hostname -f)`,
+    `--http-addr=0.0.0.0`,
+    `--cache=${cachePercent}`,
+    `--max-sql-memory=${sqlMemoryPercent}`,
+    ...(joinAddresses.length > 0 ? [`--join=${joinAddresses.join(",")}`] : []),
+    ...(locality ? [`--locality=${locality}`] : []),
+  ];
+
+  const volumes: Record<string, unknown>[] = [];
+  const volumeMounts: Record<string, unknown>[] = [
+    { name: "datadir", mountPath: dataDir },
+  ];
+
+  if (secure) {
+    volumes.push({ name: "certs", secret: { secretName: `${name}-node-certs`, defaultMode: 0o400 } });
+    volumeMounts.push({ name: "certs", mountPath: certsDir });
+  }
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ports: [
+      { containerPort: 26257, name: "grpc" },
+      { containerPort: 8080, name: "http" },
+    ],
+    command: ["/cockroach/cockroach"],
+    args: cockroachArgs,
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    volumeMounts,
+    env: [
+      { name: "COCKROACH_CHANNEL", value: "kubernetes-multiregion" },
+    ],
+    readinessProbe: {
+      httpGet: { path: "/health?ready=1", port: 8080, ...(secure && { scheme: "HTTPS" }) },
+      initialDelaySeconds: 10,
+      periodSeconds: 5,
+      failureThreshold: 2,
+    },
+    livenessProbe: {
+      httpGet: { path: "/health", port: 8080, ...(secure && { scheme: "HTTPS" }) },
+      initialDelaySeconds: 30,
+      periodSeconds: 5,
+    },
+  };
+
+  const statefulSet: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+    },
+    spec: {
+      serviceName: name,
+      replicas,
+      podManagementPolicy: "Parallel",
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          terminationGracePeriodSeconds: 60,
+          containers: [container],
+          ...(volumes.length > 0 && { volumes }),
+          affinity: {
+            podAntiAffinity: {
+              preferredDuringSchedulingIgnoredDuringExecution: [
+                {
+                  weight: 100,
+                  podAffinityTerm: {
+                    labelSelector: { matchLabels: { "app.kubernetes.io/name": name } },
+                    topologyKey: "kubernetes.io/hostname",
+                  },
+                },
+              ],
+            },
+          },
+        },
+      },
+      volumeClaimTemplates: [
+        {
+          metadata: { name: "datadir" },
+          spec: {
+            accessModes: ["ReadWriteOnce"],
+            ...(storageClassName && { storageClassName }),
+            resources: { requests: { storage: storageSize } },
+          },
+        },
+      ],
+    },
+  };
+
+  // ── cert-gen Job ─────────────────────────────────────────────────
+
+  // Generates self-signed CA and node certs, stores them in K8s Secrets.
+  // Each node's cert includes the pod DNS names (pod-N.svc.namespace.svc.cluster.local).
+  const nodeNames = Array.from({ length: replicas }, (_, i) => `${name}-${i}.${name}`);
+  const nodeAddresses = namespace
+    ? nodeNames.map((n) => `${n}.${namespace}.svc.cluster.local`)
+    : nodeNames.map((n) => `${n}.default.svc.cluster.local`);
+
+  const certGenScript = [
+    "set -ex",
+    "cd /cockroach",
+    "cockroach cert create-ca --certs-dir=certs --ca-key=certs/ca.key",
+    `cockroach cert create-node ${nodeAddresses.join(" ")} localhost 127.0.0.1 --certs-dir=certs --ca-key=certs/ca.key`,
+    "cockroach cert create-client root --certs-dir=certs --ca-key=certs/ca.key",
+  ].join(" && ");
+
+  const certGenJob: Record<string, unknown> = {
+    metadata: {
+      name: `${name}-cert-gen`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "cert-gen" },
+    },
+    spec: {
+      backoffLimit: 3,
+      ttlSecondsAfterFinished: 3600,
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          restartPolicy: "OnFailure",
+          containers: [
+            {
+              name: "cert-gen",
+              image,
+              command: ["bash", "-c", certGenScript],
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  // ── init Job ────────────────────────────────────────────────────
+
+  const initArgs = secure
+    ? [`--certs-dir=${certsDir}`, `--host=${name}-0.${name}`]
+    : ["--insecure", `--host=${name}-0.${name}`];
+
+  const initVolumes: Record<string, unknown>[] = [];
+  const initVolumeMounts: Record<string, unknown>[] = [];
+  if (secure) {
+    initVolumes.push({ name: "client-certs", secret: { secretName: `${name}-node-certs`, defaultMode: 0o400 } });
+    initVolumeMounts.push({ name: "client-certs", mountPath: certsDir });
+  }
+
+  const initJob: Record<string, unknown> = {
+    metadata: {
+      name: `${name}-init`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "init" },
+    },
+    spec: {
+      backoffLimit: 6,
+      ttlSecondsAfterFinished: 3600,
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          restartPolicy: "OnFailure",
+          containers: [
+            {
+              name: "cluster-init",
+              image,
+              command: ["/cockroach/cockroach"],
+              args: ["init", ...initArgs],
+              ...(initVolumeMounts.length > 0 && { volumeMounts: initVolumeMounts }),
+            },
+          ],
+          ...(initVolumes.length > 0 && { volumes: initVolumes }),
+        },
+      },
+    },
+  };
+
+  return {
+    serviceAccount,
+    role,
+    roleBinding,
+    clusterRole,
+    clusterRoleBinding,
+    publicService,
+    headlessService,
+    pdb,
+    statefulSet,
+    initJob,
+    certGenJob,
+  };
+}

package/src/composites/composites.test.ts

@@ -3050,3 +3050,170 @@ describe("AksExternalDnsAgent", () => {
     expect(container.securityContext.runAsUser).toBe(65534);
   });
 });
+
+// ── CockroachDbCluster ──────────────────────────────────────────────
+
+describe("CockroachDbCluster", () => {
+  const { CockroachDbCluster } = require("./cockroachdb-cluster");
+
+  const minProps = { name: "cockroachdb" };
+
+  test("returns all expected resources", () => {
+    const result = CockroachDbCluster(minProps);
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.role).toBeDefined();
+    expect(result.roleBinding).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+    expect(result.publicService).toBeDefined();
+    expect(result.headlessService).toBeDefined();
+    expect(result.pdb).toBeDefined();
+    expect(result.statefulSet).toBeDefined();
+    expect(result.initJob).toBeDefined();
+    expect(result.certGenJob).toBeDefined();
+  });
+
+  test("default replicas is 3", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.statefulSet.spec as any;
+    expect(spec.replicas).toBe(3);
+  });
+
+  test("default image is cockroachdb/cockroach:v24.3.0", () => {
+    const result = CockroachDbCluster(minProps);
+    const container = (result.statefulSet.spec as any).template.spec.containers[0];
+    expect(container.image).toBe("cockroachdb/cockroach:v24.3.0");
+  });
+
+  test("StatefulSet has correct ports (26257+8080)", () => {
+    const result = CockroachDbCluster(minProps);
+    const container = (result.statefulSet.spec as any).template.spec.containers[0];
+    const ports = container.ports.map((p: any) => p.containerPort);
+    expect(ports).toContain(26257);
+    expect(ports).toContain(8080);
+  });
+
+  test("StatefulSet has PVC with default 100Gi storage", () => {
+    const result = CockroachDbCluster(minProps);
+    const vct = (result.statefulSet.spec as any).volumeClaimTemplates[0];
+    expect(vct.spec.resources.requests.storage).toBe("100Gi");
+    expect(vct.spec.accessModes).toEqual(["ReadWriteOnce"]);
+  });
+
+  test("headless service has clusterIP None and publishNotReadyAddresses", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.headlessService.spec as any;
+    expect(spec.clusterIP).toBe("None");
+    expect(spec.publishNotReadyAddresses).toBe(true);
+  });
+
+  test("public service has ClusterIP type with both ports", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.publicService.spec as any;
+    expect(spec.type).toBe("ClusterIP");
+    const ports = spec.ports.map((p: any) => p.port);
+    expect(ports).toContain(26257);
+    expect(ports).toContain(8080);
+  });
+
+  test("PDB has maxUnavailable 1", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.pdb.spec as any;
+    expect(spec.maxUnavailable).toBe(1);
+  });
+
+  test("StatefulSet has pod anti-affinity", () => {
+    const result = CockroachDbCluster(minProps);
+    const affinity = (result.statefulSet.spec as any).template.spec.affinity;
+    expect(affinity.podAntiAffinity).toBeDefined();
+  });
+
+  test("props flow through (replicas, image, storage)", () => {
+    const result = CockroachDbCluster({
+      name: "crdb",
+      replicas: 5,
+      image: "cockroachdb/cockroach:v23.2.0",
+      storageSize: "200Gi",
+    });
+    const spec = result.statefulSet.spec as any;
+    expect(spec.replicas).toBe(5);
+    expect(spec.template.spec.containers[0].image).toBe("cockroachdb/cockroach:v23.2.0");
+    expect(spec.volumeClaimTemplates[0].spec.resources.requests.storage).toBe("200Gi");
+  });
+
+  test("joinAddresses appear in container args", () => {
+    const joins = ["crdb-0.crdb.ns.svc.cluster.local", "crdb-1.crdb.ns.svc.cluster.local"];
+    const result = CockroachDbCluster({ name: "crdb", joinAddresses: joins });
+    const args = (result.statefulSet.spec as any).template.spec.containers[0].args as string[];
+    const joinArg = args.find((a: string) => a.startsWith("--join="));
+    expect(joinArg).toBeDefined();
+    expect(joinArg).toContain("crdb-0.crdb.ns.svc.cluster.local");
+    expect(joinArg).toContain("crdb-1.crdb.ns.svc.cluster.local");
+  });
+
+  test("locality appears in container args when set", () => {
+    const result = CockroachDbCluster({ name: "crdb", locality: "cloud=aws,region=us-east-1" });
+    const args = (result.statefulSet.spec as any).template.spec.containers[0].args as string[];
+    expect(args).toContain("--locality=cloud=aws,region=us-east-1");
+  });
+
+  test("namespace is set on all namespaced resources", () => {
+    const result = CockroachDbCluster({ name: "crdb", namespace: "crdb-eks" });
+    for (const key of ["serviceAccount", "role", "roleBinding", "publicService", "headlessService", "pdb", "statefulSet", "initJob", "certGenJob"] as const) {
+      expect((result[key].metadata as any).namespace).toBe("crdb-eks");
+    }
+  });
+
+  test("cluster-scoped resources do not have namespace", () => {
+    const result = CockroachDbCluster({ name: "crdb", namespace: "crdb-eks" });
+    expect((result.clusterRole.metadata as any).namespace).toBeUndefined();
+    expect((result.clusterRoleBinding.metadata as any).namespace).toBeUndefined();
+  });
+
+  test("includes common labels", () => {
+    const result = CockroachDbCluster(minProps);
+    const meta = result.statefulSet.metadata as any;
+    expect(meta.labels["app.kubernetes.io/name"]).toBe("cockroachdb");
+    expect(meta.labels["app.kubernetes.io/managed-by"]).toBe("chant");
+  });
+
+  test("secure mode mounts certs volume", () => {
+    const result = CockroachDbCluster({ name: "crdb", secure: true });
+    const spec = (result.statefulSet.spec as any).template.spec;
+    expect(spec.volumes).toBeDefined();
+    const certsVol = spec.volumes.find((v: any) => v.name === "certs");
+    expect(certsVol).toBeDefined();
+    expect(certsVol.secret.secretName).toBe("crdb-node-certs");
+  });
+
+  test("insecure mode omits certs volume", () => {
+    const result = CockroachDbCluster({ name: "crdb", secure: false });
+    const spec = (result.statefulSet.spec as any).template.spec;
+    expect(spec.volumes).toBeUndefined();
+    const args = spec.containers[0].args as string[];
+    expect(args).toContain("--insecure");
+  });
+
+  test("storageClassName is set when provided", () => {
+    const result = CockroachDbCluster({ name: "crdb", storageClassName: "gp3-encrypted" });
+    const vct = (result.statefulSet.spec as any).volumeClaimTemplates[0];
+    expect(vct.spec.storageClassName).toBe("gp3-encrypted");
+  });
+
+  test("init job references correct host", () => {
+    const result = CockroachDbCluster({ name: "crdb" });
+    const container = (result.initJob.spec as any).template.spec.containers[0];
+    expect(container.args).toContain("--host=crdb-0.crdb");
+  });
+
+  test("StatefulSet uses Parallel podManagementPolicy", () => {
+    const result = CockroachDbCluster(minProps);
+    expect((result.statefulSet.spec as any).podManagementPolicy).toBe("Parallel");
+  });
+
+  test("cert-gen job uses same image as StatefulSet", () => {
+    const result = CockroachDbCluster({ name: "crdb", image: "cockroachdb/cockroach:v23.2.0" });
+    const container = (result.certGenJob.spec as any).template.spec.containers[0];
+    expect(container.image).toBe("cockroachdb/cockroach:v23.2.0");
+  });
+});

package/src/composites/index.ts

@@ -71,3 +71,5 @@ export { GkeExternalDnsAgent } from "./gke-external-dns-agent";
 export type { GkeExternalDnsAgentProps, GkeExternalDnsAgentResult } from "./gke-external-dns-agent";
 export { AksExternalDnsAgent } from "./aks-external-dns-agent";
 export type { AksExternalDnsAgentProps, AksExternalDnsAgentResult } from "./aks-external-dns-agent";
+export { CockroachDbCluster } from "./cockroachdb-cluster";
+export type { CockroachDbClusterProps, CockroachDbClusterResult } from "./cockroachdb-cluster";

package/src/index.ts

@@ -21,7 +21,7 @@ export {
   BatchJob, SecureIngress, ConfiguredApp, SidecarApp, MonitoredService, NetworkIsolatedApp,
   IrsaServiceAccount, AlbIngress, EbsStorageClass, EfsStorageClass, FluentBitAgent, ExternalDnsAgent, AdotCollector,
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
-  GceIngress,
+  GceIngress, CockroachDbCluster,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
   GkeFluentBitAgent, GkeOtelCollector, GkeExternalDnsAgent, AksExternalDnsAgent,
@@ -43,7 +43,7 @@ export type {
   FilestoreStorageClassProps, FilestoreStorageClassResult,
   GkeGatewayProps, GkeGatewayResult,
   ConfigConnectorContextProps, ConfigConnectorContextResult,
-  GceIngressProps, GceIngressResult,
+  GceIngressProps, GceIngressResult, CockroachDbClusterProps, CockroachDbClusterResult,
   AgicIngressProps, AgicIngressResult,
   AzureDiskStorageClassProps, AzureDiskStorageClassResult,
   AzureFileStorageClassProps, AzureFileStorageClassResult,

package/src/plugin.ts

@@ -6,7 +6,7 @@
  */
 
 import { createRequire } from "module";
-import type { LexiconPlugin, SkillDefinition, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, SkillDefinition, InitTemplateSet, ResourceMetadata } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
@@ -299,6 +299,96 @@ export const service = new Service({
     console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
   },
 
+  async describeResources(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+  }): Promise<Record<string, ResourceMetadata>> {
+    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const rt = getRuntime();
+    const resources: Record<string, ResourceMetadata> = {};
+
+    // Resolve namespace from environment (convention: env name = namespace)
+    const namespace = options.environment;
+
+    // Parse build output to extract kind/name pairs for each entity
+    let manifests: Array<{ kind: string; metadata: { name: string; namespace?: string }; apiVersion: string }> = [];
+    try {
+      // K8s build output is YAML with --- separators
+      const docs = options.buildOutput.split(/^---$/m).filter((d) => d.trim());
+      for (const doc of docs) {
+        // Simple YAML parsing — look for kind: and metadata.name:
+        const kindMatch = doc.match(/^kind:\s*(.+)$/m);
+        const nameMatch = doc.match(/^\s+name:\s*(.+)$/m);
+        const apiVersionMatch = doc.match(/^apiVersion:\s*(.+)$/m);
+        if (kindMatch && nameMatch && apiVersionMatch) {
+          manifests.push({
+            kind: kindMatch[1].trim(),
+            metadata: { name: nameMatch[1].trim() },
+            apiVersion: apiVersionMatch[1].trim(),
+          });
+        }
+      }
+    } catch {
+      // If build output parsing fails, skip
+    }
+
+    // Query each resource
+    for (const entityName of options.entityNames) {
+      // Find the corresponding manifest
+      const manifest = manifests.find((m) => {
+        // Try matching by entity name convention
+        return m.metadata.name === entityName ||
+          entityName.toLowerCase().includes(m.metadata.name.toLowerCase());
+      });
+
+      if (!manifest) continue;
+
+      // Build kubectl resource type from apiVersion + kind
+      const resourceType = manifest.kind.toLowerCase();
+      const getResult = await rt.spawn([
+        "kubectl", "get", resourceType, manifest.metadata.name,
+        "-n", namespace,
+        "-o", "json",
+      ]);
+
+      if (getResult.exitCode !== 0) continue;
+
+      try {
+        const obj = JSON.parse(getResult.stdout) as {
+          metadata: { name: string; uid: string; creationTimestamp: string };
+          status?: { phase?: string; conditions?: Array<{ type: string; status: string }> };
+        };
+
+        // Derive status from conditions or phase
+        let status = "Unknown";
+        if (obj.status?.phase) {
+          status = obj.status.phase;
+        } else if (obj.status?.conditions) {
+          const ready = obj.status.conditions.find((c) => c.type === "Ready" || c.type === "Available");
+          status = ready?.status === "True" ? "Ready" : "NotReady";
+        }
+
+        // Build attributes, scrubbing sensitive data
+        const attributes: Record<string, unknown> = {
+          uid: obj.metadata.uid,
+        };
+
+        resources[entityName] = {
+          type: `${manifest.apiVersion}/${manifest.kind}`,
+          physicalId: obj.metadata.name,
+          status,
+          lastUpdated: obj.metadata.creationTimestamp,
+          attributes,
+        };
+      } catch {
+        // Skip parse failures
+      }
+    }
+
+    return resources;
+  },
+
   mcpTools() {
     return [
       {
@@ -400,7 +490,7 @@ user-invocable: true
 
 ## How chant and Kubernetes relate
 
-chant is a **synthesis-only** tool — it compiles TypeScript source files into Kubernetes YAML manifests. chant does NOT call the Kubernetes API. Your job as an agent is to bridge the two:
+chant is a **synthesis compiler** — it compiles TypeScript source files into Kubernetes YAML manifests. \`chant build\` does not call the Kubernetes API; synthesis is pure and deterministic. The optional \`chant state snapshot\` command queries the Kubernetes API to capture deployment metadata (pod names, status, UIDs) for observability. Your job as an agent is to bridge synthesis and deployment:
 
 - Use **chant** for: build, lint, diff (local YAML comparison)
 - Use **kubectl / k8s API** for: apply, rollback, monitoring, troubleshooting