diff --git a/website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb b/website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb index e8b68d93471..3af3f5fc60f 100644 --- a/website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb +++ b/website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb @@ -11,17 +11,19 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The `PodCommandLineCodeExecutor` of the autogen.coding.kubernetes module is to execute a code block using a pod in Kubernetes.\n", - "It is like DockerCommandLineCodeExecutor, but creates container on kubernetes Pod.\n", + "The `PodCommandLineCodeExecutor` in the `autogen.coding.kubernetes` module is designed to execute code blocks using a pod in Kubernetes.\n", + "It functions similarly to the `DockerCommandLineCodeExecutor`, but specifically creates container within Kubernetes environments.\n", "\n", "There are two condition to use PodCommandLineCodeExecutor.\n", - "- accessible to kubernetes cluster\n", - "- install autogen with extra feature kubernetes\n", + "- Access to a Kubernetes cluster\n", + "- installation `autogen` with the extra requirements `'pyautogen[kubernetes]'`\n", "\n", - "This documents uses minikube cluster on local environment.\n", - "You can refer to the link below for installation and execution of minikube.\n", + "For local development and testing, this document uses a Minikube cluster.\n", "\n", - "https://minikube.sigs.k8s.io/docs/start/" + "Minikube is a tool that allows you to run a single-node Kubernetes cluster on you local machine. \n", + "You can refer to the link below for installation and setup of Minikube.\n", + "\n", + "🔗 https://minikube.sigs.k8s.io/docs/start/" ] }, { @@ -37,9 +39,9 @@ "source": [ "There are four options PodCommandLineCodeExecutor to access kubernetes API server.\n", "- default kubeconfig file path: `~/.kube/config`\n", - "- To provide kubeconfig file path to `kube_config_file` argument of `PodCommandLineCodeExecutor`.\n", - "- To provide kubeconfig file path to `KUBECONFIG` environment variable.\n", - "- To provide token from kubernetes ServiceAccount which has enough permissions" + "- Provide a custom kubeconfig file path using the `kube_config_file` argument of `PodCommandLineCodeExecutor`.\n", + "- Set the kubeconfig file path using the `KUBECONFIG` environment variable.\n", + "- Provide token from Kubernetes ServiceAccount with sufficient permissions" ] }, { @@ -48,7 +50,7 @@ "source": [ "Generally, if kubeconfig file is located in `~/.kube/config`, there's no need to provide kubeconfig file path on parameter or environment variables.\n", "\n", - "the Tutorial of providing ServiceAccount Token is in the last section" + "The tutorial of providing ServiceAccount Token is in the last section" ] }, { @@ -57,8 +59,25 @@ "source": [ "## Example\n", "\n", - "In order to use kubernetes Pod based code executor, kubernetes python sdk is required.\n", - "It can be installed by `pip install 'kubernetes>=27'` or with the extra kubernetes" + "In order to use kubernetes Pod based code executor, you need to install Kubernetes Python SDK.\n", + "\n", + "You can do this by running the following command:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "pip install 'kubernetes>=27'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively, you can install it with the extra features for Kubernetes:" ] }, { @@ -67,9 +86,7 @@ "metadata": {}, "outputs": [], "source": [ - "%pip install 'pyautogen[kubernetes]'\n", - "# or\n", - "# pip install pyautogen 'kubernetes>=27'" + "pip install 'pyautogen[kubernetes]'" ] }, { @@ -85,10 +102,10 @@ "metadata": {}, "outputs": [], "source": [ - "# import os\n", - "# # If kubeconfig file is not located on ~/.kube/config but other path, \n", - "# # you can set path of kubeconfig file on KUBECONFIG environment variables \n", - "# os.environ[\"KUBECONFIG\"] = \"kubeconfig/file/path\"" + "import os\n", + "# Set the KUBECONFIG environment variable \n", + "# if the kubeconfig file is not in the default location(~/.kube/cofig).\n", + "os.environ[\"KUBECONFIG\"] = \"path/to/your/kubeconfig\"" ] }, { @@ -121,6 +138,7 @@ " ) as executor:\n", " print(\n", " executor.execute_code_blocks(\n", + " # Example of executing a simple Python code block within a Kubernetes pod.\n", " code_blocks=[\n", " CodeBlock(language=\"python\", code=\"print('Hello, World!')\"),\n", " ]\n", @@ -132,9 +150,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "With context manager(with statement), the pod created by PodCommandLineCodeExecutor deleted automatically after tasks done.\n", + "Using a context manager(the `with` statement), the pod created by `PodCommandLineCodeExecutor` is automatically deleted after the tasks are completed.\n", "\n", - "To delete the pod manually, you can use `stop()` method" + "Although the pod is automatically deleted when using a context manager, you might sometimes need to delete it manually. You can do this using `stop()` method, as shown below:" ] }, { @@ -162,7 +180,8 @@ ], "source": [ "%%bash\n", - "# default pod name is autogen-code-exec-{uuid.uuid4()}\n", + "# This command lists all pods in the default namespace. \n", + "# The default pod name follows the format autogen-code-exec-{uuid.uuid4()}.\n", "kubectl get pod -n default" ] }, @@ -181,7 +200,8 @@ ], "source": [ "%%bash\n", - "# default container image is python:3-slim\n", + "# This command shows container's image in the pod.\n", + "# The default container image is python:3-slim\n", "kubectl get pod autogen-code-exec-afd217ac-f77b-4ede-8c53-1297eca5ec64 -o jsonpath={.spec.containers[0].image}" ] }, @@ -198,11 +218,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "If you use another container image for code executor pod, you can provide image tag to `image` argument.\n", + "To use a different container image for code executor pod, specify the desired image tag using `image` argument.\n", "\n", - "PodCommandLineCode Executor has default execution policy that allows python and shell script code blocks.\n", - "\n", - "It can be allowed other languages with `execution_policies` argument." + "`PodCommandLineCodeExecutor` has a default execution policy that allows Python and shell script code blocks. You can enable other languages with `execution_policies` argument." ] }, { @@ -220,11 +238,11 @@ ], "source": [ "with PodCommandLineCodeExecutor(\n", - " image=\"node:22-alpine\", # you can provide runtime environments through container image\n", + " image=\"node:22-alpine\", # Specifies the runtime environments using a container image\n", " namespace=\"default\",\n", - " work_dir=\"./app\", # workspace directory for code block files\n", - " timeout=10, # timeout(seconds) value for waiting pod creation, execution of code blocks. default is 60 seconds\n", - " execution_policies = {\"javascript\": True} # allowed execution languages can be updated with execution_policy dictionary\n", + " work_dir=\"./app\", # Directory within the container where code block files are stored\n", + " timeout=10, # Timeout in seconds for pod creation and code block execution (default is 60 seconds)\n", + " execution_policies = {\"javascript\": True} # Enable execution of Javascript code blocks by updating execution policies\n", ") as executor:\n", " print(\n", " executor.execute_code_blocks(\n", @@ -239,10 +257,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "If you want to give custom settings for executor pod, such as annotations, environment variables, commands, volumes etc., \n", - "you can provide custom pod specification with `kubernetes.client.V1Pod` format.\n", + "If you want to apply custom settings for executor pod, such as annotations, environment variables, commands, volumes etc., \n", + "you can provide a custom pod specification using `kubernetes.client.V1Pod` format.\n", "\n", - "`container_name` argument should also be provided because PodCommandLineCodeExecutor do not automatically recognize a container where code blocks will be executed " + "The `container_name` argument should also be provided because `PodCommandLineCodeExecutor` does not automatically recognize the container where code blocks will be executed." ] }, { @@ -261,7 +279,7 @@ " containers=[client.V1Container(\n", " args=[\"-c\", \"while true;do sleep 5; done\"],\n", " command=[\"/bin/sh\"],\n", - " name=\"abcd\", # container name where code blocks will be executed should be provided to `container_name` argument\n", + " name=\"abcd\", # container name where code blocks will be executed should be provided using `container_name` argument\n", " image=\"python:3.11-slim\",\n", " env=[\n", " client.V1EnvVar(\n", @@ -299,7 +317,7 @@ "source": [ "with PodCommandLineCodeExecutor(\n", " pod_spec=pod, # custom executor pod spec\n", - " container_name=\"abcd\", # If custom executor pod spec is provided, container_name where code block will be executed should be specified\n", + " container_name=\"abcd\", # To use custom executor pod spec, container_name where code block will be executed should be specified\n", " work_dir=\"/autogen\",\n", " timeout=60,\n", ") as executor:\n", @@ -331,7 +349,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "PodCommandLineCodeExecutor can be integrated with Agents." + "`PodCommandLineCodeExecutor` can be integrated with Agents." ] }, { @@ -427,7 +445,7 @@ "from autogen import ConversableAgent\n", "\n", "# The code writer agent's system message is to instruct the LLM on how to\n", - "# use the Jupyter code executor with IPython kernel.\n", + "# use the code executor with python or shell script code\n", "code_writer_system_message = \"\"\"\n", "You have been given coding capability to solve tasks using Python code.\n", "In the following cases, suggest python code (in a python coding block) or shell script (in a sh coding block) for the user to execute.\n", @@ -585,11 +603,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "If a PodCommandLineCodeExecutor instance executes on inside of kubernetes Pod, instance can use token which is generated from ServiceAccount to access kubernetes API server.\n", + "If a `PodCommandLineCodeExecutor` instance runs inside of Kubernetes Pod, it can use a token generated from a ServiceAccount to access Kubernetes API server.\n", "\n", - "PodCommandLineCodeExecutor needs permissions of verbs `create`, `get`, `delete` on resource `pods`, and verb `get` for resources `pods/status`, `pods/exec`.\n", + "The `PodCommandLineCodeExecutor` requires the following permissions:\n", + "the verbs `create`, `get`, `delete` for `pods` resource, and the verb `get` for resources `pods/status`, `pods/exec`.\n", "\n", - "You can make ServiceAccount, ClusterRole and RoleBinding with kubectl." + "You can create a ServiceAccount, ClusterRole and RoleBinding with `kubectl` as shown below:" ] }, { @@ -607,7 +626,7 @@ ], "source": [ "%%bash\n", - "# create ServiceAccount on default namespace\n", + "# Create ServiceAccount on default namespace\n", "kubectl create sa autogen-executor-sa" ] }, @@ -626,7 +645,7 @@ ], "source": [ "%%bash\n", - "# create ClusterRole\n", + "# Create ClusterRole that has sufficient permissions\n", "kubectl create clusterrole autogen-executor-role \\\n", " --verb=get,create,delete --resource=pods,pods/status,pods/exec" ] @@ -646,7 +665,7 @@ ], "source": [ "%%bash\n", - "# create RoleBinding\n", + "# Create RoleBinding that binds ClusterRole and ServiceAccount\n", "kubectl create rolebinding autogen-executor-rolebinding \\\n", " --clusterrole autogen-executor-role --serviceaccount default:autogen-executor-sa" ] @@ -655,7 +674,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Pod with serviceAccount created before can be launched by below" + "A pod with a previously created ServiceAccount can be launched using the following command." ] }, { @@ -683,7 +702,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Execute PodCommandLineCodeExecutor in autogen-executor Pod" + "You can execute `PodCommandLineCodeExecutor` inside the Python interpreter process from `autogen-executor` Pod.\n", + "\n", + "It creates new pod for code execution using token generated from `autogen-executor-sa` ServiceAccount." ] }, {