KubeRay CRD API reference

This page is the generated field reference for the ray.io/v1 custom resource definitions. It covers RayCluster, RayCronJob, RayJob, and RayService, along with the supporting types their fields refer to.

The fields are those of KubeRay v1.7.0. Fields added to KubeRay after that release don’t appear here.

Resource Types

• RayCluster

• RayCronJob

• RayJob

• RayService

AuthMode

Underlying type: string

AuthMode describes the authentication mode for the Ray cluster.

Appears in:

• AuthOptions

Field	Description
disabled	AuthModeDisabled disables authentication.
token	AuthModeToken enables token-based authentication.

AuthOptions

AuthOptions defines the authentication options for a RayCluster.

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
enableK8sTokenAuth boolean	EnableK8sTokenAuth enables Kubernetes-delegated token authentication. When true, the RAY_ENABLE_K8S_TOKEN_AUTH environment variable is set to “true” across all Ray Pods, and Ray will delegate authentication to the K8s API server. NOTE: The Kubernetes ServiceAccount token mounted to Raylets must be granted the ray:write custom verb via RBAC for this to function correctly. WARNING: This feature is intended for standalone RayCluster objects and is currently unsupported for RayJob or RayService resources.
secretName string	SecretName is the name of the Secret that contains the authentication token. If set, KubeRay will skip generating a Secret object per RayCluster containing a token. The Secret must have a data key auth_token that contains the value of the token.
mode AuthMode	Mode specifies the authentication mode. Supported values are “disabled” and “token”. Defaults to “token”.		Enum: [disabled token]

AutoscalerOptions

AutoscalerOptions specifies optional configuration for the Ray autoscaler.

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
resources ResourceRequirements	Resources specifies optional resource request and limit overrides for the autoscaler container. Default values: 500m CPU request and limit. 512Mi memory request and limit.
image string	Image optionally overrides the autoscaler’s container image. This override is provided for autoscaler testing and development.
imagePullPolicy PullPolicy	ImagePullPolicy optionally overrides the autoscaler container’s image pull policy. This override is provided for autoscaler testing and development.
securityContext SecurityContext	SecurityContext defines the security options the container should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
idleTimeoutSeconds integer	IdleTimeoutSeconds is the number of seconds to wait before scaling down a worker pod which is not using Ray resources. Defaults to 60 (one minute). It is not read by the KubeRay operator but by the Ray autoscaler.
upscalingMode UpscalingMode	UpscalingMode is “Conservative”, “Default”, or “Aggressive.” Conservative: Upscaling is rate-limited; the number of pending worker pods is at most the size of the Ray cluster. Default: Upscaling is not rate-limited. Aggressive: An alias for Default; upscaling is not rate-limited. It is not read by the KubeRay operator but by the Ray autoscaler.		Enum: [Default Aggressive Conservative]
version AutoscalerVersion	Version is the version of the Ray autoscaler. Setting this to v1 will explicitly use autoscaler v1. Setting this to v2 will explicitly use autoscaler v2. If this isn’t set, the Ray version determines the autoscaler version. In Ray 2.47.0 and later, the default autoscaler version is v2. It’s v1 before that.		Enum: [v1 v2]
env EnvVar array	Optional list of environment variables to set in the autoscaler container.
envFrom EnvFromSource array	Optional list of sources to populate environment variables in the autoscaler container.
volumeMounts VolumeMount array	Optional list of volumeMounts. This is needed for enabling TLS for the autoscaler container.
command string array	Optional list overwrite the default command of the autoscaler container.
args string array	Optional to overwrite the default args of the autoscaler container.

AutoscalerVersion

Underlying type: string

Validation:

• Enum: [v1 v2]

Appears in:

• AutoscalerOptions

Field	Description
v1
v2

ClusterUpgradeOptions

These options are currently only supported for the IncrementalUpgrade type.

Appears in:

• RayServiceUpgradeStrategy

Field	Description	Default	Validation
maxSurgePercent integer	The capacity of serve requests the upgraded cluster should scale to handle each interval. Defaults to 100%.	100
stepSizePercent integer	The percentage of traffic to switch to the upgraded RayCluster at a set interval after scaling by MaxSurgePercent. StepSizePercent must be less than or equal to MaxSurgePercent.
intervalSeconds integer	The interval in seconds between transferring StepSize traffic from the old to new RayCluster.
gatewayClassName string	The name of the Gateway Class installed by the Kubernetes Cluster admin.

CollectorOptions

CollectorOptions defines settings for the history server collector sidecar.

Appears in:

• HistoryServerOptions

Field	Description	Default	Validation
image string	Image is the collector container image to be used (e.g. quay.io/kuberay/collector:latest).
imagePullPolicy PullPolicy	ImagePullPolicy is the pull policy for the collector image.
resources ResourceRequirements	Resources specifies computing resource requirements.
env EnvVar array	Env allows injecting custom environment variables into the collector container.

DeletionCondition

DeletionCondition specifies the trigger conditions for a deletion action. Exactly one of JobStatus or JobDeploymentStatus must be specified:

• JobStatus (application-level): Match the Ray job execution status.

• JobDeploymentStatus (infrastructure-level): Match the RayJob deployment lifecycle status. This is particularly useful for cleaning up resources when Ray jobs fail to be submitted.

Appears in:

• DeletionRule

Field	Description	Default	Validation
ttlSeconds integer	TTLSeconds is the time in seconds from when the JobStatus or JobDeploymentStatus reaches the specified terminal state to when this deletion action should be triggered. The value must be a non-negative integer.	0	Minimum: 0

DeletionPolicy

DeletionPolicy is the legacy single-stage deletion policy. Deprecated: This struct is part of the legacy API. Use DeletionRule for new configurations.

Appears in:

• DeletionStrategy

Field	Description	Default	Validation
policy DeletionPolicyType	Policy is the action to take when the condition is met. This field is logically required when using the legacy OnSuccess/OnFailure policies. It is marked as ‘+optional’ at the API level to allow the ‘deletionRules’ field to be used instead.		Enum: [DeleteCluster DeleteWorkers DeleteSelf DeleteNone]

DeletionPolicyType

Underlying type: string

Appears in:

• DeletionPolicy

• DeletionRule

Field	Description
DeleteCluster
DeleteWorkers
DeleteSelf
DeleteNone

DeletionRule

DeletionRule defines a single deletion action and its trigger condition. This is the new, recommended way to define deletion behavior.

Appears in:

• DeletionStrategy

Field	Description	Default	Validation
policy DeletionPolicyType	Policy is the action to take when the condition is met. This field is required.		Enum: [DeleteCluster DeleteWorkers DeleteSelf DeleteNone]
condition DeletionCondition	The condition under which this deletion rule is triggered. This field is required.

DeletionStrategy

DeletionStrategy configures automated cleanup after the RayJob reaches a terminal state. Two mutually exclusive styles are supported:

• Legacy: provide both onSuccess and onFailure (deprecated; removal planned for 1.6.0). May be combined with shutdownAfterJobFinishes and (optionally) global TTLSecondsAfterFinished.

• Rules: provide deletionRules (non-empty list). Rules mode is incompatible with shutdownAfterJobFinishes, legacy fields, and the global TTLSecondsAfterFinished (use per-rule condition.ttlSeconds instead).

Semantics:

• A non-empty deletionRules selects rules mode; empty lists are treated as unset.

• Legacy requires both onSuccess and onFailure; specifying only one is invalid.

• Global TTLSecondsAfterFinished > 0 requires shutdownAfterJobFinishes=true; therefore it cannot be used with rules mode or with legacy alone (no shutdown).

• Feature gate RayJobDeletionPolicy must be enabled when this block is present.

Validation:

• CRD XValidations prevent mixing legacy fields with deletionRules and enforce legacy completeness.

• Controller logic enforces rules vs shutdown exclusivity and TTL constraints.

• onSuccess/onFailure are deprecated; migration to deletionRules is encouraged.

Appears in:

• RayJobSpec

Field	Description	Default	Validation
onSuccess DeletionPolicy	OnSuccess is the deletion policy for a successful RayJob. Deprecated: Use deletionRules instead for more flexible, multi-stage deletion strategies. This field will be removed in release 1.6.0.
onFailure DeletionPolicy	OnFailure is the deletion policy for a failed RayJob. Deprecated: Use deletionRules instead for more flexible, multi-stage deletion strategies. This field will be removed in release 1.6.0.
deletionRules DeletionRule array	DeletionRules is a list of deletion rules, processed based on their trigger conditions. While the rules can be used to define a sequence, if multiple rules are overdue (e.g., due to controller downtime), the most impactful rule (e.g., DeleteSelf) will be executed first to prioritize resource cleanup.		MinItems: 1

GCSStorageDeletionPolicy

Underlying type: string

GCSStorageDeletionPolicy specifies what happens to the operator-managed GCS storage PVC when the owning RayCluster is deleted.

Validation:

• Enum: [DeleteWithCluster Retain]

Appears in:

• GcsEmbeddedStorage

Field	Description
DeleteWithCluster	DeleteWithClusterGCSStorageDeletionPolicy (the default) makes the operator-managed PVC a child of the RayCluster via an ownerReference, so it (and its RocksDB data) is garbage-collected together with the cluster.
Retain	RetainGCSStorageDeletionPolicy keeps the operator-managed PVC (and its data) after the owning RayCluster is deleted: the operator omits the ownerReference so the PVC outlives the cluster. Recover the GCS state by pointing a new cluster’s ClaimName at the retained PVC.

GcsEmbeddedStorage

GcsEmbeddedStorage configures the PVC backing the embedded RocksDB store.

RocksDB tolerates only a single writer at a time. The operator mounts the volume on the head Pod but does not itself enforce mutual exclusion, so when a volume can be attached to more than one Pod concurrently (see AccessModes) the caller is responsible for ensuring only one Ray head writes to it at a time.

Appears in:

• GcsFaultToleranceOptions

Field	Description	Default	Validation
claimName string	ClaimName is the name of an existing, user-provided PersistentVolumeClaim to use as the RocksDB store (“bring your own” PVC). When set, the operator consumes that PVC as-is: it does not create, delete, resize, or set ownerReferences on it – the user owns its entire lifecycle. Mutually exclusive with Size/StorageClassName/AccessModes (those configure an operator-managed PVC, which is used instead when ClaimName is empty). This is the supported path for persisting GCS state across a RayService zero-downtime upgrade: point every RayService generation at the same claim. (An operator-managed PVC is keyed by and owned by the RayCluster, so it is not reused across upgrades.) Because the old and new head Pods overlap during a zero-downtime upgrade, the claim must permit concurrent attach (ReadWriteMany) with externally-coordinated single-writer semantics, or an active-passive handoff where only one Pod attaches at once.
size Quantity	Size of the operator-managed PVC (e.g. “1Gi”). Ignored when ClaimName is set. Defaults to 1Gi. The operator-managed PVC is created once and not reconfigured in place; to change size/class/accessModes, delete the PVC (or switch to ClaimName). A warning event is emitted if this diverges from the live PVC.
storageClassName string	StorageClassName for the operator-managed PVC. Uses the cluster default StorageClass when omitted. Ignored when ClaimName is set.
accessModes PersistentVolumeAccessMode array	AccessModes for the operator-managed PVC. Defaults to [ReadWriteOnce]. Ignored when ClaimName is set. ReadWriteOnce is the sane default for a standalone RayCluster (one head Pod attaches at a time). ReadWriteMany is a valid choice when you need the volume attached to multiple Pods concurrently (e.g. to overlap the old and new head during a RayService upgrade); RocksDB still requires that only one of them writes at a time, which you must coordinate externally.
subPath string	SubPath mounts a subdirectory of the volume instead of its root.
deletionPolicy GCSStorageDeletionPolicy	DeletionPolicy controls the lifecycle of the operator-managed PVC relative to the owning RayCluster. Defaults to DeleteWithCluster. Ignored when ClaimName is set (the operator never owns a bring-your-own PVC, so it is never deleted or retained by the operator). Recovery after Retain: a PVC left behind by a Retain delete can be recovered either by pointing a new cluster’s ClaimName at it, or by recreating a RayCluster with the same name on the operator-managed path – the operator adopts the existing {cluster}-gcs-pvc and reuses its RocksDB state. To start from a fresh store instead, delete the leftover PVC first.		Enum: [DeleteWithCluster Retain]

GcsFaultToleranceBackend

Underlying type: string

GcsFaultToleranceBackend selects the GCS fault tolerance persistence backend.

Validation:

• Enum: [redis rocksdb]

Appears in:

• GcsFaultToleranceOptions

Field	Description
redis	GcsFTBackendRedis persists GCS metadata in an external Redis service.
rocksdb	GcsFTBackendRocksDB persists GCS metadata in an embedded RocksDB store on a persistent volume mounted on the head Pod.

GcsFaultToleranceOptions

GcsFaultToleranceOptions contains configs for GCS FT

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
backend GcsFaultToleranceBackend	Backend selects the GCS FT persistence backend. Defaults to “redis” for backward compatibility. Immutable: the backend cannot be switched on an existing RayCluster (doing so would swap the entire GCS store and head-Pod wiring, losing fault-tolerance state).		Enum: [redis rocksdb]
redisUsername RedisCredential
redisPassword RedisCredential
externalStorageNamespace string
redisAddress string	RedisAddress is the address of the external Redis service used when Backend is “redis”. It may alternatively be supplied via env vars/annotations.
storage GcsEmbeddedStorage	Storage configures the persistent volume backing the embedded RocksDB store. Only used when Backend is “rocksdb”.

HeadGroupSpec

HeadGroupSpec are the spec for the head pod

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
template PodTemplateSpec	Template is the exact pod template used in K8s deployments, statefulsets, etc.
headService Service	HeadService is the Kubernetes service of the head pod.
enableIngress boolean	EnableIngress indicates whether operator should create ingress object for head service or not.
ingressOptions IngressOptions	IngressOptions specifies optional ingress configuration for the head service.
resources object (keys:string, values:string)	Resources specifies the resource quantities for the head group. These values override the resources passed to rayStartParams for the group, but have no effect on the resources set at the K8s Pod container level.
labels object (keys:string, values:string)	Labels specifies the Ray node labels for the head group. These labels will also be added to the Pods of this head group and override the --labels argument passed to rayStartParams.
rayStartParams object (keys:string, values:string)	RayStartParams are the params of the start command: node-manager-port, object-store-memory, …
serviceType ServiceType	ServiceType is Kubernetes service type of the head service. it will be used by the workers to connect to the head pod

HistoryServerOptions

HistoryServerOptions used for history server related configuration

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
collectorOptions CollectorOptions	CollectorOptions used for collector sidecar configuration

IngressOptions

IngressOptions defines the host, path, and TLS configuration for the ingress generated for the head group.

Appears in:

• HeadGroupSpec

Field	Description	Default	Validation
host string	Host is the fully-qualified domain name used to route external traffic to the Ray head dashboard. When unset, the generated ingress rule matches any host.
path string	Path is the HTTP path that routes to the Ray head dashboard. When unset, the operator defaults it to “/”, which routes all traffic on the host to the dashboard.
pathType IngressPathType	PathType is the path matching mode applied to Path. When unset, the operator defaults it to “Prefix”, which works out of the box without a rewrite-target annotation or controller-specific regex support.		Enum: [Exact Prefix ImplementationSpecific]
tls IngressTLS array	TLS configures TLS termination for the generated ingress.

IngressPathType

Underlying type: string

Validation:

• Enum: [Exact Prefix ImplementationSpecific]

Appears in:

• IngressOptions

Field	Description
Exact
Prefix
ImplementationSpecific

JobSubmissionMode

Underlying type: string

Appears in:

• RayJobSpec

Field	Description
K8sJobMode
HTTPMode
InteractiveMode
SidecarMode

NetworkPolicyConfig

NetworkPolicyConfig defines network isolation settings for Ray cluster. All modes permit intra-cluster pod-to-pod traffic. DNS egress is not included automatically; see NetworkPolicyRules.EgressRules for why it must be added under DenyAll/DenyAllEgress.

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
mode NetworkPolicyMode	Mode controls the security level. All modes permit intra-cluster pod-to-pod traffic (DNS egress excluded, see EgressRules). - “DenyAll”: Denies all Ingress and Egress. - “DenyAllIngress”: Denies all Ingress. - “DenyAllEgress”: Denies all Egress.	DenyAll	Enum: [DenyAll DenyAllIngress DenyAllEgress]
head NetworkPolicyRules	Head specifies custom NetworkPolicy rules applied only to the head pod’s policy. The base head policy always allows intra-cluster traffic and (for K8sJobMode RayJob-owned clusters) the submitter pod. Rules here are appended to those base rules. Platforms that need operator dashboard access should add it here (e.g. via a mutating webhook).
worker NetworkPolicyRules	Worker specifies custom NetworkPolicy rules applied only to worker pods’ policy. The base worker policy always allows intra-cluster traffic. Rules here are appended to that base rule. Acts as the default for all worker groups; see WorkerGroups for per-group overrides.
workerGroups WorkerGroupNetworkPolicyRules array	WorkerGroups specifies per-worker-group NetworkPolicy rules, keyed by group name. If an entry exists for a worker group, it replaces (not merges with) Worker for that group. Worker groups without an entry fall back to Worker.

NetworkPolicyMode

Underlying type: string

NetworkPolicyMode is the type for network isolation mode constants.

Validation:

• Enum: [DenyAll DenyAllIngress DenyAllEgress]

Appears in:

• NetworkPolicyConfig

Field	Description
DenyAll	NetworkPolicyDenyAll denies all ingress and egress traffic.
DenyAllIngress	NetworkPolicyDenyAllIngress denies all ingress traffic.
DenyAllEgress	NetworkPolicyDenyAllEgress denies all egress traffic.

NetworkPolicyRules

NetworkPolicyRules defines custom ingress and egress rules for a NetworkPolicy.

Appears in:

• NetworkPolicyConfig

• WorkerGroupNetworkPolicyRules

Field	Description	Default	Validation
ingressRules NetworkPolicyIngressRule array	IngressRules specifies custom ingress rules appended to the base policy. Only meaningful when the mode includes ingress denial (DenyAll or DenyAllIngress).
egressRules NetworkPolicyEgressRule array	EgressRules specifies custom egress rules appended to the base policy. Only meaningful when the mode includes egress denial (DenyAll or DenyAllEgress). DNS egress is NOT added automatically: under DenyAll/DenyAllEgress you MUST add a DNS rule here (e.g. to kube-system pods labeled k8s-app=kube-dns on port 53), because Ray workers reach the head via its service FQDN and cannot resolve it without DNS. See the network-policy-deny-all sample.

RayCluster

RayCluster is the Schema for the RayClusters API

Field	Description	Default	Validation
apiVersion string	ray.io/v1
kind string	RayCluster
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec RayClusterSpec	Specification of the desired behavior of the RayCluster.

RayClusterSpec

RayClusterSpec defines the desired state of RayCluster

Appears in:

• RayCluster

• RayJobSpec

• RayServiceSpec

Field	Description	Default	Validation
upgradeStrategy RayClusterUpgradeStrategy	UpgradeStrategy defines the scaling policy used when upgrading the RayCluster
authOptions AuthOptions	AuthOptions specifies the authentication options for the RayCluster.
suspend boolean	Suspend indicates whether a RayCluster should be suspended. A suspended RayCluster will have head pods and worker pods deleted.
managedBy string	ManagedBy is an optional configuration for the controller or entity that manages a RayCluster. The value must be either ‘ray.io/kuberay-operator’ or ‘kueue.x-k8s.io/multikueue’. The kuberay-operator reconciles a RayCluster which doesn’t have this field at all or the field value is the reserved string ‘ray.io/kuberay-operator’, but delegates reconciling the RayCluster with ‘kueue.x-k8s.io/multikueue’ to the Kueue. The field is immutable.
autoscalerOptions AutoscalerOptions	AutoscalerOptions specifies optional configuration for the Ray autoscaler.
headServiceAnnotations object (keys:string, values:string)
enableInTreeAutoscaling boolean	EnableInTreeAutoscaling indicates whether operator should create in tree autoscaling configs
gcsFaultToleranceOptions GcsFaultToleranceOptions	GcsFaultToleranceOptions for enabling GCS FT
historyServerOptions HistoryServerOptions	HistoryServerOptions used for history server related configuration
networkPolicy NetworkPolicyConfig	NetworkPolicy specifies optional configuration for network isolation. When set, separate NetworkPolicies are created for head and worker pods. The reconciler always permits intra-cluster pod-to-pod traffic. Note: under DenyAll/DenyAllEgress, DNS egress is not added automatically; since Ray pods reach the head via its service FQDN, you must allow DNS egress via Head/Worker EgressRules or the cluster will fail to start.
tlsOptions TLSOptions	TLSOptions specifies optional TLS encryption settings for the RayCluster. If omitted or Enabled is false, TLS is disabled. When Enabled is true, the operator enables mTLS using cert-manager to provision and manage certificates. Requires the RayClusterMTLS feature gate on the operator.
headGroupSpec HeadGroupSpec	HeadGroupSpec is the spec for the head pod
rayVersion string	RayVersion is used to determine the command for the Kubernetes Job managed by RayJob
workerGroupSpecs WorkerGroupSpec array	WorkerGroupSpecs are the specs for the worker pods

RayClusterUpgradeStrategy

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
type RayClusterUpgradeType	Type represents the strategy used when upgrading the RayCluster Pods. Currently supports Recreate and None.		Enum: [Recreate None]

RayClusterUpgradeType

Underlying type: string

Validation:

• Enum: [Recreate None]

Appears in:

• RayClusterUpgradeStrategy

Field	Description
Recreate	During upgrade, Recreate strategy will delete all existing pods before creating new ones
None	No new pod will be created while the strategy is set to None

RayCronJob

RayCronJob is the Schema for the raycronjobs API

Field	Description	Default	Validation
apiVersion string	ray.io/v1
kind string	RayCronJob
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec RayCronJobSpec

RayCronJobSpec

Appears in:

• RayCronJob

Field	Description	Default	Validation
jobTemplate RayJobSpec	JobTemplate defines the job spec that will be created by cron scheduling
schedule string	Schedule is the cron schedule string
timeZone string	TimeZone is the time zone name for the given schedule. If not specified, default to the local time zone of the Kuberay Operator. Empty string is not allowed. The bundled version of the time zone database is used.		MinLength: 1
suspend boolean	Suspend tells the controller to suspend the scheduling, it does not apply to scheduled RayJob.

RayJob

RayJob is the Schema for the rayjobs API

Field	Description	Default	Validation
apiVersion string	ray.io/v1
kind string	RayJob
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec RayJobSpec

RayJobSpec

RayJobSpec defines the desired state of RayJob

Appears in:

• RayCronJobSpec

• RayJob

Field	Description	Default	Validation
activeDeadlineSeconds integer	ActiveDeadlineSeconds is the duration in seconds that the RayJob may be active before KubeRay actively tries to terminate the RayJob; value must be positive integer.
backoffLimit integer	Specifies the number of retries before marking this job failed. Each retry creates a new RayCluster.	0
rayClusterSpec RayClusterSpec	RayClusterSpec is the cluster template to run the job
submitterPodTemplate PodTemplateSpec	SubmitterPodTemplate is the template for the pod that will run ray job submit.
metadata object (keys:string, values:string)	Refer to Kubernetes API documentation for fields of metadata.
clusterSelector object (keys:string, values:string)	clusterSelector is used to select running rayclusters by labels
submitterConfig SubmitterConfig	Configurations of submitter k8s job.
managedBy string	ManagedBy is an optional configuration for the controller or entity that manages a RayJob. The value must be either ‘ray.io/kuberay-operator’ or ‘kueue.x-k8s.io/multikueue’. The kuberay-operator reconciles a RayJob which doesn’t have this field at all or the field value is the reserved string ‘ray.io/kuberay-operator’, but delegates reconciling the RayJob with ‘kueue.x-k8s.io/multikueue’ to the Kueue. The field is immutable.
deletionStrategy DeletionStrategy	DeletionStrategy automates post-completion cleanup. Choose one style or omit: - Legacy: both onSuccess & onFailure (deprecated; may combine with shutdownAfterJobFinishes and TTLSecondsAfterFinished). - Rules: deletionRules (non-empty) — incompatible with shutdownAfterJobFinishes, legacy fields, and global TTLSecondsAfterFinished (use per-rule condition.ttlSeconds). Global TTLSecondsAfterFinished > 0 requires shutdownAfterJobFinishes=true. Feature gate RayJobDeletionPolicy must be enabled when this field is set.
entrypoint string	Entrypoint represents the command to start execution.
runtimeEnvYAML string	RuntimeEnvYAML represents the runtime environment configuration provided as a multi-line YAML string.
jobId string	If jobId is not set, a new jobId will be auto-generated.
submissionMode JobSubmissionMode	SubmissionMode specifies how RayJob submits the Ray job to the RayCluster. In “K8sJobMode”, the KubeRay operator creates a submitter Kubernetes Job to submit the Ray job. In “HTTPMode”, the KubeRay operator sends a request to the RayCluster to create a Ray job. In “InteractiveMode”, the KubeRay operator waits for a user to submit a job to the Ray cluster. In “SidecarMode”, the KubeRay operator injects a container into the Ray head Pod that acts as the job submitter to submit the Ray job.	K8sJobMode
entrypointResources string	EntrypointResources specifies the custom resources and quantities to reserve for the entrypoint command.
entrypointNumCpus float	EntrypointNumCpus specifies the number of cpus to reserve for the entrypoint command.
entrypointNumGpus float	EntrypointNumGpus specifies the number of gpus to reserve for the entrypoint command.
ttlSecondsAfterFinished integer	TTLSecondsAfterFinished is the TTL to clean up RayCluster. It’s only working when ShutdownAfterJobFinishes set to true.	0
preRunningDeadlineSeconds integer	PreRunningDeadlineSeconds is the deadline in seconds for a RayJob to reach the Running state from when it is first initialized (StartTime). If the RayJob does not transition to Running within this time, it will be marked as Failed. This is useful for cleaning up jobs stuck in Initializing or Waiting states. If not set, there is no deadline. Value must be a positive integer.		Minimum: 1
shutdownAfterJobFinishes boolean	ShutdownAfterJobFinishes will determine whether to delete the ray cluster once rayJob succeed or failed.
suspend boolean	suspend specifies whether the RayJob controller should create a RayCluster instance If a job is applied with the suspend field set to true, the RayCluster will not be created and will wait for the transition to false. If the RayCluster is already created, it will be deleted. In case of transition to false a new RayCluster will be created.

RayService

RayService is the Schema for the rayservices API

Field	Description	Default	Validation
apiVersion string	ray.io/v1
kind string	RayService
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec RayServiceSpec

RayServiceSpec

RayServiceSpec defines the desired state of RayService

Appears in:

• RayService

Field	Description	Default	Validation
rayClusterDeletionDelaySeconds integer	RayClusterDeletionDelaySeconds specifies the delay, in seconds, before deleting old RayClusters. The default value is 60 seconds.		Minimum: 0
serviceUnhealthySecondThreshold integer	Deprecated: This field is not used anymore. ref: https://github.com/ray-project/kuberay/issues/1685
deploymentUnhealthySecondThreshold integer	Deprecated: This field is not used anymore. ref: https://github.com/ray-project/kuberay/issues/1685
serveService Service	ServeService is the Kubernetes service for head node and worker nodes who have healthy http proxy to serve traffics.
upgradeStrategy RayServiceUpgradeStrategy	UpgradeStrategy defines the scaling policy used when upgrading the RayService.
managedBy string	ManagedBy is an optional configuration for the controller or entity that manages a RayService. The value must be either ‘ray.io/kuberay-operator’ or ‘kueue.x-k8s.io/multikueue’. The kuberay-operator reconciles a RayService which doesn’t have this field at all or the field value is the reserved string ‘ray.io/kuberay-operator’, but delegates reconciling the RayService with ‘kueue.x-k8s.io/multikueue’ to the Kueue. The field is immutable.
serveConfigV2 string	Important: Run “make” to regenerate code after modifying this file Defines the applications and deployments to deploy, should be a YAML multi-line scalar string.
rayClusterConfig RayClusterSpec
excludeHeadPodFromServeSvc boolean	If the field is set to true, the value of the label ray.io/serve on the head Pod should always be false. Therefore, the head Pod’s endpoint will not be added to the Kubernetes Serve service.
suspend boolean	Suspend indicates whether the RayService should suspend its execution. When set to true, all Kubernetes resources owned by the RayService controller will be deleted. Setting it back to false will allow the RayService controller to recreate the resources.

RayServiceUpgradeStrategy

Appears in:

• RayServiceSpec

Field	Description	Default	Validation
type RayServiceUpgradeType	Type represents the strategy used when upgrading the RayService. Currently supports NewCluster, NewClusterWithIncrementalUpgrade and None.
clusterUpgradeOptions ClusterUpgradeOptions	ClusterUpgradeOptions defines the behavior of a NewClusterWithIncrementalUpgrade type. RayServiceIncrementalUpgrade feature gate must be enabled to set ClusterUpgradeOptions.

RayServiceUpgradeType

Underlying type: string

Appears in:

• RayServiceUpgradeStrategy

Field	Description
NewClusterWithIncrementalUpgrade	During upgrade, NewClusterWithIncrementalUpgrade strategy will create an upgraded cluster to gradually scale and migrate traffic to using Gateway API.
NewCluster	During upgrade, NewCluster strategy will create new upgraded cluster and switch to it when it becomes ready
None	No new cluster will be created while the strategy is set to None

RedisCredential

RedisCredential is the redis username/password or a reference to the source containing the username/password

Appears in:

• GcsFaultToleranceOptions

Field	Description	Default	Validation
valueFrom EnvVarSource
value string

ScaleStrategy

ScaleStrategy to remove workers

Appears in:

• WorkerGroupSpec

Field	Description	Default	Validation
workersToDelete string array	WorkersToDelete workers to be deleted

SubmitterConfig

Appears in:

• RayJobSpec

Field	Description	Default	Validation
backoffLimit integer	BackoffLimit of the submitter. In K8sJobMode, this is the K8s Job backoffLimit. In SidecarMode with SidecarSubmitterRestart enabled, this is the maximum container restart count.

TLSOptions

TLSOptions configures TLS encryption for the RayCluster. When TLSOptions is nil or Enabled is nil/false, TLS is disabled. When Enabled is true, the operator uses cert-manager to automatically provision a full PKI (self-signed CA, head and worker leaf certificates) and keeps certificates up to date as pod IPs change during autoscaling.

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether mTLS is active for this RayCluster. Defaults to false when omitted. Set to true to enable mTLS.

UpscalingMode

Underlying type: string

Validation:

• Enum: [Default Aggressive Conservative]

Appears in:

• AutoscalerOptions

WorkerGroupNetworkPolicyRules

WorkerGroupNetworkPolicyRules is NetworkPolicyRules bound to one worker group.

Appears in:

• NetworkPolicyConfig

Field	Description	Default	Validation
groupName string	GroupName matches WorkerGroupSpec.GroupName.		Required: {}
ingressRules NetworkPolicyIngressRule array	IngressRules specifies custom ingress rules appended to the base policy. Only meaningful when the mode includes ingress denial (DenyAll or DenyAllIngress).
egressRules NetworkPolicyEgressRule array	EgressRules specifies custom egress rules appended to the base policy. Only meaningful when the mode includes egress denial (DenyAll or DenyAllEgress). DNS egress is NOT added automatically: under DenyAll/DenyAllEgress you MUST add a DNS rule here (e.g. to kube-system pods labeled k8s-app=kube-dns on port 53), because Ray workers reach the head via its service FQDN and cannot resolve it without DNS. See the network-policy-deny-all sample.

WorkerGroupSpec

WorkerGroupSpec are the specs for the worker pods

Appears in:

• RayClusterSpec

Field	Description	Default	Validation
suspend boolean	Suspend indicates whether a worker group should be suspended. A suspended worker group will have all pods deleted. This is not a user-facing API and is only used by RayJob DeletionStrategy.
groupName string	we can have multiple worker groups, we distinguish them by name
replicas integer	Replicas is the number of desired Pods for this worker group. See https://github.com/ray-project/kuberay/pull/1443 for more details about the reason for making this field optional.	0
minReplicas integer	MinReplicas denotes the minimum number of desired Pods for this worker group.	0
maxReplicas integer	MaxReplicas denotes the maximum number of desired Pods for this worker group, and the default value is maxInt32.	2147483647
idleTimeoutSeconds integer	IdleTimeoutSeconds denotes the number of seconds to wait before the v2 autoscaler terminates an idle worker pod of this type. This value is only used with the Ray Autoscaler enabled and defaults to the value set by the AutoscalingConfig if not specified for this worker group.
priority integer	Priority influences which worker group the autoscaler prefers when multiple groups can satisfy the same resource demand. Higher priority groups are preferred for scale-up. Only honored by Ray Autoscaler v2 (Ray >= 2.56).	0
resources object (keys:string, values:string)	Resources specifies the resource quantities for this worker group. These values override the resources passed to rayStartParams for the group, but have no effect on the resources set at the K8s Pod container level.
labels object (keys:string, values:string)	Labels specifies the Ray node labels for this worker group. These labels will also be added to the Pods of this worker group and override the --labels argument passed to rayStartParams.
rayStartParams object (keys:string, values:string)	RayStartParams are the params of the start command: address, object-store-memory, …
template PodTemplateSpec	Template is a pod template for the worker
scaleStrategy ScaleStrategy	ScaleStrategy defines which pods to remove
numOfHosts integer	NumOfHosts denotes the number of hosts to create per replica. The default value is 1.	1