Skip to content

Commit

Permalink
revise documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@questcollector
questcollector committed Oct 11, 2024
1 parent 1483efa commit dd3154b
Showing 1 changed file with 68 additions and 47 deletions.
115 changes: 68 additions & 47 deletions website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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:"
]
},
{
Expand All @@ -67,9 +86,7 @@
"metadata": {},
"outputs": [],
"source": [
"%pip install 'pyautogen[kubernetes]'\n",
"# or\n",
"# pip install pyautogen 'kubernetes>=27'"
"pip install 'pyautogen[kubernetes]'"
]
},
{
Expand All @@ -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\""
]
},
{
Expand Down Expand Up @@ -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",
Expand All @@ -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:"
]
},
{
Expand Down Expand Up @@ -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"
]
},
Expand All @@ -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}"
]
},
Expand All @@ -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."
]
},
{
Expand All @@ -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",
Expand All @@ -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."
]
},
{
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -331,7 +349,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"PodCommandLineCodeExecutor can be integrated with Agents."
"`PodCommandLineCodeExecutor` can be integrated with Agents."
]
},
{
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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:"
]
},
{
Expand All @@ -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"
]
},
Expand All @@ -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"
]
Expand All @@ -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"
]
Expand All @@ -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."
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down

0 comments on commit dd3154b

Please sign in to comment.