[Fix] Resolve int32 overflow by having the calculation in int64 and c…

[justinyeh1995]

…ap it if the count is over math.MaxInt32

Why are these changes needed?

The CalculateMaxReplicas function did not guard against integer overflow, which could result in an incorrect value for Status.MaxWorkerReplicas, as reported in #4153.

$ kubectl get raycluster raycluster-kuberay -o yaml
apiVersion: ray.io/v1
kind: RayCluster
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"ray.io/v1","kind":"RayCluster","metadata":{"annotations":{},"name":"raycluster-kuberay","namespace":"default"},"spec":{"headGroupSpec":{"rayStartParams":{},"template":{"spec":{"containers":[{"image":"rayproject/ray:2.46.0","name":"ray-head","ports":[{"containerPort":6379,"name":"gcs-server"},{"containerPort":8265,"name":"dashboard"},{"containerPort":10001,"name":"client"}],"resources":{"limits":{"cpu":1,"memory":"2G"},"requests":{"cpu":1,"memory":"2G"}}}],"schedulerName":"default-scheduler"}}},"rayVersion":"2.46.0","workerGroupSpecs":[{"groupName":"workergroup","minReplicas":3,"numOfHosts":4,"rayStartParams":{},"replicas":1,"template":{"spec":{"containers":[{"image":"rayproject/ray:2.46.0","name":"ray-worker","resources":{"limits":{"cpu":1,"memory":"1G"},"requests":{"cpu":1,"memory":"1G"}}}]}}}]}}
  creationTimestamp: "2025-10-28T16:05:15Z"
  generation: 1
  name: raycluster-kuberay
  namespace: default
  resourceVersion: "13168"
  uid: c83e5bd6-c5ee-4a22-b615-341fee75725a
....
status:
  availableWorkerReplicas: 12
  conditions:
  - lastTransitionTime: "2025-10-28T16:05:36Z"
    message: ""
    reason: HeadPodRunningAndReady
    status: "True"
    type: HeadPodReady
  - lastTransitionTime: "2025-10-28T16:06:43Z"
    message: All Ray Pods are ready for the first time
    reason: AllPodRunningAndReadyFirstTime
    status: "True"
    type: RayClusterProvisioned
  - lastTransitionTime: "2025-10-28T16:05:36Z"
    message: ""
    reason: RayClusterSuspended
    status: "False"
    type: RayClusterSuspended
  - lastTransitionTime: "2025-10-28T16:05:36Z"
    message: ""
    reason: RayClusterSuspending
    status: "False"
    type: RayClusterSuspending
  desiredCPU: "5"
  desiredGPU: "0"
  desiredMemory: 6G
  desiredTPU: "0"
  desiredWorkerReplicas: 12
  endpoints:
    client: "10001"
    dashboard: "8265"
    gcs-server: "6379"
    metrics: "8080"
  head:
    podIP: 10.244.0.34
    podName: raycluster-kuberay-head-g5wzm
    serviceIP: 10.244.0.34
    serviceName: raycluster-kuberay-head-svc
  lastUpdateTime: "2025-10-28T16:06:43Z"
  maxWorkerReplicas: -4                <---- overflowed
  minWorkerReplicas: 12
  observedGeneration: 1
  readyWorkerReplicas: 12
  state: ready
  stateTransitionTimes:
    ready: "2025-10-28T16:06:43Z"

After the fix, the maximum replicas now caps at 2,147,483,647.

$kubectl get raycluster raycluster-kuberay -o yaml

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"ray.io/v1","kind":"RayCluster","metadata":{"annotations":{},"name":"raycluster-kuberay","namespace":"default"},"spec":{"headGroupSpec":{"rayStartParams":{},"template":{"spec":{"containers":[{"image":"rayproject/ray:2.46.0","name":"ray-head","ports":[{"containerPort":6379,"name":"gcs-server"},{"containerPort":8265,"name":"dashboard"},{"containerPort":10001,"name":"client"}],"resources":{"limits":{"cpu":1,"memory":"2G"},"requests":{"cpu":1,"memory":"2G"}}}],"schedulerName":"default-scheduler"}}},"rayVersion":"2.46.0","workerGroupSpecs":[{"groupName":"workergroup","minReplicas":3,"numOfHosts":4,"rayStartParams":{},"replicas":1,"template":{"spec":{"containers":[{"image":"rayproject/ray:2.46.0","name":"ray-worker","resources":{"limits":{"cpu":1,"memory":"1G"},"requests":{"cpu":1,"memory":"1G"}}}]}}}]}}
  creationTimestamp: "2025-10-30T10:53:15Z"
  generation: 1
  name: raycluster-kuberay
  namespace: default
  resourceVersion: "2885229"
  uid: 1be0d901-2c48-45e1-a3ef-fbfc6f4f6d45
spec:
  headGroupSpec:
    rayStartParams: {}
    template:
      spec:
        containers:
        - image: rayproject/ray:2.46.0
          name: ray-head
          ports:
          - containerPort: 6379
            name: gcs-server
            protocol: TCP
          - containerPort: 8265
            name: dashboard
            protocol: TCP
          - containerPort: 10001
            name: client
            protocol: TCP
          resources:
            limits:
              cpu: 1
              memory: 2G
            requests:
              cpu: 1
              memory: 2G
        schedulerName: default-scheduler
  rayVersion: 2.46.0
  workerGroupSpecs:
  - groupName: workergroup
    maxReplicas: 2147483647.               <---- caps at 2147483647
    minReplicas: 3
    numOfHosts: 4
    rayStartParams: {}
    replicas: 1
    template:
      spec:
        containers:
        - image: rayproject/ray:2.46.0
          name: ray-worker
          resources:
            limits:
              cpu: 1
              memory: 1G
            requests:
              cpu: 1
              memory: 1G

Related issue number

Closes #4153

Checks

• I've made sure the tests are passing.
• Testing Strategy
  • Unit tests
  • Manual tests
  • This PR is not tested :(

[justinyeh1995]

@win5923 @Future-Outlier I somehow could not add you as reviewers, so I will ping you here instead. Please take a look. Thanks!

[win5923]

LGTM, do we also need to check overflow for CalculateMinReplicas?
@Future-Outlier

[troychiu]

Can we do sth like

kuberay/ray-operator/controllers/ray/utils/util.go

Line 249 in 2acc219

func SafeUint64ToInt64(n uint64) int64 {

to avoid nosec?

[justinyeh1995]

Can we do sth like

kuberay/ray-operator/controllers/ray/utils/util.go

Line 249 in 2acc219

func SafeUint64ToInt64(n uint64) int64 {

to avoid nosec?

I think we can.

Say we have another function

func SafeInt64ToInt32(n int64) int32 

we can change the logic into something like this

func CalculateMaxReplicas(cluster *rayv1.RayCluster) int32 {
	count := int64(0)
	for _, nodeGroup := range cluster.Spec.WorkerGroupSpecs {
		if nodeGroup.Suspend != nil && *nodeGroup.Suspend {
			continue
		}
		count += int64(*nodeGroup.MaxReplicas) * int64(nodeGroup.NumOfHosts)

		// stop the calculation if an overflow happens
		if count > math.MaxInt32 {
			break
		}
	}

	return SafeInt64ToInt32(count)

Do you think it will be a reasonable way of approaching it?

[troychiu]

yeah IMO that's better

[400Ping]

LGTM

[justinyeh1995]

yeah IMO that's better

Sounds good. I will update this section accordingly.

[troychiu]

You may need a minimum check to avoid lint error. Also, could you follow the naming convention for the function?

[justinyeh1995]

Thanks for the feedback! I'll add the minimum check and see if it resolves the lint error, and rename the function to SafeInt64ToInt32 as well.

[troychiu]

Do we still need this early return if we will do a safe type casting?

[justinyeh1995]

I think that's a decision to be made. The early return is a non-critical optimization
but not as clean as Option 1. I'm happy to go with either way.

Option 1

func CalculateMaxReplicas(cluster *rayv1.RayCluster) int32 {
	count := int64(0)
	for _, nodeGroup := range cluster.Spec.WorkerGroupSpecs {
		if nodeGroup.Suspend != nil && *nodeGroup.Suspend {
			continue
		}
		count += int64(*nodeGroup.MaxReplicas) * int64(nodeGroup.NumOfHosts)
	}
	return SafeInt64ToInt32(count)

Option 2

func CalculateMaxReplicas(cluster *rayv1.RayCluster) int32 {
	count := int64(0)
	for _, nodeGroup := range cluster.Spec.WorkerGroupSpecs {
		if nodeGroup.Suspend != nil && *nodeGroup.Suspend {
			continue
		}
		count += int64(*nodeGroup.MaxReplicas) * int64(nodeGroup.NumOfHosts)

		// early return if an overflow happens
		if count > math.MaxInt32 {
			return math.MaxInt32
		}
	}
	return SafeInt64ToInt32(count)
}

[troychiu]

I'll go for option 1 but if others think option 2 is better then I am fine with it.

[justinyeh1995]

I see. Now with the SafeInt64ToInt32 doing the overflow/underflow prevention. I think Option 1 is much cleaner.

[troychiu]

Thank you!