codeflare_sdk package

Subpackages

Submodules

codeflare_sdk.codeflare module

Single entrypoint for the CodeFlare SDK.

Usage:

from codeflare_sdk import ClusterConfiguration, Codeflare, SDKConfig from kube_authkit import AuthConfig

cf = Codeflare(config=SDKConfig(

auth=AuthConfig(method=”auto”), namespace=”my-project”,

))

cluster = cf.clusters.create(

ClusterConfiguration(name=”my-cluster”, num_workers=4)

) cluster.apply()

class codeflare_sdk.codeflare.ClusterHandler(sdk: Codeflare)[source]

Bases: object

Namespace accessor for Ray cluster operations.

create(config: ClusterConfiguration, namespace: str | None = None) → Cluster[source]

Create a new Cluster object (does not apply it to K8s yet).

Takes a ClusterConfiguration, the same object cf.jobs.create(cluster_config=...) and Cluster() take, so there is one way to describe a cluster across the SDK.

The returned Cluster is bound to this Codeflare instance’s Kubernetes client, so later operations on it are unaffected by any other Codeflare instance created afterwards.

Args:

config: Cluster configuration. config.name is required. namespace: K8s namespace, overriding config.namespace. See

namespace resolution precedence in _resolve_namespace().

Returns:

Cluster instance ready for .apply().

Raises:

ValueError: If config.name is unset, or no namespace can be resolved.

get(name: str, namespace: str | None = None, *, verify_tls: bool = True, write_to_file: bool = False) → Cluster[source]

Retrieve an existing cluster by name.

Args:

name: Cluster name. namespace: K8s namespace. See namespace resolution precedence in

_resolve_namespace().

verify_tls: Whether to verify TLS when connecting to the cluster. write_to_file: Whether to write the retrieved resource to a YAML file.

Returns:

Cluster instance bound to this instance’s Kubernetes client.

list(namespace: str | None = None) → list[source]

List all Ray clusters in a namespace.

Args:
namespace: K8s namespace. See namespace resolution precedence in

_resolve_namespace().

Returns:

List of RayCluster objects.

list_queued(namespace: str | None = None) → list[source]

List all queued Ray clusters in a namespace.

Args:
namespace: K8s namespace. See namespace resolution precedence in

_resolve_namespace().

Returns:

List of queued RayCluster objects.

class codeflare_sdk.codeflare.Codeflare(config: SDKConfig | None = None)[source]

Bases: object

Single entrypoint for the CodeFlare SDK.

Authenticates to Kubernetes via kube-authkit and provides namespace-accessor handlers for clusters and jobs.

Each instance owns its Kubernetes client, and every object created through it (cf.clusters.create(), cf.jobs.submit(), …) is bound to that client. Creating a second Codeflare instance therefore does not change which cluster the first instance’s objects talk to.

The module-level client is still set for backward compatibility, so direct APIs such as Cluster(config) that were not given an explicit client keep resolving the most recently created instance’s client as before.

Note: constructing a Codeflare instance means a client was created successfully; it does not prove the API server is reachable or the credentials are still valid.

Args:

config: SDK configuration. Defaults to auto-detection.

property client

The Kubernetes API client owned by this instance.

class codeflare_sdk.codeflare.JobHandler(sdk: Codeflare)[source]

Bases: object

Namespace accessor for RayJob operations.

create(name: str, entrypoint: str, namespace: str | None = None, *, cluster_name: str, **kwargs: Unpack[JobOptions]) → RayJob[source]
create(name: str, entrypoint: str, namespace: str | None = None, *, cluster_config: ClusterConfiguration, **kwargs: Unpack[JobOptions]) → RayJob

Create a RayJob without submitting it.

A job needs an execution target: pass exactly one of cluster_name (run on an existing cluster) or cluster_config (the job creates and manages its own cluster). The two overloads make “exactly one” a type error rather than only a runtime one.

Args:

name: Job name. entrypoint: Python script or command to run. cluster_name: Name of an existing Ray cluster to run on. cluster_config: Configuration for a cluster the job will manage. namespace: K8s namespace. See namespace resolution precedence in

_resolve_namespace().

runtime_env: Ray runtime environment, as a RuntimeEnv or dict. ttl_seconds_after_finished: Cleanup delay for managed clusters. active_deadline_seconds: Maximum job runtime before termination. local_queue: Kueue LocalQueue to submit to. priority_class: Kueue WorkloadPriorityClass name.

Returns:

RayJob instance (not yet submitted), bound to this instance’s client.

Raises:

ValueError: If neither or both of cluster_name/cluster_config given.

submit(name: str, entrypoint: str, namespace: str | None = None, *, cluster_name: str, **kwargs: Unpack[JobOptions]) → RayJob[source]
submit(name: str, entrypoint: str, namespace: str | None = None, *, cluster_config: ClusterConfiguration, **kwargs: Unpack[JobOptions]) → RayJob

Create and immediately submit a RayJob.

Takes the same arguments as create(); see there for the execution target requirement.

Returns:

Submitted RayJob instance, bound to this instance’s client.

Raises:

ValueError: If neither or both of cluster_name/cluster_config given.

class codeflare_sdk.codeflare.JobOptions[source]

Bases: TypedDict

Optional keyword arguments shared by the JobHandler overloads.

Holds every JobHandler.create() keyword except the execution target (cluster_name / cluster_config), which the overloads vary. Keeping them here means the overload pair does not restate the full signature.

test_job_options_match_create_signature fails if the two drift.

active_deadline_seconds: int | None
local_queue: str | None
priority_class: str | None
runtime_env: RuntimeEnv | Dict[str, Any] | None
ttl_seconds_after_finished: int
class codeflare_sdk.codeflare.SDKConfig(auth: ~kube_authkit.config.AuthConfig = <factory>, namespace: str | None = None, log_level: str = 'WARNING')[source]

Bases: object

Configuration for the CodeFlare SDK.

Args:

auth: kube-authkit AuthConfig for Kubernetes authentication. namespace: Default namespace for all operations. When unset, operations

fall back to the namespace of the current Kubernetes context, and raise if none can be determined. See _resolve_namespace.

log_level: Logging level for the codeflare_sdk logger.

auth: AuthConfig
log_level: str = 'WARNING'
namespace: str | None = None

codeflare_sdk.conftest module

Module contents