Skip to content

API Reference

Packages

ray.io/v1

Package v1 contains API Schema definitions for the ray v1 API group

Resource Types

AutoscalerOptions

AutoscalerOptions specifies optional configuration for the Ray autoscaler.

Appears in: - RayClusterSpec

Field Description
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 for provided for autoscaler testing and development.
imagePullPolicy PullPolicy ImagePullPolicy optionally overrides the autoscaler container's image pull policy. This override is for provided for autoscaler testing and development.
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.
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.

HeadGroupSpec

HeadGroupSpec are the spec for the head pod

Appears in: - RayClusterSpec

Field Description
serviceType ServiceType ServiceType is Kubernetes service type of the head service. it will be used by the workers to connect to the head pod
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.
rayStartParams object (keys:string, values:string) RayStartParams are the params of the start command: node-manager-port, object-store-memory, ...
template PodTemplateSpec Template is the exact pod template used in K8s depoyments, statefulsets, etc.

JobSubmissionMode

Underlying type: string

Appears in: - RayJobSpec

RayCluster

RayCluster is the Schema for the RayClusters API

Field Description
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
headGroupSpec HeadGroupSpec INSERT ADDITIONAL SPEC FIELDS - desired state of cluster Important: Run "make" to regenerate code after modifying this file HeadGroupSpecs are the spec for the head pod
workerGroupSpecs WorkerGroupSpec array WorkerGroupSpecs are the specs for the worker pods
rayVersion string RayVersion is used to determine the command for the Kubernetes Job managed by RayJob
enableInTreeAutoscaling boolean EnableInTreeAutoscaling indicates whether operator should create in tree autoscaling configs
autoscalerOptions AutoscalerOptions AutoscalerOptions specifies optional configuration for the Ray autoscaler.
headServiceAnnotations object (keys:string, values:string)
suspend boolean Suspend indicates whether a RayCluster should be suspended. A suspended RayCluster will have head pods and worker pods deleted.

RayJob

RayJob is the Schema for the rayjobs API

Field Description
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: - RayJob

Field Description
entrypoint string INSERT ADDITIONAL SPEC FIELDS - desired state of cluster Important: Run "make" to regenerate code after modifying this file
metadata object (keys:string, values:string) Refer to Kubernetes API documentation for fields of metadata.
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.
shutdownAfterJobFinishes boolean ShutdownAfterJobFinishes will determine whether to delete the ray cluster once rayJob succeed or failed.
ttlSecondsAfterFinished integer TTLSecondsAfterFinished is the TTL to clean up RayCluster. It's only working when ShutdownAfterJobFinishes set to true.
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.
rayClusterSpec RayClusterSpec RayClusterSpec is the cluster template to run the job
clusterSelector object (keys:string, values:string) clusterSelector is used to select running rayclusters by labels
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.
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.
submitterPodTemplate PodTemplateSpec SubmitterPodTemplate is the template for the pod that will run ray job submit.
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.
entrypointResources string EntrypointResources specifies the custom resources and quantities to reserve for the entrypoint command.

RayService

RayService is the Schema for the rayservices API

Field Description
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
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
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.

ScaleStrategy

ScaleStrategy to remove workers

Appears in: - WorkerGroupSpec

Field Description
workersToDelete string array WorkersToDelete workers to be deleted

UpscalingMode

Underlying type: string

Appears in: - AutoscalerOptions

WorkerGroupSpec

WorkerGroupSpec are the specs for the worker pods

Appears in: - RayClusterSpec

Field Description
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.
minReplicas integer MinReplicas denotes the minimum number of desired Pods for this worker group.
maxReplicas integer MaxReplicas denotes the maximum number of desired Pods for this worker group, and the default value is maxInt32.
numOfHosts integer NumOfHosts denotes the number of hosts to create per replica. The default value is 1.
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

ray.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the ray v1alpha1 API group

Resource Types

AutoscalerOptions

AutoscalerOptions specifies optional configuration for the Ray autoscaler.

Appears in: - RayClusterSpec

Field Description
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 for provided for autoscaler testing and development.
imagePullPolicy PullPolicy ImagePullPolicy optionally overrides the autoscaler container's image pull policy. This override is for provided for autoscaler testing and development.
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.
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.

HeadGroupSpec

HeadGroupSpec are the spec for the head pod

Appears in: - RayClusterSpec

Field Description
serviceType ServiceType ServiceType is Kubernetes service type of the head service. it will be used by the workers to connect to the head pod
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.
rayStartParams object (keys:string, values:string) RayStartParams are the params of the start command: node-manager-port, object-store-memory, ...
template PodTemplateSpec Template is the exact pod template used in K8s depoyments, statefulsets, etc.

RayCluster

RayCluster is the Schema for the RayClusters API

Field Description
apiVersion string ray.io/v1alpha1
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
headGroupSpec HeadGroupSpec INSERT ADDITIONAL SPEC FIELDS - desired state of cluster Important: Run "make" to regenerate code after modifying this file HeadGroupSpecs are the spec for the head pod
workerGroupSpecs WorkerGroupSpec array WorkerGroupSpecs are the specs for the worker pods
rayVersion string RayVersion is used to determine the command for the Kubernetes Job managed by RayJob
enableInTreeAutoscaling boolean EnableInTreeAutoscaling indicates whether operator should create in tree autoscaling configs
autoscalerOptions AutoscalerOptions AutoscalerOptions specifies optional configuration for the Ray autoscaler.
headServiceAnnotations object (keys:string, values:string)
suspend boolean Suspend indicates whether a RayCluster should be suspended. A suspended RayCluster will have head pods and worker pods deleted.

RayJob

RayJob is the Schema for the rayjobs API

Field Description
apiVersion string ray.io/v1alpha1
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: - RayJob

Field Description
entrypoint string INSERT ADDITIONAL SPEC FIELDS - desired state of cluster Important: Run "make" to regenerate code after modifying this file
metadata object (keys:string, values:string) Refer to Kubernetes API documentation for fields of metadata.
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.
shutdownAfterJobFinishes boolean ShutdownAfterJobFinishes will determine whether to delete the ray cluster once rayJob succeed or failed.
ttlSecondsAfterFinished integer TTLSecondsAfterFinished is the TTL to clean up RayCluster. It's only working when ShutdownAfterJobFinishes set to true.
rayClusterSpec RayClusterSpec RayClusterSpec is the cluster template to run the job
clusterSelector object (keys:string, values:string) clusterSelector is used to select running rayclusters by labels
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.
submitterPodTemplate PodTemplateSpec SubmitterPodTemplate is the template for the pod that will run ray job submit.
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.
entrypointResources string EntrypointResources specifies the custom resources and quantities to reserve for the entrypoint command.

RayService

RayService is the Schema for the rayservices API

Field Description
apiVersion string ray.io/v1alpha1
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
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
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.

ScaleStrategy

ScaleStrategy to remove workers

Appears in: - WorkerGroupSpec

Field Description
workersToDelete string array WorkersToDelete workers to be deleted

UpscalingMode

Underlying type: string

Appears in: - AutoscalerOptions

WorkerGroupSpec

WorkerGroupSpec are the specs for the worker pods

Appears in: - RayClusterSpec

Field Description
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.
minReplicas integer MinReplicas denotes the minimum number of desired Pods for this worker group.
maxReplicas integer MaxReplicas denotes the maximum number of desired Pods for this worker group, and the default value is maxInt32.
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