@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/dist/composites/gke-otel-collector.js

@@ -0,0 +1,94 @@
+/**
+ * GkeOtelCollector composite — DaemonSet + RBAC + ConfigMap for OpenTelemetry on GKE.
+ *
+ * @gke Like AdotCollector but targets Cloud Trace + Cloud Monitoring via the
+ * googlecloud exporter and uses GKE Workload Identity instead of IRSA.
+ *
+ * The collector config is typed through the otel lexicon
+ * (`@intentius/chant-lexicon-otel`) and rendered with its `collectorYaml`, so
+ * it is checked the way any declared collector config is.
+ */
+import { Composite } from "@intentius/chant";
+import { OtlpReceiver, BatchProcessor, ResourceDetectionProcessor, GoogleCloudExporter, Pipeline, buildCollectorConfig, collectorYaml, } from "@intentius/chant-lexicon-otel";
+import { collectorAgentResources } from "./otel-collector-agent.js";
+import { agentClusterRules } from "./otel-collector-rbac.js";
+import { collectorNodeAccess } from "./otel-collector-node.js";
+/**
+ * Create a GkeOtelCollector composite — returns prop objects for
+ * a DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, and ConfigMap.
+ *
+ * @gke
+ * @example
+ * ```ts
+ * import { GkeOtelCollector } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap } = GkeOtelCollector({
+ *   clusterName: "my-cluster",
+ *   projectId: "my-project",
+ *   gcpServiceAccountEmail: "otel@my-project.iam.gserviceaccount.com",
+ * });
+ * ```
+ */
+export const GkeOtelCollector = Composite((props) => {
+    const { clusterName, projectId, gcpServiceAccountEmail, name = "gke-otel-collector", image = "otel/opentelemetry-collector-contrib:latest", namespace = "gke-monitoring", labels: extraLabels = {}, cpuRequest = "100m", memoryRequest = "256Mi", cpuLimit = "500m", memoryLimit = "512Mi", defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    // The collector config, declared through the otel lexicon and rendered to
+    // the same YAML the ConfigMap has always carried (#2559).
+    const otlp = new OtlpReceiver({
+        protocols: {
+            grpc: { endpoint: "0.0.0.0:4317" },
+            http: { endpoint: "0.0.0.0:4318" },
+        },
+    });
+    const batch = new BatchProcessor({ timeout: "30s", send_batch_size: 8192 });
+    const resourceDetection = new ResourceDetectionProcessor({ detectors: ["gcp"], timeout: "10s" });
+    const googleCloud = new GoogleCloudExporter({
+        project: projectId,
+        metric: { prefix: `custom.googleapis.com/${clusterName}` },
+        trace: {
+            attribute_mappings: [{ key: "service.name", replacement: "g.co/r/service/name" }],
+        },
+    });
+    const entities = [
+        otlp,
+        batch,
+        resourceDetection,
+        googleCloud,
+        new Pipeline({ signal: "metrics", receivers: [otlp], processors: [batch, resourceDetection], exporters: [googleCloud] }),
+        new Pipeline({ signal: "traces", receivers: [otlp], processors: [batch, resourceDetection], exporters: [googleCloud] }),
+    ];
+    const otelConfig = collectorYaml(entities);
+    const built = buildCollectorConfig(entities).config;
+    // The DaemonSet, RBAC and ConfigMap are the ones OtelCollector builds too.
+    return collectorAgentResources({
+        name,
+        namespace,
+        image,
+        commonLabels,
+        extraLabels,
+        configYaml: otelConfig,
+        configDir: "/etc/otel",
+        // The ClusterRole OtelCollector shares: k8sattributes' rules, and none
+        // for receivers, since the config's only receiver is otlp (#2923).
+        clusterRules: agentClusterRules(built),
+        // Derived like OtelCollector's (#3103). The config reads nothing from the
+        // node, so this adds no variable or mount and the output is unchanged.
+        nodeAccess: collectorNodeAccess(built, "/etc/otel"),
+        ports: [
+            { containerPort: 4317, name: "otlp-grpc" },
+            { containerPort: 4318, name: "otlp-http" },
+        ],
+        cpuRequest,
+        memoryRequest,
+        cpuLimit,
+        memoryLimit,
+        ...(gcpServiceAccountEmail
+            ? { serviceAccountAnnotations: { "iam.gke.io/gcp-service-account": gcpServiceAccountEmail } }
+            : {}),
+        defaults: defs,
+    });
+}, "GkeOtelCollector");

package/dist/composites/index.js

@@ -0,0 +1,51 @@
+export { WebApp } from "./web-app.js";
+export { StatefulApp } from "./stateful-app.js";
+export { CronWorkload } from "./cron-workload.js";
+export { AutoscaledService } from "./autoscaled-service.js";
+export { WorkerPool } from "./worker-pool.js";
+export { NamespaceEnv } from "./namespace-env.js";
+export { NodeAgent } from "./node-agent.js";
+export { BatchJob } from "./batch-job.js";
+export { SecureIngress } from "./secure-ingress.js";
+export { ConfiguredApp } from "./configured-app.js";
+export { SidecarApp } from "./sidecar-app.js";
+export { MonitoredService } from "./monitored-service.js";
+export { NetworkIsolatedApp } from "./network-isolated-app.js";
+export { IrsaServiceAccount } from "./irsa-service-account.js";
+export { AlbIngress } from "./alb-ingress.js";
+export { EbsStorageClass } from "./ebs-storage-class.js";
+export { EfsStorageClass } from "./efs-storage-class.js";
+export { FluentBitAgent } from "./fluent-bit-agent.js";
+export { ExternalDnsAgent } from "./external-dns-agent.js";
+export { AdotCollector } from "./adot-collector.js";
+export { MetricsServer } from "./metrics-server.js";
+export { WorkloadIdentityServiceAccount } from "./workload-identity-service-account.js";
+export { GcePdStorageClass } from "./gce-pd-storage-class.js";
+export { FilestoreStorageClass } from "./filestore-storage-class.js";
+export { GkeGateway } from "./gke-gateway.js";
+export { ConfigConnectorContext } from "./config-connector-context.js";
+export { GceIngress } from "./gce-ingress.js";
+export { AgicIngress } from "./agic-ingress.js";
+export { AzureDiskStorageClass } from "./azure-disk-storage-class.js";
+export { AzureFileStorageClass } from "./azure-file-storage-class.js";
+export { AzureMonitorCollector } from "./azure-monitor-collector.js";
+export { WorkloadIdentityServiceAccount as AksWorkloadIdentityServiceAccount } from "./workload-identity-sa.js";
+export { GkeFluentBitAgent } from "./gke-fluent-bit-agent.js";
+export { OtelCollector } from "./otel-collector.js";
+export { OtelOperatorCollector } from "./otel-operator-collector.js";
+export { OtelCollectorGateway, gatewayExporter } from "./otel-collector-gateway.js";
+export { OTEL_COLLECTOR_ANNOTATIONS } from "./otel-collector-shape.js";
+export { GkeOtelCollector } from "./gke-otel-collector.js";
+export { GkeExternalDnsAgent } from "./gke-external-dns-agent.js";
+export { AksExternalDnsAgent } from "./aks-external-dns-agent.js";
+export { CockroachDbCluster } from "./cockroachdb-cluster.js";
+export { CockroachDbRegionStack } from "./cockroachdb-region-stack.js";
+export { RayCluster } from "./ray-cluster.js";
+export { RayJob } from "./ray-job.js";
+export { RayService } from "./ray-service.js";
+export { InferenceService } from "./inference-service.js";
+export { ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster } from "./argo-app.js";
+export { FluxGitSource, FluxAppFor } from "./flux-app.js";
+export { VllmServingRuntime } from "./vllm-serving-runtime.js";
+export { Model, resolveModelStorageUri } from "./model.js";
+export { OperatorStack, deriveHostVerbClass, DEFAULT_RESOURCE_RULES } from "./operator-stack.js";

package/dist/composites/inference-service.js

@@ -0,0 +1,76 @@
+/**
+ * InferenceService composite — KServe `InferenceService` (v1beta1).
+ *
+ * Spec-true to KServe: the predictor references a `ServingRuntime` by name
+ * (the plug seam KServe itself defines — see #984's VllmServingRuntime) and
+ * a model `storageUri`, plus the real `ComponentExtensionSpec` autoscaling
+ * knobs (`minReplicas`/`maxReplicas`/`scaleTarget`/`scaleMetric`) and
+ * `canaryTrafficPercent`. No chant-flavored runtime abstraction is invented;
+ * `runtime` is just the `ServingRuntime`/`ClusterServingRuntime` name string
+ * KServe's own webhook resolves against `supportedModelFormats`.
+ *
+ * Coupling note (#984/#986 land in parallel in this same lexicon): this
+ * composite does not import either sibling. `runtime` is a plain name
+ * string (whatever `VllmServingRuntime` from #984 names its `ServingRuntime`
+ * object). `model` accepts either a raw `storageUri` string or a
+ * `{ storageUri }`-shaped object — the resolved-value shape `Model` from
+ * #986 is expected to return — matched structurally, not by import.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { InferenceService as InferenceServiceResource } from "../generated/index.js";
+function resolveStorageUri(model) {
+    return typeof model === "string" ? model : model.storageUri;
+}
+/**
+ * Create an InferenceService composite — a KServe `InferenceService`
+ * predictor referencing a `ServingRuntime` and a model `storageUri`, with
+ * autoscaling bounds and an optional canary traffic split.
+ *
+ * @example
+ * ```ts
+ * import { InferenceService } from "@intentius/chant-lexicon-k8s";
+ *
+ * const svc = InferenceService({
+ *   name: "llama-3-8b",
+ *   namespace: "serving",
+ *   model: "gs://my-models/llama-3-8b/v1",
+ *   runtime: "vllm-runtime",
+ *   modelFormat: "vLLM",
+ *   minReplicas: 1,
+ *   maxReplicas: 4,
+ *   scaleTarget: 8,
+ *   scaleMetric: "concurrency",
+ *   canaryTrafficPercent: 10,
+ * });
+ * ```
+ */
+export const InferenceService = Composite((props) => {
+    const { name, namespace, model, runtime, modelFormat, minReplicas, maxReplicas, scaleTarget, scaleMetric, canaryTrafficPercent, labels: extraLabels = {}, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        "app.kubernetes.io/component": "inference-service",
+        ...extraLabels,
+    };
+    const predictor = {
+        model: {
+            runtime,
+            storageUri: resolveStorageUri(model),
+            ...(modelFormat !== undefined && { modelFormat: { name: modelFormat } }),
+        },
+        ...(minReplicas !== undefined && { minReplicas }),
+        ...(maxReplicas !== undefined && { maxReplicas }),
+        ...(scaleTarget !== undefined && { scaleTarget }),
+        ...(scaleMetric !== undefined && { scaleMetric }),
+        ...(canaryTrafficPercent !== undefined && { canaryTrafficPercent }),
+    };
+    const inferenceService = new InferenceServiceResource(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: commonLabels,
+        },
+        spec: { predictor },
+    }, defs?.inferenceService));
+    return { inferenceService };
+}, "InferenceService");

package/dist/composites/irsa-service-account.js

@@ -0,0 +1,77 @@
+/**
+ * IrsaServiceAccount composite — ServiceAccount + IAM annotation + optional RBAC.
+ *
+ * @eks Creates a ServiceAccount with the `eks.amazonaws.com/role-arn`
+ * annotation for IAM Roles for Service Accounts (IRSA).
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, Role, RoleBinding } from "../generated/index.js";
+/**
+ * Create an IrsaServiceAccount composite — returns prop objects for
+ * a ServiceAccount with IRSA annotation, and optional Role + RoleBinding.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { IrsaServiceAccount } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { serviceAccount, role, roleBinding } = IrsaServiceAccount({
+ *   name: "app-sa",
+ *   iamRoleArn: "arn:aws:iam::123456789012:role/my-app-role",
+ *   rbacRules: [
+ *     { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+ *   ],
+ * });
+ * ```
+ */
+export const IrsaServiceAccount = Composite((props) => {
+    const { name, iamRoleArn, rbacRules, labels: extraLabels = {}, namespace, defaults: defs, } = props;
+    const roleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "service-account" },
+            annotations: {
+                "eks.amazonaws.com/role-arn": iamRoleArn,
+            },
+        },
+    }, defs?.serviceAccount));
+    const result = { serviceAccount };
+    if (rbacRules && rbacRules.length > 0) {
+        result.role = new Role(mergeDefaults({
+            metadata: {
+                name: roleName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            rules: rbacRules,
+        }, defs?.role));
+        result.roleBinding = new RoleBinding(mergeDefaults({
+            metadata: {
+                name: bindingName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            roleRef: {
+                apiGroup: "rbac.authorization.k8s.io",
+                kind: "Role",
+                name: roleName,
+            },
+            subjects: [
+                {
+                    kind: "ServiceAccount",
+                    name,
+                    ...(namespace && { namespace }),
+                },
+            ],
+        }, defs?.roleBinding));
+    }
+    return result;
+}, "IrsaServiceAccount");

package/dist/composites/member-defaults.js

@@ -0,0 +1,14 @@
+/**
+ * Types for the per-member `defaults` option on composites.
+ *
+ * Each member's override is checked against the constructor props of the
+ * generated class that builds it. The override is merged into the composite's
+ * own props by mergeDefaults, so objects are partial at every depth; arrays
+ * are appended, so their elements stay complete.
+ *
+ * The props come from the generated declaration file. `../generated` itself
+ * resolves to the runtime index.ts, whose classes take `Record<string, unknown>`.
+ * The lexicon build copies that declaration file next to the emitted types so
+ * the reference resolves for consumers too.
+ */
+export {};

package/dist/composites/metrics-server.js

@@ -0,0 +1,181 @@
+/**
+ * MetricsServer composite — Deployment + Service + ServiceAccount + RBAC + APIService.
+ *
+ * Deploys metrics-server for HPA pod CPU/memory metrics. metrics-server is not an
+ * EKS managed addon — it needs K8s workloads. Uses in-cluster RBAC only (no IRSA).
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Deployment, Service, ServiceAccount, ClusterRole, ClusterRoleBinding, APIService } from "../generated/index.js";
+/**
+ * Create a MetricsServer composite — returns prop objects for a Deployment,
+ * Service, ServiceAccount, ClusterRoles, ClusterRoleBindings, and APIService.
+ *
+ * @example
+ * ```ts
+ * import { MetricsServer } from "@intentius/chant-lexicon-k8s";
+ *
+ * const ms = MetricsServer({});
+ * ```
+ */
+export const MetricsServer = Composite((props) => {
+    const { name = "metrics-server", image = "registry.k8s.io/metrics-server/metrics-server:v0.7.2", replicas = 1, namespace = "kube-system", labels: extraLabels = {}, defaults: defs, } = props;
+    const saName = `${name}-sa`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const deployment = new Deployment(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+        },
+        spec: {
+            replicas,
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: {
+                    serviceAccountName: saName,
+                    containers: [
+                        {
+                            name,
+                            image,
+                            args: [
+                                "--cert-dir=/tmp",
+                                "--secure-port=10250",
+                                "--kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname",
+                                "--kubelet-use-node-status-port",
+                                "--metric-resolution=15s",
+                            ],
+                            ports: [{ containerPort: 10250, name: "https", protocol: "TCP" }],
+                            resources: {
+                                requests: { cpu: "100m", memory: "200Mi" },
+                                limits: { cpu: "100m", memory: "200Mi" },
+                            },
+                            livenessProbe: {
+                                httpGet: { path: "/livez", port: 10250, scheme: "HTTPS" },
+                                initialDelaySeconds: 0,
+                                periodSeconds: 10,
+                                failureThreshold: 3,
+                            },
+                            readinessProbe: {
+                                httpGet: { path: "/readyz", port: 10250, scheme: "HTTPS" },
+                                initialDelaySeconds: 20,
+                                periodSeconds: 10,
+                                failureThreshold: 3,
+                            },
+                            securityContext: {
+                                runAsNonRoot: true,
+                                readOnlyRootFilesystem: true,
+                                allowPrivilegeEscalation: false,
+                            },
+                            volumeMounts: [{ name: "tmp-dir", mountPath: "/tmp" }],
+                        },
+                    ],
+                    volumes: [{ name: "tmp-dir", emptyDir: {} }],
+                    priorityClassName: "system-cluster-critical",
+                },
+            },
+        },
+    }, defs?.deployment));
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: {
+                ...commonLabels,
+                "app.kubernetes.io/component": "metrics",
+                "kubernetes.io/cluster-service": "true",
+                "kubernetes.io/name": "Metrics-server",
+            },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            ports: [{ port: 443, targetPort: 10250, protocol: "TCP", name: "https" }],
+        },
+    }, defs?.service));
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+        },
+    }, defs?.serviceAccount));
+    const clusterRole = new ClusterRole(mergeDefaults({
+        metadata: {
+            name: `system:${name}`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: [
+            { apiGroups: [""], resources: ["pods", "nodes", "namespaces", "configmaps"], verbs: ["get", "list", "watch"] },
+            { apiGroups: [""], resources: ["nodes/metrics", "nodes/stats"], verbs: ["get"] },
+        ],
+    }, defs?.clusterRole));
+    const clusterRoleBinding = new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: `system:${name}`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: `system:${name}`,
+        },
+        subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+    }, defs?.clusterRoleBinding));
+    const aggregatedClusterRole = new ClusterRole(mergeDefaults({
+        metadata: {
+            name: `system:${name}-aggregated-reader`,
+            labels: {
+                ...commonLabels,
+                "app.kubernetes.io/component": "rbac",
+                "rbac.authorization.k8s.io/aggregate-to-admin": "true",
+                "rbac.authorization.k8s.io/aggregate-to-edit": "true",
+                "rbac.authorization.k8s.io/aggregate-to-view": "true",
+            },
+        },
+        rules: [
+            { apiGroups: ["metrics.k8s.io"], resources: ["pods", "nodes"], verbs: ["get", "list", "watch"] },
+        ],
+    }, defs?.aggregatedClusterRole));
+    const authDelegatorBinding = new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: `${name}:system:auth-delegator`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: "system:auth-delegator",
+        },
+        subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+    }, defs?.authDelegatorBinding));
+    const apiService = new APIService(mergeDefaults({
+        apiVersion: "apiregistration.k8s.io/v1",
+        kind: "APIService",
+        metadata: {
+            name: "v1beta1.metrics.k8s.io",
+            labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+        },
+        spec: {
+            service: { name, namespace },
+            group: "metrics.k8s.io",
+            version: "v1beta1",
+            insecureSkipTLSVerify: true,
+            groupPriorityMinimum: 100,
+            versionPriority: 100,
+        },
+    }, defs?.apiService));
+    return {
+        deployment,
+        service,
+        serviceAccount,
+        clusterRole,
+        clusterRoleBinding,
+        aggregatedClusterRole,
+        authDelegatorBinding,
+        apiService,
+    };
+}, "MetricsServer");

package/dist/composites/model.js

@@ -0,0 +1,92 @@
+/**
+ * Model composite — resolves a model artifact reference to a KServe
+ * `storageUri` (+ optional warm-cache PVC), keyed by `(id, version)`.
+ *
+ * This is the FSx-warm-cache equivalent from the Netflix serving yardstick
+ * (see epic #982): a small, spec-true resolver that InferenceService (#985)
+ * consumes for its predictor's model reference. It does not itself emit an
+ * InferenceService or ServingRuntime — those are #984/#985's job.
+ *
+ * `version` is required so every resolved `storageUri` is pinned: the
+ * version is always appended as the trailing path segment, whether the
+ * default `id`-derived path is used or `uri` overrides it. This keeps the
+ * output stable for the unpinned-model lint rule (#988).
+ *
+ * `Model` itself is a plain resolver — a resolved value object, per the
+ * composite conventions — rather than a `Composite`, because its primary
+ * output (`storageUri`) is a string, not a Declarable; a `Composite`
+ * factory's members must all be Declarables. The optional cache PVC is
+ * built through an internal `Composite` so it gets the same bookkeeping
+ * (provenance, defaults-merging) as every other emitted resource.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { PersistentVolumeClaim } from "../generated/index.js";
+const STORAGE_SCHEME = {
+    hf: "hf",
+    gcs: "gs",
+    s3: "s3",
+    pvc: "pvc",
+};
+/**
+ * Resolve a model artifact's `{ id, version, source, uri }` to a pinned
+ * KServe `storageUri` string.
+ */
+export function resolveModelStorageUri(props) {
+    const { id, version, source, uri } = props;
+    const scheme = STORAGE_SCHEME[source];
+    const path = uri ?? id;
+    return `${scheme}://${path}/${version}`;
+}
+const ModelCachePvc = Composite((props) => {
+    const { id, version, storageClass, size, defaults } = props;
+    const pvc = new PersistentVolumeClaim(mergeDefaults({
+        metadata: {
+            name: `${id}-${version}`,
+            labels: {
+                "app.kubernetes.io/name": id,
+                "app.kubernetes.io/managed-by": "chant",
+                "app.kubernetes.io/component": "model-cache",
+            },
+        },
+        spec: {
+            accessModes: ["ReadWriteMany"],
+            storageClassName: storageClass,
+            resources: { requests: { storage: size } },
+        },
+    }, defaults));
+    return { pvc };
+}, "ModelCachePvc");
+/**
+ * Resolve a model artifact `{ id, version, source, uri, cache }` to a pinned
+ * `storageUri`, with an optional warm-cache PVC.
+ *
+ * @example
+ * ```ts
+ * import { Model } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageUri, cache } = Model({
+ *   id: "llama-3-8b-instruct",
+ *   version: "2024-07-01",
+ *   source: "gcs",
+ *   uri: "my-models-bucket/llama-3-8b-instruct",
+ *   cache: { storageClass: "premium-rwo", size: "200Gi" },
+ * });
+ * ```
+ */
+export function Model(props) {
+    const { id, version, cache, defaults } = props;
+    const storageUri = resolveModelStorageUri(props);
+    const cachePvc = cache
+        ? ModelCachePvc({
+            id,
+            version,
+            storageClass: cache.storageClass,
+            size: cache.size,
+            defaults: defaults?.cachePvc,
+        }).pvc
+        : undefined;
+    return {
+        storageUri,
+        ...(cachePvc && { cache: cachePvc }),
+    };
+}