diff --git a/docs/authentication.md b/docs/authentication.md index bb27f1716..14eee4a82 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -4,7 +4,7 @@ Authenticating with your cluster allows you to perform actions such as creating ## Method 1 Token Authentication This is how a typical user would authenticate to their cluster using `TokenAuthentication`. -``` +``` python from codeflare_sdk import TokenAuthentication auth = TokenAuthentication( @@ -26,7 +26,7 @@ If the user has not specifically authenticated through the SDK by other means su ## Method 3 Specifying a Kubernetes Config File A user can specify a config file via a different authentication class `KubeConfigFileAuthentication` for authenticating with the SDK.
This is what loading a custom config file would typically look like. -``` +``` python from codeflare_sdk import KubeConfigFileAuthentication auth = KubeConfigFileAuthentication( diff --git a/docs/cluster-configuration.md b/docs/cluster-configuration.md index 97068b490..317921b0c 100644 --- a/docs/cluster-configuration.md +++ b/docs/cluster-configuration.md @@ -31,9 +31,40 @@ The `labels={"exampleLabel": "example"}` parameter can be used to apply addition After creating their `cluster`, a user can call `cluster.up()` and `cluster.down()` to respectively create or remove the Ray Cluster. +## Parameters of the `ClusterConfiguration` +Below is a table explaining each of the `ClusterConfiguration` parameters and their default values. +| Name | Type | Description | Default | +| :--------- | :-------- | :-------- | :-------- | +| `name` | `str` | The name of the Ray Cluster/AppWrapper | Required - No default | +| `namespace` | `Optional[str]` | The namespace of the Ray Cluster/AppWrapper | `None` | +| `head_cpu_requests` | `Union[int, str]` | CPU resource requests for the Head Node | `2` | +| `head_cpu_limits` | `Union[int, str]` | CPU resource limits for the Head Node | `2` | +| `head_memory_requests` | `Union[int, str]` | Memory resource requests for the Head Node | `8` | +| `head_memory_limits` | `Union[int, str]` | Memory limits for the Head Node | `8` | +| `head_extended_resource_requests` | `Dict[str, Union[str, int]]` | Extended resource requests for the Head Node see example above | `{}` | +| `worker_cpu_requests` | `Union[int, str]` | CPU resource requests for the Worker Node | `1` | +| `worker_cpu_limits` | `Union[int, str]` | CPU resource limits for the Worker Node | `1` | +| `num_workers` | `int` | Number of Worker Nodes for the Ray Cluster | `1` | +| `worker_memory_requests` | `Union[int, str]` | Memory resource requests for the Worker Node | `8` | +| `worker_memory_limits` | `Union[int, str]` | Memory resource limits for the Worker Node | `8` | +| `appwrapper` | `bool` | A boolean that wraps the Ray Cluster in an AppWrapper when set to True | `False` | +| `envs` | `Dict[str, str]` | A dictionary of environment variables to set for the Ray Cluster | `{}` | +| `image` | `str` | A paramater for specifying the Ray Image | `""` | +| `image_pull_secrets` | `List[str]` | A Parameter for providing a list of Image Pull Secrets | `[]` | +| `write_to_file` | `bool` | A boolean for writing the Ray Cluster as a Yaml file if set to True | `False` | +| `verify_tls` | `bool` | A boolean indicating whether to verify TLS when connecting to the cluster | `True` | +| `labels` | `Dict[str, str]` | A dictionary of labels to apply to the cluster | `{}` | +| `worker_extended_resource_requests` | `Dict[str, Union[str, int]]` | Extended resource requests for the Worker Node see example above | `{}` | +| `extended_resource_mapping` | `Dict[str, str]` | A dictionary of custom resource mappings to map extended resource requests to RayCluster resource names | `{}` | +| `overwrite_default_resource_mapping` | `bool` | A boolean indicating whether to overwrite the default resource mapping | `False` | +| `local_queue` | `Optional[str]` | A parameter for specifying the Local Queue label for the Ray Cluster | `None` | + + + + ## Deprecating Parameters -The following parameters of the `ClusterConfiguration` are being deprecated in release `v0.22.0`. +The following parameters of the `ClusterConfiguration` are being deprecated. | Deprecated Parameter | Replaced By | | :--------- | :-------- | | `head_cpus` | `head_cpu_requests`, `head_cpu_limits` | diff --git a/docs/images/ui-buttons.png b/docs/images/ui-buttons.png new file mode 100644 index 000000000..a27492920 Binary files /dev/null and b/docs/images/ui-buttons.png differ diff --git a/docs/images/ui-view-clusters.png b/docs/images/ui-view-clusters.png new file mode 100644 index 000000000..259d2dc11 Binary files /dev/null and b/docs/images/ui-view-clusters.png differ diff --git a/docs/ray-cluster-interaction.md b/docs/ray-cluster-interaction.md new file mode 100644 index 000000000..6e17580bd --- /dev/null +++ b/docs/ray-cluster-interaction.md @@ -0,0 +1,67 @@ +# 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: +``` python +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. diff --git a/docs/ui-widgets.md b/docs/ui-widgets.md new file mode 100644 index 000000000..7136a484d --- /dev/null +++ b/docs/ui-widgets.md @@ -0,0 +1,29 @@ +# Jupyter UI Widgets +Below are some examples of the Jupyter UI Widgets that are included in the CodeFlare SDK.
+> [!NOTE] +> To use the widgets functionality you must be using the CodeFlare SDK in a Jupyter Notebook environment. + +## Cluster Up/Down Buttons +The Cluster Up/Down buttons appear after successfully initialising your [ClusterConfiguration](cluster-configuration.md#ray-cluster-configuration). +There are two buttons and a checkbox `Cluster Up`, `Cluster Down` and `Wait for Cluster?` which mimic the [cluster.up()](ray-cluster-interaction.md#clusterup), [cluster.down()](ray-cluster-interaction.md#clusterdown) and [cluster.wait_ready()](ray-cluster-interaction.md#clusterwait_ready) functionality. + +After initialising their `ClusterConfiguration` a user can select the `Wait for Cluster?` checkbox then click the `Cluster Up` button to create their Ray Cluster and wait until it is ready. The cluster can be deleted by clicking the `Cluster Down` button.
+ +An image of the up/down ui buttons + +## View Clusters UI Table +The View Clusters UI Table allows a user to see a list of Ray Clusters with information on their configuration including number of workers, CPU requests and limits along with the clusters status. + +An image of the view clusters ui table + +Above is a list of two Ray Clusters `raytest` and `raytest2` each of those headings is clickable and will update the table to view the selected Cluster's information. +There are three buttons under the table `Cluster Down`, `View Jobs` and `Open Ray Dashboard`.
+* The `Cluster Down` button will delete the selected Cluster. +* The `View Jobs` button will try to open the Ray Dashboard's Jobs view in a Web Browser. The link will also be printed to the console. +* The `Open Ray Dashboard` button will try to open the Ray Dashboard view in a Web Browser. The link will also be printed to the console. + +The UI Table can be viewed by calling the following function. +``` python +from codeflare_sdk import view_clusters +view_clusters() # Accepts namespace parameter but will try to gather the namespace from the current context +```