DocsICP FilingConsole
Documentation

GetRayCluster

Updated at:
Copy as MD
Product
My Favorites

Retrieves a Ray cluster.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

emr-serverless-spark:GetRayCluster

get

*All Resource

*

 None None

Request syntax

GET /api/v1/workspaces/{workspaceId}/rayCluster/{clusterId} HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example
workspaceId

string

No

The workspace ID.

w-d2d82aa09155
clusterId

string

No

The cluster ID.

ray-xxxxxxxxxx

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element

Type

Description

Example

object

Schema of Response

requestId

string

The request ID.

DD6B1B2A-5837-5237-ABE4-FF0C8944
clusterId

string

The Ray cluster ID.

ray-k7nm8ahl5te4tg91
name

string

The Ray cluster name.

myRayCluster
displayReleaseVersion

string

The Ray DPI engine version.

ray-1.0.0 (Ray 2.47.1, Python 3.12)
description

string

The description.

Ray Cluster for dev.
networkServiceName

string

The network connectivity name.

vpc
headSpec

object

The Ray cluster head node parameters.

queueName

string

The queue name.

root_queue
cpu

string

The number of CPU cores.

2
memory

string

The memory size, in GiB.

8Gi
enableAutoScaling

boolean

Indicates whether auto scaling is enabled for worker nodes.

false
idleTimeoutSeconds

integer

The idle timeout period for worker nodes after auto scaling is enabled.

60
replica

integer

The number of nodes.

1
gpuSpec

string

The GPU instance type.

ecs.gn6i-c4g1.xlarge
gftEnabled

boolean

Indicates whether GCS Fault Tolerance is enabled.

gftConfig

object

The GCS Fault Tolerance configuration.

redisUrl

string

The Redis address.

10.4.5.6:6789
redisUsername

string

The Redis username.

default
redisPassword

string

The Redis password.

123456
env

string

The environment variables.

MY_ENV=123456
rayStartParams

string

The Ray startup parameters.

--num-cpus=0
displayReleaseVersion

string

The Ray DPI engine version.

err-1.3.0 (Ray 2.55.1, Python 3.12)
state

string

The session status. Valid values:

  • Starting: starting.

  • Running: running.

  • Stopping: stopping.

  • Stopped: stopped.

  • Error: failed.

Valid values:

  • Stopped :

    Stopped.

  • Starting :

    Starting.

  • Running :

    Running.

  • Error :

    Error.

  • Stopping :

    Stopping.

Running
creator

string

The UID of the user who created the cluster.

202077646755523991
creatorName

string

The nickname of the creator.

Alice
modifier

string

The UID of the user who last updated the cluster.

202077646755523991
modifierName

string

The nickname of the modifier.

Alice
userId

string

The Alibaba Cloud account ID of the creator.

123456789012
dashboardUrl

string

The URL of the Ray cluster dashboard.

https://emr-ray-gateway-cn-hangzhou.aliyuncs.com/workspace/w-xxxxxxxx/raycluster/ray-xxxxxx/dashboard?token=xxxxxx
jobUrl

string

The public address for submitting Ray jobs.

https://emr-spark-ray-gateway-cn-hangzhou.aliyuncs.com
submitToken

string

The authentication token for submitting Ray jobs. Include this token in the request header as "ray-token": "token".

1d06484d3b424f7fa4ab7082a4076da2
modified

boolean

Indicates whether the configuration has been modified.

false
extraParam

string

The additional parameters in JSON format.

{}
message

string

The error message when the status is Error.

ok
instances

array<object>

The Ray cluster node IDs.

object

The Ray cluster node struct.

type

string

The node type.

Head
instanceId

string

The node ID.

ray-uiulpgow9xljim10-head-7cgta
containerState

string

The main container state.

Running
reason

string

The node information.

OOMKilled
phase

string

The node pod state.

Running
message

string

The node pod state information.

ok
startTime

integer

The start time. The value is a UNIX timestamp in milliseconds.

1762946698000
createTime

integer

The creation time. The value is a UNIX timestamp in milliseconds.

1735870116167
containerStateReason

string

The main container information.

ok
containerStateMessage

string

The main container state information.

ContainerExit
containerExitCode

integer

The main container exit code.

137
instanceId

string

The Ray cluster node IDs.

ray-k7nm8ahl5te4tg93-xxxxxxx
workerSpec

array<object>

The Ray cluster worker node information.

object

The Ray cluster worker node information struct.

groupName

string

The worker node group name.

WorkerGroup1
workerType

string

The worker node group type.

Valid values:

  • CPU :

    CPU worker.

CPU
replica

integer

The number of worker nodes.

2
queueName

string

The queue name.

root_queue
cpu

string

The number of CPU cores.

2
memory

string

The memory size, in GiB.

8Gi
minReplica

integer

The minimum number of workers.

1
maxReplica

integer

The maximum number of workers.

10
gpuSpec

string

The GPU instance type.

ecs.gn6i-c4g1.xlarge
displayReleaseVersion

string

The database engine version.

ray-1.2.0 (Ray 2.55.1, Python 3.12)
env

string

The Ray environment variables.

MY_ENV=12456
rayStartParams

string

The Ray startup parameters.

--num-cpus=0
startTime

integer

The start time. The value is a UNIX timestamp in milliseconds.

1750327083303
createTime

integer

The creation time. The value is a UNIX timestamp in milliseconds.

1750327083303
modifiedTime

integer

The update time. The value is a UNIX timestamp in milliseconds.

1754274541693
grpcEndpoint

string

The gRPC endpoint (internal network). The domain name in the endpoint can also be used to submit Ray jobs.

ray://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com:80
volumeIds

array

The list of managed file IDs.

string

The managed file ID.

vol-123456789
jobUrlInner

string

The internal network address for submitting Ray jobs.

http://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com

Examples

Success response

JSON format

{
  "requestId": "DD6B1B2A-5837-5237-ABE4-FF0C8944",
  "clusterId": "ray-k7nm8ahl5te4tg91",
  "name": "myRayCluster",
  "displayReleaseVersion": "ray-1.0.0 (Ray 2.47.1, Python 3.12)",
  "description": "Ray Cluster for dev.",
  "networkServiceName": "vpc",
  "headSpec": {
    "queueName": "root_queue",
    "cpu": "2",
    "memory": "8Gi",
    "enableAutoScaling": false,
    "idleTimeoutSeconds": 60,
    "replica": 1,
    "gpuSpec": "ecs.gn6i-c4g1.xlarge",
    "gftEnabled": false,
    "gftConfig": {
      "redisUrl": "10.4.5.6:6789",
      "redisUsername": "default",
      "redisPassword": "123456"
    },
    "env": "MY_ENV=123456",
    "rayStartParams": "--num-cpus=0",
    "displayReleaseVersion": "err-1.3.0 (Ray 2.55.1, Python 3.12)"
  },
  "state": "Running",
  "creator": "202077646755523991",
  "creatorName": "Alice",
  "modifier": "202077646755523991",
  "modifierName": "Alice",
  "userId": "123456789012",
  "dashboardUrl": "https://emr-ray-gateway-cn-hangzhou.aliyuncs.com/workspace/w-xxxxxxxx/raycluster/ray-xxxxxx/dashboard?token=xxxxxx",
  "jobUrl": "https://emr-spark-ray-gateway-cn-hangzhou.aliyuncs.com",
  "submitToken": "1d06484d3b424f7fa4ab7082a4076da2",
  "modified": false,
  "extraParam": "{}",
  "message": "ok",
  "instances": [
    {
      "type": "Head",
      "instanceId": "ray-uiulpgow9xljim10-head-7cgta",
      "containerState": "Running",
      "reason": "OOMKilled",
      "phase": "Running",
      "message": "ok",
      "startTime": 1762946698000,
      "createTime": 1735870116167,
      "containerStateReason": "ok",
      "containerStateMessage": "ContainerExit",
      "containerExitCode": 137
    }
  ],
  "instanceId": "ray-k7nm8ahl5te4tg93-xxxxxxx",
  "workerSpec": [
    {
      "groupName": "WorkerGroup1",
      "workerType": "CPU",
      "replica": 2,
      "queueName": "root_queue",
      "cpu": "2",
      "memory": "8Gi",
      "minReplica": 1,
      "maxReplica": 10,
      "gpuSpec": "ecs.gn6i-c4g1.xlarge",
      "displayReleaseVersion": "ray-1.2.0 (Ray 2.55.1, Python 3.12)",
      "env": "MY_ENV=12456",
      "rayStartParams": "--num-cpus=0"
    }
  ],
  "startTime": 1750327083303,
  "createTime": 1750327083303,
  "modifiedTime": 1754274541693,
  "grpcEndpoint": "ray://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com:80",
  "volumeIds": [
    "vol-123456789"
  ],
  "jobUrlInner": "http://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.