@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/composites/ray-cluster.js

@@ -0,0 +1,378 @@
+/**
+ * RayCluster composite — KubeRay RayCluster CR + surrounding K8s infra.
+ *
+ * Encodes production defaults for running Ray on Kubernetes:
+ * - NetworkPolicy with podSelector rules (avoids GKE pod CIDR mismatch)
+ * - PodDisruptionBudget on the head (minAvailable: 1)
+ * - preStop: ray stop hooks + terminationGracePeriodSeconds: 120 on all pods
+ * - ServiceAccount for the head + optional autoscaler ClusterRole/CRB
+ * - Optional shared ReadWriteMany PVC for training data (Filestore/EFS)
+ * - Optional GCS spillover env var for object store spill-to-GCS
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, ClusterRole, ClusterRoleBinding, NetworkPolicy, PodDisruptionBudget, PersistentVolumeClaim, Service, RayCluster as RayClusterResource, } from "../generated/index.js";
+// ── Internal helpers ─────────────────────────────────────────────────────────
+/** Parse a CPU string to a numeric count for --num-cpus. "2" → "2", "500m" → "0.5". */
+function cpuToNumCpus(cpu) {
+    if (cpu.endsWith("m")) {
+        const millis = parseInt(cpu.slice(0, -1), 10);
+        return String(millis / 1000);
+    }
+    return cpu;
+}
+/** Build resource requests/limits. GPU count maps to nvidia.com/gpu. */
+function buildResources(spec) {
+    const base = { cpu: spec.cpu, memory: spec.memory };
+    if (spec.gpu)
+        base["nvidia.com/gpu"] = String(spec.gpu);
+    return { requests: { ...base }, limits: { ...base } };
+}
+/** Shared volume list for a pod (dshm + optional PVC). */
+function buildPodVolumes(shmSize, pvcName) {
+    const vols = [
+        { name: "dshm", emptyDir: { medium: "Memory", sizeLimit: shmSize } },
+    ];
+    if (pvcName) {
+        vols.push({ name: "shared-data", persistentVolumeClaim: { claimName: pvcName } });
+    }
+    return vols;
+}
+/** Shared volume mounts for a container (dshm + optional shared-data). */
+function buildVolumeMounts(mountPath) {
+    const mounts = [
+        { name: "dshm", mountPath: "/dev/shm" },
+    ];
+    if (mountPath) {
+        mounts.push({ name: "shared-data", mountPath });
+    }
+    return mounts;
+}
+/**
+ * Extract the Ray version from a container image reference.
+ * Used to populate spec.rayVersion on KubeRay CRs so the autoscaler
+ * pulls an image that matches the running Ray version.
+ *
+ * "rayproject/ray:2.40.0-py310-cpu" → "2.40.0"
+ * "rayproject/ray:latest"           → undefined
+ */
+function extractRayVersion(image) {
+    const tag = image.includes(":") ? image.split(":").pop() : image;
+    const m = /^([0-9]+\.[0-9]+\.[0-9]+)/.exec(tag);
+    return m ? m[1] : undefined;
+}
+// ── Shared cluster spec builder (used by RayJob and RayService too) ──────────
+/**
+ * Build headGroupSpec and workerGroupSpecs for a KubeRay CR.
+ * Exported for use in RayJob and RayService composites.
+ */
+export function buildRayClusterParts(cluster, saName, spilloverBucket, pvcName, mountPath) {
+    const { image, head, workerGroups } = cluster;
+    const rayVersion = extractRayVersion(image);
+    const shmSize = head.shmSize ?? "2Gi";
+    const resolvedMountPath = pvcName ? (mountPath ?? "/mnt/ray-data") : undefined;
+    // ── Head container ─────────────────────────────────────────────────────
+    const headEnv = [...(head.env ?? [])];
+    if (spilloverBucket) {
+        headEnv.push({
+            name: "RAY_object_spilling_config",
+            value: JSON.stringify({
+                type: "smart_open",
+                params: { uri: `gs://${spilloverBucket}/spill` },
+            }),
+        });
+    }
+    const headContainer = {
+        name: "ray-head",
+        image,
+        resources: buildResources(head.resources),
+        ports: [
+            { containerPort: 6379, name: "gcs-server" },
+            { containerPort: 8265, name: "dashboard" },
+            { containerPort: 10001, name: "client" },
+            { containerPort: 8080, name: "metrics" },
+        ],
+        ...(headEnv.length > 0 && { env: headEnv }),
+        volumeMounts: buildVolumeMounts(resolvedMountPath),
+        lifecycle: { preStop: { exec: { command: ["ray", "stop"] } } },
+    };
+    const headGroupSpec = {
+        rayStartParams: {
+            ...(head.reserveHead && { "num-cpus": "0" }),
+            ...(head.rayStartParams ?? {}),
+        },
+        template: {
+            spec: {
+                serviceAccountName: saName,
+                terminationGracePeriodSeconds: 120,
+                containers: [headContainer],
+                volumes: buildPodVolumes(shmSize, pvcName),
+            },
+        },
+    };
+    // ── Worker groups ───────────────────────────────────────────────────────
+    const workerGroupSpecs = workerGroups.map((group) => {
+        // Always inject the GCS reconnect timeout — default 60s terminates workers
+        // when the head is briefly unavailable (eviction, rolling restart). 600s gives
+        // workers 10 minutes to wait for head recovery before self-terminating.
+        const workerEnv = [
+            { name: "RAY_gcs_rpc_server_reconnect_timeout_s", value: "600" },
+            ...(group.env ?? []),
+        ];
+        const workerContainer = {
+            name: "ray-worker",
+            image,
+            resources: buildResources(group.resources),
+            env: workerEnv,
+            volumeMounts: buildVolumeMounts(resolvedMountPath),
+            lifecycle: { preStop: { exec: { command: ["ray", "stop"] } } },
+        };
+        const rayStartParams = {
+            "num-cpus": cpuToNumCpus(group.resources.cpu),
+            ...(group.resources.gpu ? { "num-gpus": String(group.resources.gpu) } : {}),
+            ...(group.rayStartParams ?? {}),
+        };
+        const podSpec = {
+            terminationGracePeriodSeconds: 120,
+            containers: [workerContainer],
+            volumes: buildPodVolumes("2Gi", pvcName),
+        };
+        if (group.gpuTolerations) {
+            podSpec.tolerations = [
+                { key: "nvidia.com/gpu", operator: "Exists", effect: "NoSchedule" },
+            ];
+        }
+        return {
+            groupName: group.groupName,
+            replicas: group.replicas,
+            minReplicas: group.minReplicas ?? group.replicas,
+            maxReplicas: group.maxReplicas ?? group.replicas,
+            idleTimeoutSeconds: group.idleTimeoutSeconds ?? 60,
+            rayStartParams,
+            template: { spec: podSpec },
+        };
+    });
+    return { headGroupSpec, workerGroupSpecs, rayVersion };
+}
+// ── NetworkPolicy builder ─────────────────────────────────────────────────────
+/**
+ * Build a NetworkPolicy for a Ray cluster.
+ * Uses podSelector-only rules for intra-cluster traffic to avoid GKE pod CIDR
+ * mismatch (GKE secondary pod CIDRs differ from declared subnet CIDRs).
+ * GCS egress uses ipBlock excluding RFC1918 to allow Google APIs while
+ * blocking internal lateral movement.
+ */
+export function buildRayNetworkPolicy(name, namespace, commonLabels, exposeDashboard, defOverride) {
+    const clusterSelector = { matchLabels: { "ray.io/cluster-name": name } };
+    const rayPorts = [
+        { port: 6379, protocol: "TCP" },
+        { port: 10001, protocol: "TCP" },
+        { port: 10002, protocol: "TCP" },
+        { port: 8080, protocol: "TCP" },
+        // Ephemeral gRPC ports for worker-to-worker communication (requires K8s 1.25+)
+        { port: 32768, endPort: 60999, protocol: "TCP" },
+    ];
+    const ingressRules = [
+        {
+            from: [{ podSelector: clusterSelector }],
+            ports: [...rayPorts, { port: 8265, protocol: "TCP" }],
+        },
+    ];
+    // When the dashboard is externally exposed, allow ingress from outside the cluster
+    if (exposeDashboard) {
+        ingressRules.push({ ports: [{ port: 8265, protocol: "TCP" }] });
+    }
+    const egressRules = [
+        // Intra-cluster Ray traffic
+        {
+            to: [{ podSelector: clusterSelector }],
+            ports: [...rayPorts, { port: 8265, protocol: "TCP" }],
+        },
+        // DNS — required for head service name resolution
+        {
+            ports: [
+                { port: 53, protocol: "UDP" },
+                { port: 53, protocol: "TCP" },
+            ],
+        },
+        // GCS / Artifact Registry HTTPS — ipBlock excludes RFC1918 to prevent
+        // lateral movement while allowing Google API endpoints
+        {
+            to: [
+                {
+                    ipBlock: {
+                        cidr: "0.0.0.0/0",
+                        except: ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
+                    },
+                },
+            ],
+            ports: [{ port: 443, protocol: "TCP" }],
+        },
+    ];
+    return new NetworkPolicy(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "network-policy" },
+        },
+        spec: {
+            podSelector: clusterSelector,
+            policyTypes: ["Ingress", "Egress"],
+            ingress: ingressRules,
+            egress: egressRules,
+        },
+    }, defOverride));
+}
+// ── Composite ────────────────────────────────────────────────────────────────
+/**
+ * Create a RayCluster composite — returns a KubeRay RayCluster CR and the
+ * surrounding K8s resources needed for a production Ray cluster.
+ *
+ * @example
+ * ```ts
+ * import { RayCluster } from "@intentius/chant-lexicon-k8s";
+ *
+ * const ray = RayCluster({
+ *   name: "ray",
+ *   namespace: "ray-system",
+ *   cluster: {
+ *     image: "us-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+ *     head: { resources: { cpu: "2", memory: "8Gi" } },
+ *     workerGroups: [
+ *       { groupName: "cpu", replicas: 2, minReplicas: 1, maxReplicas: 8,
+ *         resources: { cpu: "2", memory: "4Gi" } },
+ *     ],
+ *   },
+ *   enableAutoscaler: true,
+ *   spilloverBucket: "my-ray-spill",
+ * });
+ * ```
+ */
+export const RayCluster = Composite((props) => {
+    const { name, namespace, cluster, sharedStorage, enableAutoscaler = false, spilloverBucket, exposeDashboard = false, labels: extraLabels = {}, defaults: defs, } = props;
+    const saName = `${name}-head`;
+    const pvcName = sharedStorage ? `${name}-shared` : undefined;
+    const mountPath = sharedStorage?.mountPath;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        "app.kubernetes.io/component": "ray",
+        ...extraLabels,
+    };
+    // -- ServiceAccount --
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "service-account" },
+        },
+    }, defs?.serviceAccount));
+    // -- Autoscaler RBAC (optional) --
+    const clusterRole = enableAutoscaler ? new ClusterRole(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: [
+            {
+                apiGroups: [""],
+                resources: ["pods"],
+                verbs: ["get", "list", "watch", "create", "delete", "patch"],
+            },
+            {
+                apiGroups: [""],
+                resources: ["pods/status"],
+                verbs: ["get"],
+            },
+            {
+                apiGroups: ["ray.io"],
+                resources: ["rayclusters"],
+                verbs: ["get", "list", "patch"],
+            },
+        ],
+    }, defs?.clusterRole)) : undefined;
+    const clusterRoleBinding = enableAutoscaler ? new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: `${name}-autoscaler`,
+        },
+        subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+    }, defs?.clusterRoleBinding)) : undefined;
+    // -- NetworkPolicy --
+    const networkPolicy = buildRayNetworkPolicy(name, namespace, commonLabels, exposeDashboard, defs?.networkPolicy);
+    // -- PodDisruptionBudget (head) --
+    const pdb = new PodDisruptionBudget(mergeDefaults({
+        metadata: {
+            name: `${name}-head`,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+        },
+        spec: {
+            minAvailable: 1,
+            selector: {
+                matchLabels: {
+                    "ray.io/cluster-name": name,
+                    "ray.io/node-type": "head",
+                },
+            },
+        },
+    }, defs?.pdb));
+    // -- Shared PVC (optional) --
+    const pvc = sharedStorage ? new PersistentVolumeClaim(mergeDefaults({
+        metadata: {
+            name: pvcName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+        },
+        spec: {
+            accessModes: ["ReadWriteMany"],
+            storageClassName: sharedStorage.storageClass,
+            resources: { requests: { storage: sharedStorage.size } },
+        },
+    }, defs?.pvc)) : undefined;
+    // -- Dashboard LoadBalancer Service (optional) --
+    const dashboardService = exposeDashboard ? new Service(mergeDefaults({
+        metadata: {
+            name: `${name}-dashboard`,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "dashboard" },
+        },
+        spec: {
+            type: "LoadBalancer",
+            selector: {
+                "ray.io/cluster-name": name,
+                "ray.io/node-type": "head",
+            },
+            ports: [{ port: 8265, targetPort: 8265, protocol: "TCP", name: "dashboard" }],
+        },
+    }, defs?.dashboardService)) : undefined;
+    // -- RayCluster CR --
+    const { headGroupSpec, workerGroupSpecs, rayVersion } = buildRayClusterParts(cluster, saName, spilloverBucket, pvcName, mountPath);
+    const rayCluster = new RayClusterResource(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: commonLabels,
+        },
+        spec: {
+            ...(rayVersion && { rayVersion }),
+            ...(enableAutoscaler && { enableInTreeAutoscaling: true }),
+            headGroupSpec,
+            workerGroupSpecs,
+        },
+    }, defs?.rayCluster));
+    return {
+        serviceAccount,
+        ...(clusterRole && { clusterRole }),
+        ...(clusterRoleBinding && { clusterRoleBinding }),
+        networkPolicy,
+        pdb,
+        ...(pvc && { pvc }),
+        ...(dashboardService && { dashboardService }),
+        rayCluster,
+    };
+}, "RayCluster");

package/dist/composites/ray-job.js

@@ -0,0 +1,136 @@
+/**
+ * RayJob composite — KubeRay RayJob CR + surrounding K8s infra.
+ *
+ * RayJob spins up an ephemeral Ray cluster, runs a single entrypoint command,
+ * then tears the cluster down. Ideal for batch training pipelines.
+ *
+ * Encodes the same production defaults as RayCluster (NetworkPolicy,
+ * preStop hooks, optional shared PVC, optional autoscaler RBAC).
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, ClusterRole, ClusterRoleBinding, PersistentVolumeClaim, RayJob as RayJobResource, } from "../generated/index.js";
+import { buildRayClusterParts, buildRayNetworkPolicy, } from "./ray-cluster.js";
+/**
+ * Create a RayJob composite — ephemeral Ray cluster for a single batch job.
+ *
+ * @example
+ * ```ts
+ * import { RayJob } from "@intentius/chant-lexicon-k8s";
+ *
+ * const job = RayJob({
+ *   name: "train-resnet",
+ *   namespace: "ray-system",
+ *   entrypoint: "python train.py --epochs 50",
+ *   cluster: {
+ *     image: "us-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+ *     head: { resources: { cpu: "2", memory: "8Gi" } },
+ *     workerGroups: [
+ *       { groupName: "gpu", replicas: 4,
+ *         resources: { cpu: "8", memory: "32Gi", gpu: 1 },
+ *         gpuTolerations: true },
+ *     ],
+ *   },
+ *   spilloverBucket: "my-ray-spill",
+ * });
+ * ```
+ */
+export const RayJob = Composite((props) => {
+    const { name, namespace, entrypoint, cluster, runtimeEnvYAML, shutdownAfterJobFinishes = true, ttlSecondsAfterFinished = 300, sharedStorage, enableAutoscaler = false, spilloverBucket, labels: extraLabels = {}, defaults: defs, } = props;
+    const saName = `${name}-head`;
+    const pvcName = sharedStorage ? `${name}-shared` : undefined;
+    const mountPath = sharedStorage?.mountPath;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        "app.kubernetes.io/component": "ray",
+        ...extraLabels,
+    };
+    // -- ServiceAccount --
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "service-account" },
+        },
+    }, defs?.serviceAccount));
+    // -- Autoscaler RBAC (optional) --
+    const clusterRole = enableAutoscaler ? new ClusterRole(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: [
+            {
+                apiGroups: [""],
+                resources: ["pods"],
+                verbs: ["get", "list", "watch", "create", "delete", "patch"],
+            },
+            {
+                apiGroups: [""],
+                resources: ["pods/status"],
+                verbs: ["get"],
+            },
+            {
+                apiGroups: ["ray.io"],
+                resources: ["rayjobs"],
+                verbs: ["get", "list", "patch"],
+            },
+        ],
+    }, defs?.clusterRole)) : undefined;
+    const clusterRoleBinding = enableAutoscaler ? new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: `${name}-autoscaler`,
+        },
+        subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+    }, defs?.clusterRoleBinding)) : undefined;
+    // -- NetworkPolicy --
+    const networkPolicy = buildRayNetworkPolicy(name, namespace, commonLabels, false, defs?.networkPolicy);
+    // -- Shared PVC (optional) --
+    const pvc = sharedStorage ? new PersistentVolumeClaim(mergeDefaults({
+        metadata: {
+            name: pvcName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+        },
+        spec: {
+            accessModes: ["ReadWriteMany"],
+            storageClassName: sharedStorage.storageClass,
+            resources: { requests: { storage: sharedStorage.size } },
+        },
+    }, defs?.pvc)) : undefined;
+    // -- RayJob CR --
+    const { headGroupSpec, workerGroupSpecs, rayVersion } = buildRayClusterParts(cluster, saName, spilloverBucket, pvcName, mountPath);
+    const rayJob = new RayJobResource(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: commonLabels,
+        },
+        spec: {
+            entrypoint,
+            ...(runtimeEnvYAML && { runtimeEnvYAML }),
+            shutdownAfterJobFinishes,
+            ttlSecondsAfterFinished,
+            rayClusterSpec: {
+                ...(rayVersion && { rayVersion }),
+                ...(enableAutoscaler && { enableInTreeAutoscaling: true }),
+                headGroupSpec,
+                workerGroupSpecs,
+            },
+        },
+    }, defs?.rayJob));
+    return {
+        serviceAccount,
+        ...(clusterRole && { clusterRole }),
+        ...(clusterRoleBinding && { clusterRoleBinding }),
+        networkPolicy,
+        ...(pvc && { pvc }),
+        rayJob,
+    };
+}, "RayJob");

package/dist/composites/ray-service.js

@@ -0,0 +1,178 @@
+/**
+ * RayService composite — KubeRay RayService CR + surrounding K8s infra.
+ *
+ * RayService manages a persistent Ray Serve HTTP endpoint with zero-downtime
+ * blue-green upgrades. Ideal for online inference and serving workloads.
+ *
+ * Encodes the same production defaults as RayCluster (NetworkPolicy, preStop
+ * hooks, PDB, optional shared PVC, optional autoscaler RBAC) plus a
+ * LoadBalancer Service exposing the Serve HTTP endpoint on port 8000.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, ClusterRole, ClusterRoleBinding, PodDisruptionBudget, PersistentVolumeClaim, Service, RayService as RayServiceResource, } from "../generated/index.js";
+import { buildRayClusterParts, buildRayNetworkPolicy, } from "./ray-cluster.js";
+/**
+ * Create a RayService composite — persistent Ray Serve endpoint with
+ * zero-downtime blue-green upgrades.
+ *
+ * @example
+ * ```ts
+ * import { RayService } from "@intentius/chant-lexicon-k8s";
+ *
+ * const svc = RayService({
+ *   name: "inference",
+ *   namespace: "ray-system",
+ *   serveConfigV2: `
+ *     applications:
+ *       - name: classifier
+ *         import_path: app:deployment
+ *         deployments:
+ *           - name: Classifier
+ *             num_replicas: 2
+ *   `,
+ *   cluster: {
+ *     image: "us-docker.pkg.dev/my-project/ray-images/ray:2.40.0",
+ *     head: { resources: { cpu: "2", memory: "8Gi" } },
+ *     workerGroups: [
+ *       { groupName: "gpu", replicas: 2,
+ *         resources: { cpu: "4", memory: "16Gi", gpu: 1 },
+ *         gpuTolerations: true },
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export const RayService = Composite((props) => {
+    const { name, namespace, serveConfigV2, cluster, sharedStorage, enableAutoscaler = false, spilloverBucket, labels: extraLabels = {}, defaults: defs, } = props;
+    const saName = `${name}-head`;
+    const pvcName = sharedStorage ? `${name}-shared` : undefined;
+    const mountPath = sharedStorage?.mountPath;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        "app.kubernetes.io/component": "ray",
+        ...extraLabels,
+    };
+    // -- ServiceAccount --
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "service-account" },
+        },
+    }, defs?.serviceAccount));
+    // -- Autoscaler RBAC (optional) --
+    const clusterRole = enableAutoscaler ? new ClusterRole(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: [
+            {
+                apiGroups: [""],
+                resources: ["pods"],
+                verbs: ["get", "list", "watch", "create", "delete", "patch"],
+            },
+            {
+                apiGroups: [""],
+                resources: ["pods/status"],
+                verbs: ["get"],
+            },
+            {
+                apiGroups: ["ray.io"],
+                resources: ["rayservices"],
+                verbs: ["get", "list", "patch"],
+            },
+        ],
+    }, defs?.clusterRole)) : undefined;
+    const clusterRoleBinding = enableAutoscaler ? new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: `${name}-autoscaler`,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: `${name}-autoscaler`,
+        },
+        subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+    }, defs?.clusterRoleBinding)) : undefined;
+    // -- NetworkPolicy --
+    // RayService exposes port 8000 (Serve HTTP) externally via LoadBalancer,
+    // so we allow ingress from outside the cluster on that port.
+    const networkPolicy = buildRayNetworkPolicy(name, namespace, commonLabels, false, defs?.networkPolicy);
+    // -- PodDisruptionBudget (head) --
+    const pdb = new PodDisruptionBudget(mergeDefaults({
+        metadata: {
+            name: `${name}-head`,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+        },
+        spec: {
+            minAvailable: 1,
+            selector: {
+                matchLabels: {
+                    "ray.io/cluster-name": name,
+                    "ray.io/node-type": "head",
+                },
+            },
+        },
+    }, defs?.pdb));
+    // -- Shared PVC (optional) --
+    const pvc = sharedStorage ? new PersistentVolumeClaim(mergeDefaults({
+        metadata: {
+            name: pvcName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+        },
+        spec: {
+            accessModes: ["ReadWriteMany"],
+            storageClassName: sharedStorage.storageClass,
+            resources: { requests: { storage: sharedStorage.size } },
+        },
+    }, defs?.pvc)) : undefined;
+    // -- Ray Serve LoadBalancer Service --
+    const serveService = new Service(mergeDefaults({
+        metadata: {
+            name: `${name}-serve`,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "serve" },
+        },
+        spec: {
+            type: "LoadBalancer",
+            selector: {
+                "ray.io/cluster-name": name,
+                "ray.io/node-type": "head",
+            },
+            ports: [{ port: 8000, targetPort: 8000, protocol: "TCP", name: "serve" }],
+        },
+    }, defs?.serveService));
+    // -- RayService CR --
+    const { headGroupSpec, workerGroupSpecs, rayVersion } = buildRayClusterParts(cluster, saName, spilloverBucket, pvcName, mountPath);
+    const rayService = new RayServiceResource(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: commonLabels,
+        },
+        spec: {
+            serveConfigV2,
+            rayClusterConfig: {
+                ...(rayVersion && { rayVersion }),
+                ...(enableAutoscaler && { enableInTreeAutoscaling: true }),
+                headGroupSpec,
+                workerGroupSpecs,
+            },
+        },
+    }, defs?.rayService));
+    return {
+        serviceAccount,
+        ...(clusterRole && { clusterRole }),
+        ...(clusterRoleBinding && { clusterRoleBinding }),
+        networkPolicy,
+        pdb,
+        ...(pvc && { pvc }),
+        serveService,
+        rayService,
+    };
+}, "RayService");