@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/composites/secure-ingress.js

@@ -0,0 +1,100 @@
+/**
+ * SecureIngress composite — Ingress + optional cert-manager Certificate.
+ *
+ * A standalone Ingress with TLS via cert-manager, supporting
+ * multiple hosts and paths (unlike the single-path Ingress in WebApp).
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Ingress, Certificate } from "../generated/index.js";
+/**
+ * Create a SecureIngress composite — returns prop objects for
+ * an Ingress and optional cert-manager Certificate.
+ *
+ * @example
+ * ```ts
+ * import { SecureIngress } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { ingress, certificate } = SecureIngress({
+ *   name: "api-ingress",
+ *   hosts: [
+ *     {
+ *       hostname: "api.example.com",
+ *       paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+ *     },
+ *   ],
+ *   clusterIssuer: "letsencrypt-prod",
+ *   ingressClassName: "nginx",
+ * });
+ * ```
+ */
+export const SecureIngress = Composite((props) => {
+    const { name, hosts, clusterIssuer, ingressClassName, annotations: extraAnnotations = {}, labels: extraLabels = {}, namespace, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const allHostnames = hosts.map((h) => h.hostname);
+    const secretName = `${name}-tls`;
+    const ingressAnnotations = {
+        ...extraAnnotations,
+    };
+    if (clusterIssuer) {
+        ingressAnnotations["cert-manager.io/cluster-issuer"] = clusterIssuer;
+    }
+    const ingressRules = hosts.map((host) => ({
+        host: host.hostname,
+        http: {
+            paths: host.paths.map((p) => ({
+                path: p.path,
+                pathType: p.pathType ?? "Prefix",
+                backend: {
+                    service: { name: p.serviceName, port: { number: p.servicePort } },
+                },
+            })),
+        },
+    }));
+    const hasAnnotations = Object.keys(ingressAnnotations).length > 0;
+    const ingress = new Ingress(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+            ...(hasAnnotations && { annotations: ingressAnnotations }),
+        },
+        spec: {
+            ...(ingressClassName && { ingressClassName }),
+            rules: ingressRules,
+            ...(clusterIssuer && {
+                tls: [
+                    {
+                        hosts: allHostnames,
+                        secretName,
+                    },
+                ],
+            }),
+        },
+    }, defs?.ingress));
+    const result = { ingress };
+    if (clusterIssuer) {
+        // A real cert-manager Certificate (the ingress-shim annotation on the Ingress
+        // above is also set, so either path issues the cert; the explicit resource
+        // makes the cert lifecycle declarable).
+        result.certificate = new Certificate(mergeDefaults({
+            metadata: {
+                name: secretName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "certificate" },
+            },
+            spec: {
+                secretName,
+                issuerRef: {
+                    name: clusterIssuer,
+                    kind: "ClusterIssuer",
+                },
+                dnsNames: allHostnames,
+            },
+        }, defs?.certificate));
+    }
+    return result;
+}, "SecureIngress");

package/dist/composites/security-context.js

@@ -0,0 +1 @@
+export {};

package/dist/composites/sidecar-app.js

@@ -0,0 +1,105 @@
+/**
+ * SidecarApp composite — multi-container Deployment + Service.
+ *
+ * Sidecar and init container patterns (envoy proxy, log forwarder,
+ * DB migration init). Supports shared volumes between containers.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Deployment, Service } from "../generated/index.js";
+/**
+ * Create a SidecarApp composite — returns prop objects for
+ * a multi-container Deployment and Service.
+ *
+ * @example
+ * ```ts
+ * import { SidecarApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service } = SidecarApp({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   port: 8080,
+ *   sidecars: [
+ *     { name: "envoy", image: "envoyproxy/envoy:v1.28", ports: [{ containerPort: 9901 }] },
+ *   ],
+ *   initContainers: [
+ *     { name: "migrate", image: "api:1.0", command: ["python", "manage.py", "migrate"] },
+ *   ],
+ *   sharedVolumes: [{ name: "tmp", emptyDir: {} }],
+ * });
+ * ```
+ */
+export const SidecarApp = Composite((props) => {
+    const { name, image, port = 80, replicas = 2, sidecars, initContainers, sharedVolumes, labels: extraLabels = {}, cpuLimit = "500m", memoryLimit = "256Mi", cpuRequest = "100m", memoryRequest = "128Mi", namespace, env, securityContext, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    // Primary container
+    const primaryContainer = {
+        name,
+        image,
+        ports: [{ containerPort: port, name: "http" }],
+        resources: {
+            limits: { cpu: cpuLimit, memory: memoryLimit },
+            requests: { cpu: cpuRequest, memory: memoryRequest },
+        },
+        ...(env && { env }),
+        ...(securityContext && { securityContext }),
+    };
+    // Sidecar containers
+    const sidecarContainers = sidecars.map((sc) => ({
+        name: sc.name,
+        image: sc.image,
+        ...(sc.ports && { ports: sc.ports }),
+        ...(sc.resources && { resources: sc.resources }),
+        ...(sc.env && { env: sc.env }),
+    }));
+    // Build volumes from sharedVolumes
+    const volumes = sharedVolumes?.map((sv) => {
+        if (sv.configMapName) {
+            return { name: sv.name, configMap: { name: sv.configMapName } };
+        }
+        return { name: sv.name, emptyDir: sv.emptyDir ?? {} };
+    });
+    const podSpec = {
+        containers: [primaryContainer, ...sidecarContainers],
+        ...(initContainers && {
+            initContainers: initContainers.map((ic) => ({
+                name: ic.name,
+                image: ic.image,
+                ...(ic.command && { command: ic.command }),
+                ...(ic.args && { args: ic.args }),
+            })),
+        }),
+        ...(volumes && volumes.length > 0 && { volumes }),
+    };
+    const deployment = new Deployment(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+        },
+        spec: {
+            replicas,
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: podSpec,
+            },
+        },
+    }, defs?.deployment));
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            ports: [{ port: 80, targetPort: port, protocol: "TCP", name: "http" }],
+            type: "ClusterIP",
+        },
+    }, defs?.service));
+    return { deployment, service };
+}, "SidecarApp");

package/dist/composites/stateful-app.js

@@ -0,0 +1,111 @@
+/**
+ * StatefulApp composite — StatefulSet + headless Service + PVC template.
+ *
+ * A higher-level construct for deploying stateful applications
+ * like databases, caches, and message queues.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { StatefulSet, Service, PodDisruptionBudget } from "../generated/index.js";
+/**
+ * Create a StatefulApp composite — returns prop objects for
+ * a StatefulSet and headless Service.
+ *
+ * @example
+ * ```ts
+ * import { StatefulApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { statefulSet, service } = StatefulApp({
+ *   name: "postgres",
+ *   image: "postgres:16",
+ *   port: 5432,
+ *   storageSize: "20Gi",
+ *   env: [{ name: "POSTGRES_PASSWORD", value: "changeme" }],
+ * });
+ * ```
+ */
+export const StatefulApp = Composite((props) => {
+    const { name, image, port = 5432, replicas = 1, storageSize = "10Gi", storageClassName, mountPath = "/data", minAvailable, initContainers, securityContext, terminationGracePeriodSeconds, priorityClassName, labels: extraLabels = {}, cpuLimit = "1", memoryLimit = "1Gi", namespace, env, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const container = {
+        name,
+        image,
+        ports: [{ containerPort: port, name: "app" }],
+        resources: {
+            limits: { cpu: cpuLimit, memory: memoryLimit },
+        },
+        volumeMounts: [{ name: "data", mountPath }],
+        ...(env && { env }),
+        ...(securityContext && { securityContext }),
+    };
+    const podSpec = {
+        containers: [container],
+        ...(initContainers && {
+            initContainers: initContainers.map((ic) => ({
+                name: ic.name,
+                image: ic.image,
+                ...(ic.command && { command: ic.command }),
+                ...(ic.args && { args: ic.args }),
+            })),
+        }),
+        ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+        ...(priorityClassName && { priorityClassName }),
+    };
+    const statefulSet = new StatefulSet(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+        },
+        spec: {
+            serviceName: name,
+            replicas,
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: podSpec,
+            },
+            volumeClaimTemplates: [
+                {
+                    metadata: { name: "data" },
+                    spec: {
+                        accessModes: ["ReadWriteOnce"],
+                        ...(storageClassName && { storageClassName }),
+                        resources: { requests: { storage: storageSize } },
+                    },
+                },
+            ],
+        },
+    }, defs?.statefulSet));
+    // Headless service (clusterIP: None) for StatefulSet DNS
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            ports: [{ port, targetPort: port, protocol: "TCP", name: "app" }],
+            clusterIP: "None",
+        },
+    }, defs?.service));
+    const result = { statefulSet, service };
+    if (minAvailable !== undefined) {
+        result.pdb = new PodDisruptionBudget(mergeDefaults({
+            metadata: {
+                name,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+            },
+            spec: {
+                minAvailable,
+                selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            },
+        }, defs?.pdb));
+    }
+    return result;
+}, "StatefulApp");

package/dist/composites/vllm-serving-runtime.js

@@ -0,0 +1,114 @@
+/**
+ * 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/index.js";
+/** Build the container args list, in `vllm serve --help` flag order. */
+function buildVllmArgs(props) {
+    const { tensorParallelSize, maxModelLen, dtype, quantization, gpuMemoryUtilization, maxNumSeqs, containerArgs = [], } = props;
+    const args = [];
+    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) {
+    if (!spec)
+        return undefined;
+    const base = {};
+    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) => {
+    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 = {
+        "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 = {
+        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/dist/composites/web-app.js

@@ -0,0 +1,157 @@
+/**
+ * WebApp composite — Deployment + Service + optional Ingress.
+ *
+ * A higher-level construct for deploying stateless web applications
+ * with common defaults (health probes, resource limits, labels).
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Deployment, Service, Ingress, PodDisruptionBudget } from "../generated/index.js";
+/**
+ * Create a WebApp composite — returns declarable instances for
+ * a Deployment, Service, and optional Ingress.
+ *
+ * @example
+ * ```ts
+ * import { WebApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, ingress } = WebApp({
+ *   name: "my-app",
+ *   image: "my-app:1.0",
+ *   port: 8080,
+ *   replicas: 3,
+ *   ingressHost: "my-app.example.com",
+ * });
+ *
+ * export { deployment, service, ingress };
+ * ```
+ */
+export const WebApp = Composite((props) => {
+    const { name, image, port = 80, replicas = 2, labels: extraLabels = {}, cpuLimit = "500m", memoryLimit = "256Mi", cpuRequest = "100m", memoryRequest = "128Mi", namespace, env, initContainers, securityContext, terminationGracePeriodSeconds, priorityClassName, minAvailable, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const container = {
+        name,
+        image,
+        ports: [{ containerPort: port, name: "http" }],
+        resources: {
+            limits: { cpu: cpuLimit, memory: memoryLimit },
+            requests: { cpu: cpuRequest, memory: memoryRequest },
+        },
+        livenessProbe: {
+            httpGet: { path: "/", port },
+            initialDelaySeconds: 10,
+            periodSeconds: 10,
+        },
+        readinessProbe: {
+            httpGet: { path: "/", port },
+            initialDelaySeconds: 5,
+            periodSeconds: 5,
+        },
+        ...(env && { env }),
+        ...(securityContext && { securityContext }),
+    };
+    const podSpec = {
+        containers: [container],
+        ...(initContainers && {
+            initContainers: initContainers.map((ic) => ({
+                name: ic.name,
+                image: ic.image,
+                ...(ic.command && { command: ic.command }),
+                ...(ic.args && { args: ic.args }),
+            })),
+        }),
+        ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+        ...(priorityClassName && { priorityClassName }),
+    };
+    const deployment = new Deployment(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+        },
+        spec: {
+            replicas,
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: podSpec,
+            },
+        },
+    }, defs?.deployment));
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            ports: [{ port: 80, targetPort: port, protocol: "TCP", name: "http" }],
+            type: "ClusterIP",
+        },
+    }, defs?.service));
+    const result = { deployment, service };
+    if (props.ingressHost) {
+        // Build paths — use ingressPaths if provided, otherwise default single "/"
+        const paths = props.ingressPaths
+            ? props.ingressPaths.map((p) => ({
+                path: p.path,
+                pathType: p.pathType ?? "Prefix",
+                backend: {
+                    service: {
+                        name: p.serviceName ?? name,
+                        port: { number: p.servicePort ?? 80 },
+                    },
+                },
+            }))
+            : [
+                {
+                    path: "/",
+                    pathType: "Prefix",
+                    backend: {
+                        service: { name, port: { number: 80 } },
+                    },
+                },
+            ];
+        result.ingress = new Ingress(mergeDefaults({
+            metadata: {
+                name,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+            },
+            spec: {
+                rules: [
+                    {
+                        host: props.ingressHost,
+                        http: { paths },
+                    },
+                ],
+                ...(props.ingressTlsSecret && {
+                    tls: [
+                        {
+                            hosts: [props.ingressHost],
+                            secretName: props.ingressTlsSecret,
+                        },
+                    ],
+                }),
+            },
+        }, defs?.ingress));
+    }
+    if (minAvailable !== undefined) {
+        result.pdb = new PodDisruptionBudget(mergeDefaults({
+            metadata: {
+                name,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+            },
+            spec: {
+                minAvailable,
+                selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            },
+        }, defs?.pdb));
+    }
+    return result;
+}, "WebApp");