View a markdown version of this page

Attaching Ray cluster to Space - Amazon SageMaker AI
PrerequisitesConnect a space to a Ray cluster with Amazon SageMaker StudioConnect a space to a Ray cluster with kubectlVerifyVersion compatibility

Attaching Ray cluster to Space

Attaching a Ray cluster to a space points your IDE or notebook session at that cluster, so ray.init() connects to it. Inside the space, the cluster is reachable on port 8265 for interactive development, the same port a local Ray cluster uses. You get the experience of running Ray on a laptop, with cloud-scale compute behind it.

You manage the connection from the Ray cluster tab inside the space.

Prerequisites

  • (Optional) Amazon SageMaker Studio configured for your cluster. For more information, see Setting up Studio for Ray.

  • The SageMaker Spaces add-on is Active. For more information, see Setting up the Spaces add-on.

  • A JupyterLab or Code Editor space, created from the IDE and Notebooks tab in Amazon SageMaker Studio.

  • A running Ray cluster in the same namespace as the space pods.

Connect a space to a Ray cluster with Amazon SageMaker Studio

To attach a space to a Ray cluster

  1. Open the JupyterLab or Code Editor space you created under the IDE and Notebooks tab in Studio, then choose the Ray cluster tab.

  2. Choose Connect.

  3. Choose an existing cluster from the picker, or create a new one, then save.

Use Change to point the space at a different cluster, and Disconnect to detach it.

Important

Saving a connection change restarts the space pods. Save unsaved work first.

Connect a space to a Ray cluster with kubectl

You can also patch the space's Workspace resource with kubectl instead of using Studio. The Ray integration template lives in the jupyter-k8s-system namespace, and you pass the Ray cluster name as a parameter.

Replace the following values in both commands:

Placeholder Replace with
my-workspace The name of the space's Workspace resource.
my-namespace The namespace that holds both the space and the Ray cluster.
my-cluster The name of the RayCluster to attach.

Leave ray-integration and jupyter-k8s-system as they are. They identify the integration template the add-on installs.

kubectl patch workspace my-workspace -n my-namespace --type=merge -p '{
  "spec": {
    "integrationTemplateRefs": [
      {
        "name": "ray-integration",
        "namespace": "jupyter-k8s-system",
        "parameters": [
          { "name": "rayClusterName", "value": "my-cluster" }
        ]
      }
    ]
  }
}'

To detach the space from its cluster, clear the integration references.

kubectl patch workspace my-workspace -n my-namespace --type=merge -p '{"spec":{"integrationTemplateRefs":[]}}'

Verify

After you connect the space, ray.init() and ray job submit reach the attached cluster by default. Open a terminal or notebook in the space and run ray.init(). Confirm that it connects to the cluster.

Version compatibility

The space's SageMaker AI Distribution image carries its own Ray version, and it must match the cluster's spec.rayVersion. When the versions differ, Studio shows a warning and offers to create a compatible cluster instead.

The Python version must match as well, including the patch version. A space running Python 3.11.9 and a cluster running Python 3.11.4 are not compatible.

A version mismatch surfaces as errors during development. For a simpler experience you can choose the same SageMaker AI Distribution image for both the Ray cluster and the Space Image to ensure compatibility.