diff --git a/docs/cluster-configuration.md b/docs/cluster-configuration.md index 8ca4a2c26..abe59eae4 100644 --- a/docs/cluster-configuration.md +++ b/docs/cluster-configuration.md @@ -18,8 +18,7 @@ cluster = Cluster(ClusterConfiguration( worker_cpu_limits=1, # Default 1 worker_memory_requests=2, # Default 2 worker_memory_limits=2, # Default 2 - # image="", # Optional Field - machine_types=["m5.xlarge", "g4dn.xlarge"], + # image="", # Default quay.io/rhoai/ray:2.23.0-py39-cu121 labels={"exampleLabel": "example", "secondLabel": "example"}, )) ``` @@ -27,4 +26,4 @@ Note: 'quay.io/rhoai/ray:2.23.0-py39-cu121' is the default community image used The `labels={"exampleLabel": "example"}` parameter can be used to apply additional labels to the RayCluster resource. -After creating their `cluster`, a user can call `cluster.up()` and `cluster.down()` to respectively create or remove the Ray Cluster. +For detailed instructions on the various methods that can be called for interacting with Ray Clusters see [Ray Cluster Interaction](./ray_cluster_interaction.md). diff --git a/docs/ray_cluster_interaction.md b/docs/ray_cluster_interaction.md new file mode 100644 index 000000000..ad5309c90 --- /dev/null +++ b/docs/ray_cluster_interaction.md @@ -0,0 +1,71 @@ +# Ray Cluster Interaction + +The CodeFlare SDK offers multiple ways to interact with Ray Clusters including the below methods. + +## get_cluster() +The `get_cluster()` function is used to initialise a `Cluster` object from a pre-existing Ray Cluster/AppWrapper.
+Below is an example of it's usage: +``` +from codeflare_sdk import get_cluster +cluster = get_cluster(cluster_name="raytest", namespace="example", is_appwrapper=False, write_to_file=False) +-> output: Yaml resources loaded for raytest + +cluster.status() +-> output: + ๐Ÿš€ CodeFlare Cluster Status ๐Ÿš€ + + โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ + โ”‚ Name โ”‚ + โ”‚ raytest Active โœ… โ”‚ + โ”‚ โ”‚ + โ”‚ URI: ray://raytest-head-svc.example.svc:10001 โ”‚ + โ”‚ โ”‚ + โ”‚ Dashboard๐Ÿ”— โ”‚ + โ”‚ โ”‚ + โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ +(, True) + +cluster.down() + +cluster.up() # This function will create an exact copy of the retrieved Ray Cluster only if the Ray Cluster has been previously deleted. +``` + +These are the parameters the `get_cluster()` function accepts: +* `cluster_name: str # Required` -> The name of the Ray Cluster. +* `namespace: str # Default: "default"` -> The namespace of the Ray Cluster. +* `is_appwrapper: bool # Default: False` -> When set to `True` the function will attempt to retrieve an AppWrapper instead of a Ray Cluster. +* `write_to_file: bool # Default: False` -> When set to `True` the Ray Cluster/AppWrapper will be written to a file similar to how it is done in `ClusterConfiguration`. + +## list_all_queued() +The `list_all_queued()` function returns (and prints by default) a list of all currently queued-up Ray Clusters in a given namespace. +It accepts the following parameters: +* `namespace: str # Required` -> The namespace you want to retrieve the list from. +* `print_to_console: bool # Default: True` -> Allows the user to print the list to their console. +* `appwrapper: bool # Default: False` -> When set to `True` allows the user to list queued AppWrappers. + + + +## list_all_clusters() +The `list_all_clusters()` function will return a list of detailed descriptions of Ray Clusters to the console by default. It accepts the following parameters: +* `namespace: str # Required` -> The namespace you want to retrieve the list from. +* `print_to_console: bool # Default: True` -> A boolean that allows the user to print the list to their console. + +
+NOTE: The following methods require a `Cluster` object to be initialised see [Cluster Configuration](./cluster-configuration.md) + +## cluster.up() +The `cluster.up()` function creates a Ray Cluster in the given namespace. + +## cluster.down() +The `cluster.down()` function deletes the Ray Cluster in the given namespace. + +## cluster.status() +The `cluster.status()` function prints out the status of the Ray Cluster's state with a link to the Ray Dashboard. + +## cluster.details() +The `cluster.details()` function prints out a detailed description of the Ray Cluster's status, worker resources and a link to the Ray Dashboard. + +## cluster.wait_ready() +The `cluster.wait_ready()` function waits for the requested cluster to be ready, up to an optional timeout and checks every 5 seconds. It accepts the following parameters: +* `timeout: Optional[int] # Default: None` -> Allows the user to define a timeout for the `wait_ready()` function. +* `dashboard_check: bool # Default: True` -> If enabled the `wait_ready()` function will wait until the Ray Dashboard is ready too.