demo-notebooks/guided-demos/0_basic_ray.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8d4a42f6",
   "metadata": {},
   "source": [
    "In this notebook, we will go through the basics of using the SDK to:\n",
    " - Spin up a Ray cluster with our desired resources\n",
    " - View the status and specs of our Ray cluster\n",
    " - Take down the Ray cluster when finished"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b55bc3ea-4ce3-49bf-bb1f-e209de8ca47a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import pieces from codeflare-sdk\n",
    "from codeflare_sdk import Cluster, ClusterConfiguration, TokenAuthentication"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "614daa0c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create authentication object for user permissions\n",
    "# IF unused, SDK will automatically check for default kubeconfig, then in-cluster config\n",
    "# KubeConfigFileAuthentication can also be used to specify kubeconfig path manually\n",
    "auth = TokenAuthentication(\n",
    "    token = \"XXXXX\",\n",
    "    server = \"XXXXX\",\n",
    "    skip_tls=False\n",
    ")\n",
    "auth.login()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc27f84c",
   "metadata": {},
   "source": [
    "Here, we want to define our cluster by specifying the resources we require for our batch workload. Below, we define our cluster object (which generates a corresponding RayCluster).\n",
    "\n",
    "NOTE: We must specify the `image` which will be used in our RayCluster, we recommend you bring your own image which suits your purposes. \n",
    "The example here is a community image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0f4bc870-091f-4e11-9642-cba145710159",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create and configure our cluster object\n",
    "# The SDK will try to find the name of your default local queue based on the annotation \"kueue.x-k8s.io/default-queue\": \"true\" unless you specify the local queue manually below\n",
    "cluster = Cluster(ClusterConfiguration(\n",
    "    name='raytest',\n",
    "    namespace='default', # Update to your namespace\n",
    "    num_workers=2,\n",
    "    min_cpus=1,\n",
    "    max_cpus=1,\n",
    "    min_memory=4,\n",
    "    max_memory=4,\n",
    "    num_gpus=0,\n",
    "    image=\"quay.io/project-codeflare/ray:latest-py39-cu118\",\n",
    "    write_to_file=False, # When enabled Ray Cluster yaml files are written to /HOME/.codeflare/resources \n",
    "    # local_queue=\"local-queue-name\" # Specify the local queue manually\n",
    "))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12eef53c",
   "metadata": {},
   "source": [
    "Next, we want to bring our cluster up, so we call the `up()` function below to submit our Ray Cluster onto the queue, and begin the process of obtaining our resource cluster."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0884bbc-c224-4ca0-98a0-02dfa09c2200",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Bring up the cluster\n",
    "cluster.up()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "657ebdfb",
   "metadata": {},
   "source": [
    "Now, we want to check on the status of our resource cluster, and wait until it is finally ready for use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c1b4311-2e61-44c9-8225-87c2db11363d",
   "metadata": {},
   "outputs": [],
   "source": [
    "cluster.status()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a99d5aff",
   "metadata": {},
   "outputs": [],
   "source": [
    "cluster.wait_ready()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "df71c1ed",
   "metadata": {},
   "outputs": [],
   "source": [
    "cluster.status()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3a55fe4",
   "metadata": {},
   "source": [
    "Let's quickly verify that the specs of the cluster are as expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7fd45bc5-03c0-4ae5-9ec5-dd1c30f1a084",
   "metadata": {},
   "outputs": [],
   "source": [
    "cluster.details()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5af8cd32",
   "metadata": {},
   "source": [
    "Finally, we bring our resource cluster down and release/terminate the associated resources, bringing everything back to the way it was before our cluster was brought up."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5f36db0f-31f6-4373-9503-dc3c1c4c3f57",
   "metadata": {},
   "outputs": [],
   "source": [
    "cluster.down()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0d41b90e",
   "metadata": {},
   "outputs": [],
   "source": [
    "auth.logout()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.18"
  },
  "vscode": {
   "interpreter": {
    "hash": "f9f85f796d01129d0dd105a088854619f454435301f6ffec2fea96ecbd9be4ac"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}