KubeRay APIServer V1 (deprecated)

March 16, 2026 ยท View on GitHub

Warning

KubeRay APIServer V1 is deprecated and will be removed in the future. Please use KubeRay APIServer V2 instead.

The KubeRay APIServer offers gRPC and HTTP APIs to manage KubeRay resources.

Introduction

The KubeRay APIServer is an optional component that provides a layer of simplified configuration for KubeRay resources. Some organizations use the KubeRay APIServer internally to support user interfaces for managing KubeRay resources.

Installation

Install with Helm

Ensure that the version of Helm is v3+. Currently, existing CI tests are based on Helm v3.4.1 and v3.9.4.

helm version

Create a Kubernetes cluster

Create a local Kubernetes cluster using Kind. If you already have a Kubernetes cluster, you can skip this step.

kind create cluster --image=kindest/node:v1.29.0

Install KubeRay Operator

Refer to this document to install the latest stable KubeRay operator.

Install KubeRay APIServer

Refer to this document to install the latest stable KubeRay operator and APIServer (without the security proxy) from the Helm repository.

Important

If you install APIServer with security proxy, you may receive an "Unauthorized" error when making a request. Please add an authorization header to the request: -H 'Authorization: 12345' or install the APIServer without a security proxy.

Port-forwarding the APIServer service

Use the following command for port-forwarding to access the APIServer through port 31888:

kubectl port-forward service/kuberay-apiserver-service 31888:8888

For Development: Start a Local APIServer

You can build and start the APIServer from scratch in your local environment with a single command. This will deploy all the necessary components to a local kind cluster.

make start-local-apiserver

Verify the installation

The APIServer supports HTTP requests, so you can easily verify its successful startup by issuing two simple curl commands.

# Create complete template.
curl --silent -X 'POST' \
    'http://localhost:31888/apis/v1/namespaces/ray-system/compute_templates' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "default-template",
        "namespace": "ray-system",
        "cpu": 2,
        "memory": 4
      }'

# Check whether compute template is created successfully.
curl --silent -X 'GET' \
    'http://localhost:31888/apis/v1/namespaces/ray-system/compute_templates' \
    -H 'accept: application/json'

Usage

After deployment, you can use the {{baseUrl}} to access the service. Refer to the Swagger support section for complete API definitions.

  • (default) for NodePort access, use port 31888 for connection

  • for ingress access, you will need to create your own ingress

Details of the request parameters can be found in KubeRay Swagger. This README provides only basic examples.

Setup a smoke test

The following steps allow you to validate the integration of the KubeRay APIServer components and the KubeRay Operator in your environment.

  1. (Optional) You may use your local kind cluster or minikube

    cat <<EOF | kind create cluster --name ray-test --config -
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.29.0
  kubeadmConfigPatches:
    - |
      kind: InitConfiguration
      nodeRegistration:
        kubeletExtraArgs:
          node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 30265
    hostPort: 8265
    listenAddress: "0.0.0.0"
    protocol: tcp
  - containerPort: 30001
    hostPort: 10001
    listenAddress: "0.0.0.0"
    protocol: tcp
  - containerPort: 8000
    hostPort: 8000
    listenAddress: "0.0.0.0"
  - containerPort: 31888
    hostPort: 31888
    listenAddress: "0.0.0.0"
  - containerPort: 31887
    hostPort: 31887
    listenAddress: "0.0.0.0"
- role: worker
  image: kindest/node:v1.29.0
- role: worker
  image: kindest/node:v1.29.0
EOF

  2. Deploy the KubeRay APIServer within the same cluster of KubeRay operator

    helm repo add kuberay https://ray-project.github.io/kuberay-helm/
helm -n ray-system install kuberay-apiserver kuberay/kuberay-apiserver -n ray-system --create-namespace

  3. The APIServer exposes its service using NodePort by default. You can test access via your host and port; the default port is set to 31888. The examples below assume a kind (localhost) deployment. If the KubeRay APIServer is deployed on another type of cluster, you'll need to adjust the hostname to match your environment.

    curl localhost:31888
...
{
  "code": 5,
  "message": "Not Found"
}

  4. You can create RayCluster, RayJobs, or RayService by accessing the endpoints.

Swagger Support

The KubeRay APIServer supports Swagger UI. The Swagger page can be accessed at:

HTTP definition endpoints

The APIServer supports HTTP requests. For detailed specifications, check out the full spec document.

Advanced Usage