CodeFlare SDK

0.37.0 verified Sat May 09 auth: no python

Python SDK for CodeFlare, providing high-level abstractions to deploy and manage Ray clusters on Kubernetes, with integrated job submission and resource management. Current version 0.37.0, requires Python >=3.11, <4.0, and is actively maintained with monthly releases.

pip install codeflare-sdk

Common errors

error ModuleNotFoundError: No module named 'codeflare' ↓

cause Incorrect import path; the package is named 'codeflare_sdk', not 'codeflare'.

fix

Install the package (pip install codeflare-sdk) and import as 'from codeflare_sdk import Cluster'.

error ValueError: Invalid cluster name 'MyCluster_1'. Must be a valid Kubernetes resource name ↓

cause Cluster name contains uppercase letters or underscores, which violates RFC 1123.

fix

Use a lowercase name with only hyphens and alphanumeric characters, e.g., 'mycluster-1'.

error ClusterError: Failed to get RayCluster resource: 'appwrapper.codeflare.codeflare.dev "..." not found' ↓

cause AppWrapper CRD is no longer available in the cluster; requires Kuberay operator.

fix

Ensure Kuberay operator is installed and use ClusterConfiguration without AppWrapper-related settings.

Warnings

breaking AppWrapper support removed in v0.34.0. Instantiation of Ray clusters now relies solely on Kuberay operator; any code using AppWrapper objects will break. ↓

fix Migrate to Kuberay-based configurations. Remove any AppWrapper references.

breaking In v0.33.0, the immutable image tag for Ray was updated to Ray v2.52.1. Clusters created with older SDK versions (pre-0.33.0) may fail if the operator is not updated. ↓

fix Upgrade the Kuberay operator to a compatible version. Ensure Ray image aligns with the SDK's default.

gotcha Cluster name must be a valid Kubernetes resource name (lowercase RFC 1123 subdomain). Since v0.36.0, invalid names cause early errors. ↓

fix Use only lowercase alphanumeric characters and hyphens; no underscores or uppercase.

deprecated Usage of 'codeflare-operator' is deprecated; all operator references have been replaced with 'kuberay' in v0.35.0. Old cluster configurations may stop working. ↓

fix Replace any references to codeflare-operator with kuberay in your cluster configuration or environment.

Imports

Cluster
wrong
```
from codeflare.cluster import Cluster
```
correct
```
from codeflare_sdk import Cluster
```
Wrong module name: the correct package is 'codeflare_sdk', not 'codeflare'.
ClusterConfiguration
wrong
```
from codeflare_sdk.config import ClusterConfiguration
```
correct
```
from codeflare_sdk import ClusterConfiguration
```
ClusterConfiguration is exported from the top-level package, not from a submodule.

Quickstart

Create a Ray cluster on Kubernetes, run a remote function, and tear down.

from codeflare_sdk import Cluster, ClusterConfiguration
import os

# Define cluster configuration
config = ClusterConfiguration(
    name='example-cluster',
    namespace='default',
    num_workers=2,
    head_cpus='500m',
    head_memory='2Gi',
    worker_cpus='1',
    worker_memory='4Gi',
    min_workers=1,
    max_workers=4,
)

# Create and start the cluster
cluster = Cluster(config)
cluster.up()
# Wait for cluster to be ready
cluster.wait_ready()
print(f"Ray URI: {cluster.cluster_uri()}")
# Submit a simple Ray job
import ray
ray.init(cluster.cluster_uri())
@ray.remote
def hello():
    return "Hello from Ray cluster"
print(ray.get(hello.remote()))
# Tear down
cluster.down()